Struct edgedb_tokio::Client

pub struct Client { /* private fields */ }

EdgeDB Client

Internally it contains a connection pool.

To create 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.

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<R, A>( &self, query: &str, 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 edgedb_protocol::value::Value. Similarly, dynamically typed results are also supported.

pub async fn query_single<R, A>( &self, query: &str, arguments: &A ) -> Result<Option<R>, Error>where A: QueryArgs, R: QueryResult,

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 edgedb_protocol::value::Value. Similarly, dynamically typed results are also supported.

pub async fn query_required_single<R, A>( &self, query: &str, arguments: &A ) -> Result<R, Error>where A: QueryArgs, R: QueryResult,

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 edgedb_protocol::value::Value. Similarly, dynamically typed results are also supported.

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

Execute a query and return the result as JSON.

pub async fn query_single_json( &self, query: &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.

pub async fn query_required_single_json( &self, query: &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 transaction<T, B, F>(&self, body: B) -> Result<T, Error>where B: FnMut(Transaction) -> F, F: Future<Output = Result<T, Error>>,

Execute a transaction

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.

Returning custom errors

See this example and the documentation of the edgedb_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.

Example

let conn = edgedb_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?;

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.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy 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.