Struct Client 

pub struct Client { /* private fields */ }

Gel database client.

Internally it contains a connection pool.

To create a client, use create_client function (it gets database connection configuration from environment). You can also use Builder to build custom Config and create a client using that config.

The with_ methods (with_retry_options, with_transaction_options, etc.) let you create a shallow copy of the client with adjusted options.

Implementations

impl Client

pub fn new(config: &Config) -> Client

Create a new connection pool.

Note this does not create a connection immediately. Use ensure_connected() to establish a connection and verify that the connection is usable.

pub async fn ensure_connected(&self) -> Result<(), Error>

Ensure that there is at least one working connection to the pool.

This can be used at application startup to ensure that you have a working connection.

pub async fn query_verbose<R, A>( &self, query: impl AsRef<str> + Send, arguments: &A, ) -> Result<ResultVerbose<Vec<R>>, Error>

where A: QueryArgs, R: QueryResult,

Execute a query and return a collection of results and warnings produced by the server.

You will usually have to specify the return type for the query:

let greeting: (Vec<String>, _) = conn.query_with_warnings("select 'hello'", &()).await?;

This method can be used with both static arguments, like a tuple of scalars, and with dynamic arguments gel_protocol::value::Value. Similarly, dynamically typed results are also supported.

pub async fn query<R, A>( &self, query: impl AsRef<str> + Send, arguments: &A, ) -> Result<Vec<R>, Error>

where A: QueryArgs, R: QueryResult,

Execute a query and return a collection of results.

You will usually have to specify the return type for the query:

let greeting = pool.query::<String, _>("SELECT 'hello'", &());
// or
let greeting: Vec<String> = pool.query("SELECT 'hello'", &());

let two_numbers: Vec<i32> = conn.query("select {<int32>$0, <int32>$1}", &(10, 20)).await?;

This method can be used with both static arguments, like a tuple of scalars, and with dynamic arguments gel_protocol::value::Value. Similarly, dynamically typed results are also supported.

pub async fn query_single<R, A>( &self, query: impl AsRef<str> + Send, arguments: &A, ) -> Result<Option<R>, Error>

where A: QueryArgs, R: QueryResult + Send,

Execute a query and return a single result

You will usually have to specify the return type for the query:

let greeting = pool.query_single::<String, _>("SELECT 'hello'", &());
// or
let greeting: Option<String> = pool.query_single(
    "SELECT 'hello'",
    &()
);

This method can be used with both static arguments, like a tuple of scalars, and with dynamic arguments gel_protocol::value::Value. Similarly, dynamically typed results are also supported.

pub async fn query_required_single<R, A>( &self, query: impl AsRef<str> + Send, arguments: &A, ) -> Result<R, Error>

where A: QueryArgs, R: QueryResult + Send,

Execute a query and return a single result

The query must return exactly one element. If the query returns more than one element, a ResultCardinalityMismatchError is raised. If the query returns an empty set, a NoDataError is raised.

You will usually have to specify the return type for the query:

let greeting = pool.query_required_single::<String, _>(
    "SELECT 'hello'",
    &(),
);
// or
let greeting: String = pool.query_required_single(
    "SELECT 'hello'",
    &(),
);

This method can be used with both static arguments, like a tuple of scalars, and with dynamic arguments gel_protocol::value::Value. Similarly, dynamically typed results are also supported.

pub async fn query_json( &self, query: impl AsRef<str>, arguments: &impl QueryArgs, ) -> Result<Json, Error>

Execute a query and return the result as JSON.

pub async fn query_single_json( &self, query: impl AsRef<str>, arguments: &impl QueryArgs, ) -> Result<Option<Json>, Error>

Execute a query and return a single result as JSON.

The query must return exactly one element. If the query returns more than one element, a ResultCardinalityMismatchError is raised.

let query = "select <json>(
    insert Account {
    username := <str>$0
    }) {
    username,
    id
    };";
let json_res: Option<Json> = client
 .query_single_json(query, &("SomeUserName",))
    .await?;

pub async fn query_required_single_json( &self, query: impl AsRef<str>, arguments: &impl QueryArgs, ) -> Result<Json, Error>

Execute a query and return a single result as JSON.

The query must return exactly one element. If the query returns more than one element, a ResultCardinalityMismatchError is raised. If the query returns an empty set, a NoDataError is raised.

pub async fn execute<A>( &self, query: impl AsRef<str>, arguments: &A, ) -> Result<(), Error>

where A: QueryArgs,

Execute a query and don’t expect result

This method can be used with both static arguments, like a tuple of scalars, and with dynamic arguments gel_protocol::value::Value. Similarly, dynamically typed results are also supported.

pub async fn transaction<T, B, F>(&self, body: B) -> Result<T, Error>

where B: FnMut(RetryingTransaction) -> F, F: Future<Output = Result<T, Error>>,

Execute a transaction and retry.

Transaction body must be encompassed in the closure. The closure may be executed multiple times. This includes not only database queries but also executing the whole function, so the transaction code must be prepared to be idempotent.

Example

let conn = gel_tokio::create_client().await?;
let val = conn.transaction(|mut tx| async move {
    tx.query_required_single::<i64, _>("
        WITH C := UPDATE Counter SET { value := .value + 1}
        SELECT C.value LIMIT 1
        ", &()
    ).await
}).await?;

Commit and rollback

If the closure returns Result::Ok, the transaction is committed. If the closure returns Result::Err, the transaction is either retried or aborted, depending on weather the error has `SHOULD_RETRY`` tag set.

To manually abort a transaction, gel_errors::UserError can be returned:

use gel_errors::ErrorKind;
let val = conn.transaction(|mut tx| async move {
    tx.execute("UPDATE Foo SET { x := 1 };", &()).await;
    Err(gel_errors::UserError::build()) // abort transaction
}).await?;

Returning custom errors

See this example and the documentation of the gel-errors crate for how to return custom error types.

Panics

Function panics when transaction object passed to the closure is not dropped after closure exists. General rule: do not store transaction anywhere and do not send to another coroutine. Pass to all further function calls by reference.

pub fn with_transaction_options(&self, options: TransactionOptions) -> Self

Returns client with adjusted options for future transactions.

This method returns a “shallow copy” of the current client with modified transaction options.

Both self and returned client can be used after, but when using them transaction options applied will be different.

Transaction options are used by the transaction method.

pub fn with_retry_options(&self, options: RetryOptions) -> Self

Returns client with adjusted options for future retrying transactions.

This method returns a “shallow copy” of the current client with modified transaction options.

Both self and returned client can be used after, but when using them transaction options applied will be different.

pub fn with_globals(&self, globals: impl GlobalsDelta) -> Self

Returns the client with the specified global variables set

Most commonly used with #[derive(GlobalsDelta)].

Note: this method is incremental, i.e. it adds (or removes) globals instead of setting a definite set of variables. Use .with_globals(Unset(["name1", "name2"])) to unset some variables.

This method returns a “shallow copy” of the current client with modified global variables

Both self and returned client can be used after, but when using them transaction options applied will be different.

pub fn with_globals_fn(&self, f: impl FnOnce(&mut GlobalsModifier<'_>)) -> Self

Returns the client with the specified global variables set

This method returns a “shallow copy” of the current client with modified global variables

Both self and returned client can be used after, but when using them transaction options applied will be different.

This is equivalent to .with_globals(Fn(f)) but more ergonomic as it allows type inference for lambda.

pub fn with_aliases(&self, aliases: impl AliasesDelta) -> Self

Returns the client with the specified aliases set

This method returns a “shallow copy” of the current client with modified aliases.

Both self and returned client can be used after, but when using them transaction options applied will be different.

pub fn with_aliases_fn(&self, f: impl FnOnce(&mut AliasesModifier<'_>)) -> Self

Returns the client with the specified aliases set

This method returns a “shallow copy” of the current client with modified aliases.

Both self and returned client can be used after, but when using them transaction options applied will be different.

This is equivalent to .with_aliases(Fn(f)) but more ergonomic as it allows type inference for lambda.

pub fn with_default_module(&self, module: Option<impl Into<String>>) -> Self

Returns the client with the default module set or unset

This method returns a “shallow copy” of the current client with modified default module.

Both self and returned client can be used after, but when using them transaction options applied will be different.

pub fn with_config(&self, cfg: impl ConfigDelta) -> Self

Returns the client with the specified config

Note: this method is incremental, i.e. it adds (or removes) individual settings instead of setting a definite configuration. Use .with_config(Unset(["name1", "name2"])) to unset some settings.

This method returns a “shallow copy” of the current client with modified global variables

Both self and returned client can be used after, but when using them transaction options applied will be different.

pub fn with_config_fn(&self, f: impl FnOnce(&mut ConfigModifier<'_>)) -> Self

Returns the client with the specified config

Most commonly used with #[derive(ConfigDelta)].

This method returns a “shallow copy” of the current client with modified global variables

Both self and returned client can be used after, but when using them transaction options applied will be different.

This is equivalent to .with_config(Fn(f)) but more ergonomic as it allows type inference for lambda.

pub fn with_tag(&self, tag: Option<&str>) -> Result<Self, Error>

Returns the client with the specified query tag.

This method returns a “shallow copy” of the current client with modified query tag.

Both self and returned client can be used after, but when using them query tag applied will be different.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl QueryExecutor for &Client

fn query<R, A>( self, query: impl AsRef<str> + Send, arguments: &A, ) -> impl Future<Output = Result<Vec<R>, Error>>

where A: QueryArgs, R: QueryResult,

see Client::query

fn query_verbose<R, A>( self, query: impl AsRef<str> + Send, arguments: &A, ) -> impl Future<Output = Result<ResultVerbose<Vec<R>>, Error>> + Send

where A: QueryArgs, R: QueryResult + Send,

see Client::query_verbose

fn query_single<R, A>( self, query: impl AsRef<str> + Send, arguments: &A, ) -> impl Future<Output = Result<Option<R>, Error>>

where A: QueryArgs, R: QueryResult + Send,

see Client::query_single

fn query_required_single<R, A>( self, query: impl AsRef<str> + Send, arguments: &A, ) -> impl Future<Output = Result<R, Error>>

where A: QueryArgs, R: QueryResult + Send,

see Client::query_required_single

fn query_json( self, query: &str, arguments: &impl QueryArgs, ) -> impl Future<Output = Result<Json, Error>>

see Client::query_json

fn query_single_json( self, query: &str, arguments: &impl QueryArgs, ) -> impl Future<Output = Result<Option<Json>, Error>>

see Client::query_single_json

fn query_required_single_json( self, query: &str, arguments: &impl QueryArgs, ) -> impl Future<Output = Result<Json, Error>>

see Client::query_required_single_json

fn execute<A>( self, query: &str, arguments: &A, ) -> impl Future<Output = Result<(), Error>>

where A: QueryArgs,

see Client::execute