Light
Dark
System

Client API Reference

Copy
Client createClient(
  {String? dsn,
  String? instanceName,
  String? credentials,
  String? credentialsFile,
  String? host,
  int? port,
  String? database,
  String? user,
  String? password,
  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.

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.

Copy
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.

Copy
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).

Copy
Future<void> execute(
  String query,
  [dynamic args]
)

Executes a query, returning no result.

For details on args see the edgedb library docs page.

Copy
bool get isClosed

Whether close() (or terminate()) has been called on the client. If isClosed is true, subsequent calls to query methods will fail.

Copy
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.

Copy
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.

Copy
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.

Copy
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.

Copy
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.

Copy
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.

Copy
void terminate()

Immediately closes all connections in the client’s pool, without waiting for any running queries to finish.

Copy
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().

Copy
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.

Copy
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:

Copy
final user = await client.withGlobals({
  'userId': '...'
}).querySingle('''
  select User {name} filter .id = global userId
''');
Copy
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:

Copy
final user = await client.withModuleAliases({
  'module': 'sys'
}).querySingle('''
  select get_version_as_str()
''');
// "2.0"
Copy
Client withRetryOptions(
  RetryOptions options
)

Returns a new Client instance with the specified RetryOptions.

Copy
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.

Copy
Client withTransactionOptions(
  TransactionOptions options
)

Returns a new Client instance with the specified TransactionOptions.

Manages all options (RetryOptions, TransactionOptions and Session) for a Client.

Copy
Options(
  {RetryOptions? retryOptions,
  TransactionOptions? transactionOptions,
  Session? session}
)
Copy
Options defaults()

Creates a new Options object with all options set to their defaults.

Copy
final RetryOptions retryOptions;
Copy
final Session session;
Copy
final TransactionOptions transactionOptions;
Copy
Options withRetryOptions(
  RetryOptions options
)

Returns a new Options object with the specified RetryOptions.

Copy
Options withSession(
  Session session
)

Returns a new Options object with the specified Session options.

Copy
Options withTransactionOptions(
  TransactionOptions options
)

Returns a new Options object with the specified TransactionOptions.

Configuration of a session, containing the config, aliases, and globals to be used when executing a query.

Copy
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.

Copy
final Map<String, Object> config;
Copy
Session defaults()

Creates a new Session with all options set to their defaults.

Copy
final Map<String, dynamic> globals;
Copy
final String module;
Copy
final Map<String, String> moduleAliases;
Copy
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.

Copy
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.

Copy
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.

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.

Copy
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.

Copy
final RetryRule defaultRetryRule;
Copy
RetryOptions defaults()

Creates a new RetryOptions with all options set to their defaults.

Copy
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.

Defines the transaction mode that Client.transaction runs transactions with.

For more details on transaction modes see the Transaction docs.

Copy
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

Copy
TransactionOptions defaults()

Creates a new TransactionOptions with all options set to their defaults.

Copy
final bool deferrable;
Copy
final IsolationLevel isolation;
Copy
final bool readonly;
Light
Dark
System