edgedb library
This is the core client library, providing the main createClient() function for configuring a connection to an EdgeDB server, and the Client class, which implements all the methods to run queries, work with transactions, and manage other client state.
Parameters
If your query contains parameters (e.g. $foo), you can pass in values as
the second argument to all the execute() and query*() methods.
Named parameters are expected to be passed as a Map<String, dynamic>, and
positional parameters as a List<dynamic>.
// Named parameters
await client.execute(r'''insert Movie {
title := <str>$title
}''', {'title': 'Iron Man'});
// Positional parameters
await client.execute(r'''insert Movie {
title := <str>$0
}''', ['Iron Man']);
Remember that parameters can only be scalars or arrays of scalars.
Scripts
All the execute() and the query*() methods support scripts (queries
containing multiple statements). The statements are run in an implicit
transaction (unless already in an explicit transaction), so the whole
script remains atomic. For the query*() methods only the result of the
final statement in the script will be returned.
final result = await client.query(r'''
insert Movie {
title := <str>$title
};
insert Person {
name := <str>$name
};
''', {
'title': 'Thor: Ragnarok',
'name': 'Anson Mount'
});
// [{id: "5dd2557b..."}]
// Note: only the single item of the `insert Person ...`
// statement is returned
For more fine grained control of atomic exectution of multiple statements, use the Client.transaction() API.
Type Conversion
EdgeDB types are decoded into/encoded from Dart types as follows (any types in parentheses are also valid for query parameters):
| EdgeDB type | Dart type |
|---|---|
| Sets | List<dynamic> |
| Arrays | List<dynamic> |
| Objects | Map<String, dynamic> |
Tuples (tuple<x, y, ...>) |
List<dynamic> |
Named tuples (tuple<foo: x, bar: y, ...>) |
Map<String, dynamic> |
| Ranges | Range<dynamic> |
| Multiranges | MultiRange<dynamic> |
| Enums | String |
str |
String |
bool |
bool |
int16/int32/int64 |
int |
float32/float64 |
double |
json |
as decoded by json.decode() |
uuid |
String |
bigint |
BigInt |
decimal |
(unsupported) |
bytes |
Uint8List |
datetime |
DateTime |
duration |
Duration |
cal::local_datetime |
LocalDateTime |
cal::local_date |
LocalDate |
cal::local_time |
LocalTime |
cal::relative_duration |
RelativeDuration |
cal::date_duration |
DateDuration |
cfg::memory |
ConfigMemory |
ext::pgvector::vector |
Float32List (List<double>) |
Custom types
For EdgeDB types that don't have a built-in Dart type, we provide some custom types:
EdgeDB errors
EdgeDB has a large range of type errors for fine-grained error handling, with all exported error types inheriting from a base EdgeDBError type. These are the main error types which are useful to watch out for (along with their subtypes):
- QueryError: Errors relating to an issue with the query you're trying to run, such as syntax errors, or non-existant types/properties/links.
- ExecutionError: Runtime errors while running your query, such as cardinality violations.
- ClientError: Client side errors arising from incorrect arguments being passed to methods, etc.
- AccessError: The authentication details you provided were incorrect.
- InternalServerError: Ideally these should never happen; they indicate a bug in the EdgeDB server. It's useful if you can report these errors here: github.com/edgedb/edgedb/issues
Classes
- 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.)
- ConfigMemory
- Represents an amount of memory in bytes.
- ConnectConfig
- DateDuration
-
Represents an interval of time in days and months. DateDuration unlike
RelativeDuration does not contain an absolute time component. (ie.
hours,minutes,seconds,millisecondsandmicroseconds). - Executor
-
Abstract class that defines the interface for the
execute()andquery*()methods. - LocalDate
- Represents a calendar date without any associated time or timezone.
- LocalDateTime
- Represents a calendar date and time without a timezone.
- LocalTime
- Represents a 'wall-clock' time, without any associated date or timezone.
-
MultiRange<
T> - Options
- Manages all options (RetryOptions, TransactionOptions and Session) for a Client.
-
Range<
T> - Represents an interval between values.
- RelativeDuration
-
Represents an interval of time. RelativeDuration can contain both
absolute components (
hours,minutes,seconds,millisecondsandmicroseconds) as in the Duration type, and also components which need to be interpreted relative to a date (years,months,days). - RetryOptions
- Options that define how a Client will handle automatically retrying queries in the event of a retryable error.
- RetryRule
- Session
- Configuration of a session, containing the config, aliases, and globals to be used when executing a query.
- Transaction
- TransactionOptions
- Defines the transaction mode that Client.transaction runs transactions with.
Functions
-
createClient(
{String? dsn, String? instanceName, String? credentials, String? credentialsFile, String? host, int? port, String? database, String? user, String? password, String? secretKey, Map< String, String> ? serverSettings, String? tlsCA, String? tlsCAFile, TLSSecurity? tlsSecurity, Duration? waitUntilAvailable, ConnectConfig? config, int? concurrency}) → Client - Creates a new Client instance with the provided connection options.
-
defaultBackoff(
int attempt) → Duration
Typedefs
- BackoffFunction = Duration Function(int attempt)
Exceptions / Errors
- AccessError
- AccessPolicyError
- AuthenticationError
- AvailabilityError
- BackendError
- BinaryProtocolError
- CapabilityError
- CardinalityViolationError
- ClientConnectionClosedError
- ClientConnectionError
- ClientConnectionFailedError
- ClientConnectionFailedTemporarilyError
- ClientConnectionTimeoutError
- ClientError
- ConfigurationError
- ConstraintViolationError
- DisabledCapabilityError
- DivisionByZeroError
- DuplicateCastDefinitionError
- DuplicateConstraintDefinitionError
- DuplicateDatabaseDefinitionError
- DuplicateDefinitionError
- DuplicateFunctionDefinitionError
- DuplicateLinkDefinitionError
- DuplicateMigrationError
- DuplicateModuleDefinitionError
- DuplicateOperatorDefinitionError
- DuplicatePropertyDefinitionError
- DuplicateUserDefinitionError
- DuplicateViewDefinitionError
- EdgeDBError
- EdgeQLSyntaxError
- ExecutionError
- GraphQLSyntaxError
- IdleSessionTimeoutError
- IdleTransactionTimeoutError
- InputDataError
- IntegrityError
- InterfaceError
- InternalClientError
- InternalServerError
- InvalidAliasDefinitionError
- InvalidArgumentError
- InvalidCastDefinitionError
- InvalidConstraintDefinitionError
- InvalidDatabaseDefinitionError
- InvalidDefinitionError
- InvalidFunctionDefinitionError
- InvalidLinkDefinitionError
- InvalidLinkTargetError
- InvalidModuleDefinitionError
- InvalidOperatorDefinitionError
- InvalidPropertyDefinitionError
- InvalidPropertyTargetError
- InvalidReferenceError
- InvalidSyntaxError
- InvalidTargetError
- InvalidTypeError
- InvalidUserDefinitionError
- InvalidValueError
- LogMessage
- MissingArgumentError
- MissingRequiredError
- NoDataError
- NumericOutOfRangeError
- ParameterTypeMismatchError
- ProtocolError
- QueryArgumentError
- QueryAssertionError
- QueryError
- QueryTimeoutError
- ResultCardinalityMismatchError
- SchemaDefinitionError
- SchemaError
- SchemaSyntaxError
- ServerBlockedError
- ServerOfflineError
- SessionTimeoutError
- StateMismatchError
- TransactionConflictError
- TransactionDeadlockError
- TransactionError
- TransactionSerializationError
- TransactionTimeoutError
- TypeSpecNotFoundError
- UnexpectedMessageError
- UnknownArgumentError
- UnknownDatabaseError
- UnknownLinkError
- UnknownModuleError
- UnknownParameterError
- UnknownPropertyError
- UnknownTenantError
- UnknownUserError
- UnsupportedBackendFeatureError
- UnsupportedCapabilityError
- UnsupportedFeatureError
- UnsupportedProtocolVersionError
- WarningMessage
- WatchError