Struct edgedb_tokio::Client
source · pub struct Client { /* private fields */ }
Expand description
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§
source§impl Client
impl Client
sourcepub fn new(config: &Config) -> 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.
sourcepub async fn ensure_connected(&self) -> Result<(), Error>
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.
sourcepub async fn query<R, A>(
&self,
query: &str,
arguments: &A
) -> Result<Vec<R>, Error>where
A: QueryArgs,
R: QueryResult,
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.
sourcepub async fn query_single<R, A>(
&self,
query: &str,
arguments: &A
) -> Result<Option<R>, Error>where
A: QueryArgs,
R: QueryResult,
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.
sourcepub async fn query_required_single<R, A>(
&self,
query: &str,
arguments: &A
) -> Result<R, Error>where
A: QueryArgs,
R: QueryResult,
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.
sourcepub async fn query_json(
&self,
query: &str,
arguments: &impl QueryArgs
) -> Result<Json, Error>
pub async fn query_json( &self, query: &str, arguments: &impl QueryArgs ) -> Result<Json, Error>
Execute a query and return the result as JSON.
sourcepub async fn query_single_json(
&self,
query: &str,
arguments: &impl QueryArgs
) -> Result<Option<Json>, Error>
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.
sourcepub async fn query_required_single_json(
&self,
query: &str,
arguments: &impl QueryArgs
) -> Result<Json, Error>
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.
sourcepub async fn execute<A>(&self, query: &str, arguments: &A) -> Result<(), Error>where
A: QueryArgs,
pub async fn execute<A>(&self, query: &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 edgedb_protocol::value::Value
.
Similarly, dynamically typed results are also supported.
sourcepub async fn transaction<T, B, F>(&self, body: B) -> Result<T, Error>where
B: FnMut(Transaction) -> F,
F: Future<Output = Result<T, Error>>,
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?;
sourcepub fn with_transaction_options(&self, options: TransactionOptions) -> Self
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.
sourcepub fn with_retry_options(&self, options: RetryOptions) -> Self
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.
sourcepub fn with_globals(&self, globals: impl GlobalsDelta) -> Self
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.
sourcepub fn with_globals_fn(&self, f: impl FnOnce(&mut GlobalsModifier<'_>)) -> Self
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.
sourcepub fn with_aliases(&self, aliases: impl AliasesDelta) -> Self
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.
sourcepub fn with_aliases_fn(&self, f: impl FnOnce(&mut AliasesModifier<'_>)) -> Self
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.
sourcepub fn with_default_module(&self, module: Option<impl Into<String>>) -> Self
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.
sourcepub fn with_config(&self, cfg: impl ConfigDelta) -> Self
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.
sourcepub fn with_config_fn(&self, f: impl FnOnce(&mut ConfigModifier<'_>)) -> Self
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.