Client API Reference
function createClient()
Client createClient({
String? dsn,
String? instanceName,
String? credentials,
String? credentialsFile,
String? host,
int? port,
String? database,
String? branch,
String? user,
String? password,
String? secretKey,
Map<String, String>? serverSettings,
String? tlsCA,
String? tlsCAFile,
TLSSecurity? tlsSecurity,
Duration? waitUntilAvailable,
ConnectConfig? config,
int? concurrency, }
)Creates a new Client instance with the provided connection options.
Usually it’s recommended to not pass any connection options here, and instead let the client resolve the connection options from the edgedb project or environment variables. See the Client Library Connection documentation for details on connection options and how they are resolved.
The config parameter allows you to pass in a ConnectConfig object, which
is just a wrapper object containing connection options to make them easier
to manage in your application. If a connection option exists both in the
config object and is passed as a parameter, the value passed as a
parameter will override the value in the config object.
Alongside the connection options, there are the following parameters:
-
concurrency: Specifies the maximum number of connections the Client will create in it’s connection pool. If not specified the concurrency will be controlled by the server. This is recommended as it allows the server to better manage the number of client connections based on it’s own available resources.
class Client
Represents a pool of connections to the database, provides methods to run queries and manages the context in which queries are run (ie. setting globals, modifying session config, etc.)
The Client class cannot be instantiated directly, and is instead created by the createClient() function. Since creating a client is relatively expensive, it is recommended to create a single Client instance that you can then import and use across your app.
The with*() methods return a new Client instance derived from this
instance. The derived instances all share the pool of connections managed
by the root Client instance (ie. the instance created by createClient()),
so calling the ensureConnected(), close() or terminate() methods on
any of these instances will affect them all.
property
.isClosed
bool get isClosedWhether close() (or terminate()) has been called on the client.
If isClosed is true, subsequent calls to query methods will fail.
method
.close()
Future<void> close()Close the client’s open connections gracefully.
Returns a Future that completes when all connections in the client’s
pool have finished any currently running query. Any pending queries
awaiting a free connection from the pool, and have not started executing
yet, will return an error.
A warning is produced if the pool takes more than 60 seconds to close.
method
.ensureConnected()
Future<void> ensureConnected()If the client does not yet have any open connections in its pool, attempts to open a connection, else returns immediately.
Since the client lazily creates new connections as needed (up to the
configured concurrency limit), the first connection attempt will
usually only happen when the first query is run on a client.
The ensureConnected() method allows you to explicitly check that the
client can connect to the database without running a query
(can be useful to catch any errors resulting from connection
mis-configuration).
method
.execute()
Future<void> execute(
String query, [
dynamic args]
)Executes a query, returning no result.
For details on args see the edgedb library
docs page.
method
.query()
Future<List> query(
String query, [
dynamic args]
)Executes a query, returning a List of results.
For details on result types and args see the edgedb library
docs page.
method
.queryJSON()
Future<String> queryJSON(
String query, [
dynamic args]
)Executes a query, returning the result as a JSON encoded String.
For details on args see the edgedb library
docs page.
method
.queryRequiredSingle()
Future queryRequiredSingle(
String query, [
dynamic args]
)Executes a query, returning a single (non-null) result.
The query must return exactly one element. If the query returns more than one element, a ResultCardinalityMismatchError error is thrown. If the query returns an empty set, a NoDataError error is thrown.
For details on result types and args see the edgedb library
docs page.
method
.queryRequiredSingleJSON()
Future<String> queryRequiredSingleJSON(
String query, [
dynamic args]
)Executes a query, returning the result as a JSON encoded String.
The query must return exactly one element. If the query returns more than one element, a ResultCardinalityMismatchError error is thrown. If the query returns an empty set, a NoDataError error is thrown.
For details on args see the edgedb library
docs page.
method
.querySingle()
Future querySingle(
String query, [
dynamic args]
)Executes a query, returning a single (possibly null) result.
The query must return no more than one element. If the query returns more than one element, a ResultCardinalityMismatchError error is thrown.
For details on result types and args see the edgedb library
docs page.
method
.querySingleJSON()
Future<String> querySingleJSON(
String query, [
dynamic args]
)Executes a query, returning the result as a JSON encoded String.
The query must return no more than one element. If the query returns more than one element, a ResultCardinalityMismatchError error is thrown.
For details on args see the edgedb library
docs page.
method
.terminate()
void terminate()Immediately closes all connections in the client’s pool, without waiting for any running queries to finish.
method
.transaction<T>()
Future<T> transaction<T>(
Future<T> action( Transaction)
)Execute a retryable transaction.
Use this method to atomically execute multiple queries, where you also
need to run some logic client side. If you only need to run multiple
queries atomically, instead consider just using the execute()/
query*() methods - they all support queries containing multiple
statements.
The transaction() method expects an action function returning a
Future, and will automatically handle starting the transaction before
the action function is run, and commiting / rolling back the transaction
when the Future completes / throws an error.
The action function is passed a Transaction object, which implements
the same execute()/query*() methods as on Client, and should be
used instead of the Client methods. The notable difference of these
methods on Transaction as compared to the Client query methods, is
that they do not attempt to retry on errors. Instead the entire action
function is re-executed if a retryable error (such as a transient
network error or transaction serialization error) is thrown inside it.
Non-retryable errors will cause the transaction to be automatically
rolled back, and the error re-thrown by transaction().
A key implication of the whole action function being re-executed on
transaction retries, is that non-querying code will also be re-executed,
so the action should should not have side effects. It is also
recommended that the action does not have long running code, as
holding a transaction open is expensive on the server, and will negatively
impact performance.
The number of times transaction() will attempt to execute the transaction, and the backoff timeout between retries can be configured with withRetryOptions().
method
.withConfig()
Client withConfig(
Map<String, Object> config
)Returns a new Client instance with the specified client session configuration.
The config parameter is merged with any existing
session config defined on the current client instance.
Equivalent to using the configure session command. For available
configuration parameters refer to the
Config documentation.
method
.withGlobals()
Client withGlobals(
Map<String, dynamic> globals
)Returns a new Client instance with the specified global values.
The globals parameter is merged with any existing globals defined
on the current client instance.
Equivalent to using the set global command.
Example:
final user = await client.withGlobals({
'userId': '...'
}).querySingle('''
select User {name} filter .id = global userId
''');method
.withModuleAliases()
Client withModuleAliases(
Map<String, String> aliases
)Returns a new Client instance with the specified module aliases.
The aliases parameter is merged with any existing module aliases
defined on the current client instance.
If the alias name is 'module' this is equivalent to using the
set module command, otherwise it is equivalent to the set alias
command.
Example:
final user = await client.withModuleAliases({
'module': 'sys'
}).querySingle('''
select get_version_as_str()
''');
// "2.0"method
.withRetryOptions()
Client withRetryOptions(
RetryOptions options
)Returns a new Client instance with the specified RetryOptions.
method
.withSession()
Client withSession(
Session session
)Returns a new Client instance with the specified Session options.
Instead of specifying an entirely new Session options object, Client also implements the withModuleAliases, withConfig and withGlobals methods for convenience.
method
.withTransactionOptions()
Client withTransactionOptions(
TransactionOptions options
)Returns a new Client instance with the specified TransactionOptions.
class Options
Manages all options (RetryOptions, TransactionOptions and Session) for a Client.
constructor
Options()
Options({
RetryOptions? retryOptions,
TransactionOptions? transactionOptions,
Session? session, }
)method
.defaults()
Options defaults()Creates a new Options object with all options set to their defaults.
method
.withRetryOptions()
Options withRetryOptions(
RetryOptions options
)Returns a new Options object with the specified RetryOptions.
method
.withSession()
Options withSession(
Session session
)Returns a new Options object with the specified Session options.
method
.withTransactionOptions()
Options withTransactionOptions(
TransactionOptions options
)Returns a new Options object with the specified TransactionOptions.
class Session
Configuration of a session, containing the config, aliases, and globals to be used when executing a query.
constructor
Session()
Session({
String module = 'default',
Map<String, String>? moduleAliases,
Map<String, Object>? config,
Map<String, dynamic>? globals, }
)Creates a new Session object with the given options.
Refer to the individial with* methods for details on each option.
method
.defaults()
Session defaults()Creates a new Session with all options set to their defaults.
method
.withConfig()
Session withConfig(
Map<String, Object> config
)Returns a new Session with the specified client session configuration.
The config parameter is merged with any existing
session config defined on the current Session.
Equivalent to using the configure session command. For available
configuration parameters refer to the
Config documentation.
method
.withGlobals()
Session withGlobals(
Map<String, dynamic> globals
)Returns a new Session with the specified global values.
The globals parameter is merged with any existing globals defined
on the current Session.
Equivalent to using the set global command.
method
.withModuleAliases()
Session withModuleAliases(
Map<String, String> aliases
)Returns a new Session with the specified module aliases.
The aliases parameter is merged with any existing module aliases
defined on the current Session.
If the alias name is 'module' this is equivalent to using the
set module command, otherwise it is equivalent to the set alias
command.
class RetryOptions
Options that define how a Client will handle automatically retrying queries in the event of a retryable error.
The options are specified by RetryRule’s, which define a number of times to attempt to retry a query, and a backoff function to determine how long to wait after each retry before attempting the query again. RetryOptions has a default RetryRule, and can be configured with extra RetryRule’s which override the default for given error conditions.
constructor
RetryOptions()
RetryOptions({
int? attempts,
BackoffFunction? backoff, }
)Creates a new RetryOptions object, with a default RetryRule, with
the given attempts and backoff function.
If attempts or backoff are not specified, the defaults of 3 attempts
and the exponential defaultBackoff function are used.
method
.defaults()
RetryOptions defaults()Creates a new RetryOptions with all options set to their defaults.
method
.withRule()
RetryOptions withRule({
required RetryCondition condition,
int? attempts,
BackoffFunction? backoff, }
)Adds a new RetryRule with the given attempts and backoff function,
that overrides the default RetryRule for a given error condition.
If attempts or backoff are not specified, the values of the default
RetryRule of this RetryOptions are used.
class TransactionOptions
Defines the transaction mode that Client.transaction runs transactions with.
For more details on transaction modes see the Transaction docs.
constructor
TransactionOptions()
TransactionOptions({
IsolationLevel? isolation,
bool? readonly,
bool? deferrable, }
)Creates a new TransactionOptions object with the given isolation,
readonly and deferrable options.
If not specified, the defaults are as follows:
-
isolation: serializable -
readonly: false -
deferrable: false
method
.defaults()
TransactionOptions defaults()Creates a new TransactionOptions with all options set to their defaults.