API

Client is a connection pool and is safe for concurrent use.

  1. type Client struct {
  2.     // contains filtered or unexported fields
  3. }
  1. func CreateClient(ctx context.Context, opts Options) (*Client, error)

CreateClient returns a new client. The client connects lazily. Call Client.EnsureConnected() to force a connection.

  1. func CreateClientDSN(ctx context.Context, dsn string, opts Options) (*Client, error)

CreateClientDSN returns a new client. See also CreateClient.

dsn is either an instance name https://www.edgedb.com/docs/clients/connection or it specifies a single string in the following format:

  1. edgedb://user:password@host:port/database?option=value.

The following options are recognized: host, port, user, database, password.

  1. func (p *Client) Close() error

Close closes all connections in the pool. Calling close blocks until all acquired connections have been released, and returns an error if called more than once.

  1. func (p *Client) EnsureConnected(ctx context.Context) error

EnsureConnected forces the client to connect if it hasn’t already.

  1. func (p *Client) Execute(
  2.     ctx context.Context,
  3.     cmd string,
  4.     args ...interface{},
  5. ) error

Execute an EdgeQL command (or commands).

  1. func (p *Client) Query(
  2.     ctx context.Context,
  3.     cmd string,
  4.     out interface{},
  5.     args ...interface{},
  6. ) error

Query runs a query and returns the results.

  1. func (p *Client) QueryJSON(
  2.     ctx context.Context,
  3.     cmd string,
  4.     out *[]byte,
  5.     args ...interface{},
  6. ) error

QueryJSON runs a query and return the results as JSON.

  1. func (p *Client) QuerySingle(
  2.     ctx context.Context,
  3.     cmd string,
  4.     out interface{},
  5.     args ...interface{},
  6. ) error

QuerySingle runs a singleton-returning query and returns its element. If the query executes successfully but doesn’t return a result a NoDataError is returned.

  1. func (p *Client) QuerySingleJSON(
  2.     ctx context.Context,
  3.     cmd string,
  4.     out interface{},
  5.     args ...interface{},
  6. ) error

QuerySingleJSON runs a singleton-returning query. If the query executes successfully but doesn’t have a result a NoDataError is returned.

  1. func (p *Client) Tx(ctx context.Context, action TxBlock) error

Tx runs an action in a transaction retrying failed actions if they might succeed on a subsequent attempt.

Retries are governed by retry rules. The default rule can be set with WithRetryRule(). For more fine grained control a retry rule can be set for each defined RetryCondition using WithRetryCondition(). When a transaction fails but is retryable the rule for the failure condition is used to determine if the transaction should be tried again based on RetryRule.Attempts and the amount of time to wait before retrying is determined by RetryRule.Backoff. If either field is unset (see RetryRule) then the default rule is used. If the object’s default is unset the fall back is 3 attempts and exponential backoff.

  1. func (p Client) WithConfig(
  2.     cfg map[string]interface{},
  3. ) *Client

WithConfig sets configuration values for the returned client.

  1. func (p Client) WithGlobals(
  2.     globals map[string]interface{},
  3. ) *Client

WithGlobals sets values for global variables for the returned client.

  1. func (p Client) WithModuleAliases(
  2.     aliases ...ModuleAlias,
  3. ) *Client

WithModuleAliases sets module name aliases for the returned client.

  1. func (p Client) WithRetryOptions(
  2.     opts RetryOptions,
  3. ) *Client

WithRetryOptions returns a shallow copy of the client with the RetryOptions set to opts.

  1. func (p Client) WithTxOptions(opts TxOptions) *Client

WithTxOptions returns a shallow copy of the client with the TxOptions set to opts.

  1. func (p Client) WithoutConfig(key ...string) *Client

WithoutConfig unsets configuration values for the returned client.

  1. func (p Client) WithoutGlobals(globals ...string) *Client

WithoutGlobals unsets values for global variables for the returned client.

  1. func (p Client) WithoutModuleAliases(
  2.     aliases ...string,
  3. ) *Client

WithoutModuleAliases unsets module name aliases for the returned client.

Error is the error type returned from edgedb.

  1. type Error interface {
  2.     Error() string
  3.     Unwrap() error
  5.     // HasTag returns true if the error is marked with the supplied tag.
  6.     HasTag(ErrorTag) bool
  8.     // Category returns true if the error is in the provided category.
  9.     Category(ErrorCategory) bool
  10. }

ErrorCategory values represent EdgeDB’s error types.

  1. type ErrorCategory string
  1. const (
  2.     InternalServerError                    ErrorCategory = "errors::InternalServerError"
  3.     UnsupportedFeatureError                ErrorCategory = "errors::UnsupportedFeatureError"
  4.     ProtocolError                          ErrorCategory = "errors::ProtocolError"
  5.     BinaryProtocolError                    ErrorCategory = "errors::BinaryProtocolError"
  6.     UnsupportedProtocolVersionError        ErrorCategory = "errors::UnsupportedProtocolVersionError"
  7.     TypeSpecNotFoundError                  ErrorCategory = "errors::TypeSpecNotFoundError"
  8.     UnexpectedMessageError                 ErrorCategory = "errors::UnexpectedMessageError"
  9.     InputDataError                         ErrorCategory = "errors::InputDataError"
  10.     ParameterTypeMismatchError             ErrorCategory = "errors::ParameterTypeMismatchError"
  11.     StateMismatchError                     ErrorCategory = "errors::StateMismatchError"
  12.     ResultCardinalityMismatchError         ErrorCategory = "errors::ResultCardinalityMismatchError"
  13.     CapabilityError                        ErrorCategory = "errors::CapabilityError"
  14.     UnsupportedCapabilityError             ErrorCategory = "errors::UnsupportedCapabilityError"
  15.     DisabledCapabilityError                ErrorCategory = "errors::DisabledCapabilityError"
  16.     QueryError                             ErrorCategory = "errors::QueryError"
  17.     InvalidSyntaxError                     ErrorCategory = "errors::InvalidSyntaxError"
  18.     EdgeQLSyntaxError                      ErrorCategory = "errors::EdgeQLSyntaxError"
  19.     SchemaSyntaxError                      ErrorCategory = "errors::SchemaSyntaxError"
  20.     GraphQLSyntaxError                     ErrorCategory = "errors::GraphQLSyntaxError"
  21.     InvalidTypeError                       ErrorCategory = "errors::InvalidTypeError"
  22.     InvalidTargetError                     ErrorCategory = "errors::InvalidTargetError"
  23.     InvalidLinkTargetError                 ErrorCategory = "errors::InvalidLinkTargetError"
  24.     InvalidPropertyTargetError             ErrorCategory = "errors::InvalidPropertyTargetError"
  25.     InvalidReferenceError                  ErrorCategory = "errors::InvalidReferenceError"
  26.     UnknownModuleError                     ErrorCategory = "errors::UnknownModuleError"
  27.     UnknownLinkError                       ErrorCategory = "errors::UnknownLinkError"
  28.     UnknownPropertyError                   ErrorCategory = "errors::UnknownPropertyError"
  29.     UnknownUserError                       ErrorCategory = "errors::UnknownUserError"
  30.     UnknownDatabaseError                   ErrorCategory = "errors::UnknownDatabaseError"
  31.     UnknownParameterError                  ErrorCategory = "errors::UnknownParameterError"
  32.     SchemaError                            ErrorCategory = "errors::SchemaError"
  33.     SchemaDefinitionError                  ErrorCategory = "errors::SchemaDefinitionError"
  34.     InvalidDefinitionError                 ErrorCategory = "errors::InvalidDefinitionError"
  35.     InvalidModuleDefinitionError           ErrorCategory = "errors::InvalidModuleDefinitionError"
  36.     InvalidLinkDefinitionError             ErrorCategory = "errors::InvalidLinkDefinitionError"
  37.     InvalidPropertyDefinitionError         ErrorCategory = "errors::InvalidPropertyDefinitionError"
  38.     InvalidUserDefinitionError             ErrorCategory = "errors::InvalidUserDefinitionError"
  39.     InvalidDatabaseDefinitionError         ErrorCategory = "errors::InvalidDatabaseDefinitionError"
  40.     InvalidOperatorDefinitionError         ErrorCategory = "errors::InvalidOperatorDefinitionError"
  41.     InvalidAliasDefinitionError            ErrorCategory = "errors::InvalidAliasDefinitionError"
  42.     InvalidFunctionDefinitionError         ErrorCategory = "errors::InvalidFunctionDefinitionError"
  43.     InvalidConstraintDefinitionError       ErrorCategory = "errors::InvalidConstraintDefinitionError"
  44.     InvalidCastDefinitionError             ErrorCategory = "errors::InvalidCastDefinitionError"
  45.     DuplicateDefinitionError               ErrorCategory = "errors::DuplicateDefinitionError"
  46.     DuplicateModuleDefinitionError         ErrorCategory = "errors::DuplicateModuleDefinitionError"
  47.     DuplicateLinkDefinitionError           ErrorCategory = "errors::DuplicateLinkDefinitionError"
  48.     DuplicatePropertyDefinitionError       ErrorCategory = "errors::DuplicatePropertyDefinitionError"
  49.     DuplicateUserDefinitionError           ErrorCategory = "errors::DuplicateUserDefinitionError"
  50.     DuplicateDatabaseDefinitionError       ErrorCategory = "errors::DuplicateDatabaseDefinitionError"
  51.     DuplicateOperatorDefinitionError       ErrorCategory = "errors::DuplicateOperatorDefinitionError"
  52.     DuplicateViewDefinitionError           ErrorCategory = "errors::DuplicateViewDefinitionError"
  53.     DuplicateFunctionDefinitionError       ErrorCategory = "errors::DuplicateFunctionDefinitionError"
  54.     DuplicateConstraintDefinitionError     ErrorCategory = "errors::DuplicateConstraintDefinitionError"
  55.     DuplicateCastDefinitionError           ErrorCategory = "errors::DuplicateCastDefinitionError"
  56.     SessionTimeoutError                    ErrorCategory = "errors::SessionTimeoutError"
  57.     IdleSessionTimeoutError                ErrorCategory = "errors::IdleSessionTimeoutError"
  58.     QueryTimeoutError                      ErrorCategory = "errors::QueryTimeoutError"
  59.     TransactionTimeoutError                ErrorCategory = "errors::TransactionTimeoutError"
  60.     IdleTransactionTimeoutError            ErrorCategory = "errors::IdleTransactionTimeoutError"
  61.     ExecutionError                         ErrorCategory = "errors::ExecutionError"
  62.     InvalidValueError                      ErrorCategory = "errors::InvalidValueError"
  63.     DivisionByZeroError                    ErrorCategory = "errors::DivisionByZeroError"
  64.     NumericOutOfRangeError                 ErrorCategory = "errors::NumericOutOfRangeError"
  65.     AccessPolicyError                      ErrorCategory = "errors::AccessPolicyError"
  66.     IntegrityError                         ErrorCategory = "errors::IntegrityError"
  67.     ConstraintViolationError               ErrorCategory = "errors::ConstraintViolationError"
  68.     CardinalityViolationError              ErrorCategory = "errors::CardinalityViolationError"
  69.     MissingRequiredError                   ErrorCategory = "errors::MissingRequiredError"
  70.     TransactionError                       ErrorCategory = "errors::TransactionError"
  71.     TransactionConflictError               ErrorCategory = "errors::TransactionConflictError"
  72.     TransactionSerializationError          ErrorCategory = "errors::TransactionSerializationError"
  73.     TransactionDeadlockError               ErrorCategory = "errors::TransactionDeadlockError"
  74.     ConfigurationError                     ErrorCategory = "errors::ConfigurationError"
  75.     AccessError                            ErrorCategory = "errors::AccessError"
  76.     AuthenticationError                    ErrorCategory = "errors::AuthenticationError"
  77.     AvailabilityError                      ErrorCategory = "errors::AvailabilityError"
  78.     BackendUnavailableError                ErrorCategory = "errors::BackendUnavailableError"
  79.     BackendError                           ErrorCategory = "errors::BackendError"
  80.     UnsupportedBackendFeatureError         ErrorCategory = "errors::UnsupportedBackendFeatureError"
  81.     ClientError                            ErrorCategory = "errors::ClientError"
  82.     ClientConnectionError                  ErrorCategory = "errors::ClientConnectionError"
  83.     ClientConnectionFailedError            ErrorCategory = "errors::ClientConnectionFailedError"
  84.     ClientConnectionFailedTemporarilyError ErrorCategory = "errors::ClientConnectionFailedTemporarilyError"
  85.     ClientConnectionTimeoutError           ErrorCategory = "errors::ClientConnectionTimeoutError"
  86.     ClientConnectionClosedError            ErrorCategory = "errors::ClientConnectionClosedError"
  87.     InterfaceError                         ErrorCategory = "errors::InterfaceError"
  88.     QueryArgumentError                     ErrorCategory = "errors::QueryArgumentError"
  89.     MissingArgumentError                   ErrorCategory = "errors::MissingArgumentError"
  90.     UnknownArgumentError                   ErrorCategory = "errors::UnknownArgumentError"
  91.     InvalidArgumentError                   ErrorCategory = "errors::InvalidArgumentError"
  92.     NoDataError                            ErrorCategory = "errors::NoDataError"
  93.     InternalClientError                    ErrorCategory = "errors::InternalClientError"
  94. )

ErrorTag is the argument type to Error.HasTag().

  1. type ErrorTag string
  1. const (
  2.     ShouldRetry     ErrorTag = "SHOULD_RETRY"
  3.     ShouldReconnect ErrorTag = "SHOULD_RECONNECT"
  4. )

IsolationLevel documentation can be found here https://www.edgedb.com/docs/reference/edgeql/tx_start#parameters

  1. type IsolationLevel string

The available levels are:

  1. const (
  2.     Serializable IsolationLevel = "serializable"
  3. )

ModuleAlias is an alias name and module name pare.

  1. type ModuleAlias struct {
  2.     Alias  string
  3.     Module string
  4. }

Options for connecting to an EdgeDB server

  1. type Options struct {
  2.     // Host is an EdgeDB server host address, given as either an IP address or
  3.     // domain name. (Unix-domain socket paths are not supported)
  4.     //
  5.     // Host cannot be specified alongside the 'dsn' argument, or
  6.     // CredentialsFile option. Host will override all other credentials
  7.     // resolved from any environment variables, or project credentials with
  8.     // their defaults.
  9.     Host string
  11.     // Port is a port number to connect to at the server host.
  12.     //
  13.     // Port cannot be specified alongside the 'dsn' argument, or
  14.     // CredentialsFile option. Port will override all other credentials
  15.     // resolved from any environment variables, or project credentials with
  16.     // their defaults.
  17.     Port int
  19.     // Credentials is a JSON string containing connection credentials.
  20.     //
  21.     // Credentials cannot be specified alongside the 'dsn' argument, Host,
  22.     // Port, or CredentialsFile.  Credentials will override all other
  23.     // credentials not present in the credentials string with their defaults.
  24.     Credentials []byte
  26.     // CredentialsFile is a path to a file containing connection credentials.
  27.     //
  28.     // CredentialsFile cannot be specified alongside the 'dsn' argument, Host,
  29.     // Port, or Credentials.  CredentialsFile will override all other
  30.     // credentials not present in the credentials file with their defaults.
  31.     CredentialsFile string
  33.     // User is the name of the database role used for authentication.
  34.     //
  35.     // If not specified, the value is resolved from any compound
  36.     // argument/option, then from EDGEDB_USER, then any compound environment
  37.     // variable, then project credentials.
  38.     User string
  40.     // Database is the name of the database to connect to.
  41.     //
  42.     // If not specified, the value is resolved from any compound
  43.     // argument/option, then from EDGEDB_DATABASE, then any compound
  44.     // environment variable, then project credentials.
  45.     Database string
  47.     // Password to be used for authentication, if the server requires one.
  48.     //
  49.     // If not specified, the value is resolved from any compound
  50.     // argument/option, then from EDGEDB_PASSWORD, then any compound
  51.     // environment variable, then project credentials.
  52.     // Note that the use of the environment variable is discouraged
  53.     // as other users and applications may be able to read it
  54.     // without needing specific privileges.
  55.     Password OptionalStr
  57.     // ConnectTimeout is used when establishing connections in the background.
  58.     ConnectTimeout time.Duration
  60.     // WaitUntilAvailable determines how long to wait
  61.     // to reestablish a connection.
  62.     WaitUntilAvailable time.Duration
  64.     // Concurrency determines the maximum number of connections.
  65.     // If Concurrency is zero, max(4, runtime.NumCPU()) will be used.
  66.     // Has no effect for single connections.
  67.     Concurrency uint
  69.     // Parameters used to configure TLS connections to EdgeDB server.
  70.     TLSOptions TLSOptions
  72.     // Read the TLS certificate from this file.
  73.     // DEPRECATED, use TLSOptions.CAFile instead.
  74.     TLSCAFile string
  76.     // Specifies how strict TLS validation is.
  77.     // DEPRECATED, use TLSOptions.SecurityMode instead.
  78.     TLSSecurity string
  80.     // ServerSettings is currently unused.
  81.     ServerSettings map[string][]byte
  82. }

RetryBackoff returns the duration to wait after the nth attempt before making the next attempt when retrying a transaction.

  1. type RetryBackoff func(n int) time.Duration

RetryCondition represents scenarios that can caused a transaction run in Tx() methods to be retried.

  1. type RetryCondition int

RetryOptions configures how Tx() retries failed transactions. Use NewRetryOptions to get a default RetryOptions value instead of creating one yourself.

  1. type RetryOptions struct {
  2.     // contains filtered or unexported fields
  3. }
  1. func (o RetryOptions) WithCondition(
  2.     condition RetryCondition,
  3.     rule RetryRule,
  4. ) RetryOptions

WithCondition sets the retry rule for the specified condition.

  1. func (o RetryOptions) WithDefault(rule RetryRule) RetryOptions

WithDefault sets the rule for all conditions to rule.

RetryRule determines how transactions should be retried when run in Tx() methods. See Client.Tx() for details.

  1. type RetryRule struct {
  2.     // contains filtered or unexported fields
  3. }
  1. func NewRetryRule() RetryRule

NewRetryRule returns the default RetryRule value.

  1. func (r RetryRule) WithAttempts(attempts int) RetryRule

WithAttempts sets the rule’s attempts. attempts must be greater than zero.

  1. func (r RetryRule) WithBackoff(fn RetryBackoff) RetryRule

WithBackoff returns a copy of the RetryRule with backoff set to fn.

TLSOptions contains the parameters needed to configure TLS on EdgeDB server connections.

  1. type TLSOptions struct {
  2.     // PEM-encoded CA certificate
  3.     CA []byte
  4.     // Path to a PEM-encoded CA certificate file
  5.     CAFile string
  6.     // Determines how strict we are with TLS checks
  7.     SecurityMode TLSSecurityMode
  8. }

TLSSecurityMode specifies how strict TLS validation is.

  1. type TLSSecurityMode string
  1. const (
  2.     // TLSModeDefault makes security mode inferred from other options
  3.     TLSModeDefault TLSSecurityMode = "default"
  4.     // TLSModeInsecure results in no certificate verification whatsoever
  5.     TLSModeInsecure TLSSecurityMode = "insecure"
  6.     // TLSModeNoHostVerification enables certificate verification
  7.     // against CAs, but hostname matching is not performed.
  8.     TLSModeNoHostVerification TLSSecurityMode = "no_host_verification"
  9.     // TLSModeStrict enables full certificate and hostname verification.
  10.     TLSModeStrict TLSSecurityMode = "strict"
  11. )

Tx is a transaction. Use Client.Tx() to get a transaction.

  1. type Tx struct {
  2.     // contains filtered or unexported fields
  3. }
  1. func (t *Tx) Execute(
  2.     ctx context.Context,
  3.     cmd string,
  4.     args ...interface{},
  5. ) error

Execute an EdgeQL command (or commands).

  1. func (t *Tx) Query(
  2.     ctx context.Context,
  3.     cmd string,
  4.     out interface{},
  5.     args ...interface{},
  6. ) error

Query runs a query and returns the results.

  1. func (t *Tx) QueryJSON(
  2.     ctx context.Context,
  3.     cmd string,
  4.     out *[]byte,
  5.     args ...interface{},
  6. ) error

QueryJSON runs a query and return the results as JSON.

  1. func (t *Tx) QuerySingle(
  2.     ctx context.Context,
  3.     cmd string,
  4.     out interface{},
  5.     args ...interface{},
  6. ) error

QuerySingle runs a singleton-returning query and returns its element. If the query executes successfully but doesn’t return a result a NoDataError is returned.

  1. func (t *Tx) QuerySingleJSON(
  2.     ctx context.Context,
  3.     cmd string,
  4.     out interface{},
  5.     args ...interface{},
  6. ) error

QuerySingleJSON runs a singleton-returning query. If the query executes successfully but doesn’t have a result a NoDataError is returned.

TxBlock is work to be done in a transaction.

  1. type TxBlock func(context.Context, *Tx) error

TxOptions configures how transactions behave.

  1. type TxOptions struct {
  2.     // contains filtered or unexported fields
  3. }
  1. func NewTxOptions() TxOptions

NewTxOptions returns the default TxOptions value.

  1. func (o TxOptions) WithDeferrable(d bool) TxOptions

WithDeferrable returns a shallow copy of the client with the transaction deferrable mode set to d.

  1. func (o TxOptions) WithIsolation(i IsolationLevel) TxOptions

WithIsolation returns a copy of the TxOptions with the isolation level set to i.

  1. func (o TxOptions) WithReadOnly(r bool) TxOptions

WithReadOnly returns a shallow copy of the client with the transaction read only access mode set to r.