Action is work to be done in a transaction.
type Action func(context.Context, *Tx) errorConn is a single Conn to a server. Conn is not safe for concurrent use. Pool should be preferred over Conn for most use cases.
type Conn struct {
// contains filtered or unexported fields
}func ConnectOne(ctx context.Context, opts Options) (*Conn, error)ConnectOne establishes a connection to an EdgeDB server.
func ConnectOneDSN(
ctx context.Context,
dsn string,
opts Options,
) (*Conn, error)ConnectOneDSN establishes a connection to an EdgeDB server.
dsn is either an instance name https://www.edgedb.com/docs/clients/00_python/instances/#edgedb-instances or it specifies a single string in the following format:
edgedb://user:password@host:port/database?option=value.The following options are recognized: host, port, user, database, password.
func (c *Conn) Close() errorClose closes the connection. Connections are not usable after they are closed.
func (b Conn) Execute(ctx context.Context, cmd string) errorExecute an EdgeQL command (or commands).
func (b Conn) Query(
ctx context.Context,
cmd string,
out interface{},
args ...interface{},
) errorQuery runs a query and returns the results.
func (b Conn) QueryJSON(
ctx context.Context,
cmd string,
out *[]byte,
args ...interface{},
) errorQueryJSON runs a query and return the results as JSON.
func (b Conn) QueryOne(
ctx context.Context,
cmd string,
out interface{},
args ...interface{},
) errorQueryOne runs a singleton-returning query and returns its element. If the query executes successfully but doesn’t return a result a NoDataError is returned.
func (b Conn) QueryOneJSON(
ctx context.Context,
cmd string,
out *[]byte,
args ...interface{},
) errorQueryOneJSON runs a singleton-returning query. If the query executes successfully but doesn’t have a result a NoDataError is returned.
func (c *Conn) RawTx(ctx context.Context, action Action) errorRawTx runs an action in a transaction. If the action returns an error the transaction is rolled back, otherwise it is committed.
func (c *Conn) RetryingTx(ctx context.Context, action Action) errorRetryingTx does the same as RawTx but retries failed actions if they might succeed on a subsequent attempt.
Error is the error type returned from edgedb.
type Error interface {
Error() string
Unwrap() error
// HasTag returns true if the error is marked with the supplied tag.
HasTag(ErrorTag) bool
// Category returns true if the error is in the provided category.
Category(ErrorCategory) bool
}ErrorCategory values represent EdgeDB’s error types.
type ErrorCategory stringconst (
InternalServerError ErrorCategory = "errors::InternalServerError"
UnsupportedFeatureError ErrorCategory = "errors::UnsupportedFeatureError"
ProtocolError ErrorCategory = "errors::ProtocolError"
BinaryProtocolError ErrorCategory = "errors::BinaryProtocolError"
UnsupportedProtocolVersionError ErrorCategory = "errors::UnsupportedProtocolVersionError"
TypeSpecNotFoundError ErrorCategory = "errors::TypeSpecNotFoundError"
UnexpectedMessageError ErrorCategory = "errors::UnexpectedMessageError"
InputDataError ErrorCategory = "errors::InputDataError"
ResultCardinalityMismatchError ErrorCategory = "errors::ResultCardinalityMismatchError"
CapabilityError ErrorCategory = "errors::CapabilityError"
UnsupportedCapabilityError ErrorCategory = "errors::UnsupportedCapabilityError"
DisabledCapabilityError ErrorCategory = "errors::DisabledCapabilityError"
QueryError ErrorCategory = "errors::QueryError"
InvalidSyntaxError ErrorCategory = "errors::InvalidSyntaxError"
EdgeQLSyntaxError ErrorCategory = "errors::EdgeQLSyntaxError"
SchemaSyntaxError ErrorCategory = "errors::SchemaSyntaxError"
GraphQLSyntaxError ErrorCategory = "errors::GraphQLSyntaxError"
InvalidTypeError ErrorCategory = "errors::InvalidTypeError"
InvalidTargetError ErrorCategory = "errors::InvalidTargetError"
InvalidLinkTargetError ErrorCategory = "errors::InvalidLinkTargetError"
InvalidPropertyTargetError ErrorCategory = "errors::InvalidPropertyTargetError"
InvalidReferenceError ErrorCategory = "errors::InvalidReferenceError"
UnknownModuleError ErrorCategory = "errors::UnknownModuleError"
UnknownLinkError ErrorCategory = "errors::UnknownLinkError"
UnknownPropertyError ErrorCategory = "errors::UnknownPropertyError"
UnknownUserError ErrorCategory = "errors::UnknownUserError"
UnknownDatabaseError ErrorCategory = "errors::UnknownDatabaseError"
UnknownParameterError ErrorCategory = "errors::UnknownParameterError"
SchemaError ErrorCategory = "errors::SchemaError"
SchemaDefinitionError ErrorCategory = "errors::SchemaDefinitionError"
InvalidDefinitionError ErrorCategory = "errors::InvalidDefinitionError"
InvalidModuleDefinitionError ErrorCategory = "errors::InvalidModuleDefinitionError"
InvalidLinkDefinitionError ErrorCategory = "errors::InvalidLinkDefinitionError"
InvalidPropertyDefinitionError ErrorCategory = "errors::InvalidPropertyDefinitionError"
InvalidUserDefinitionError ErrorCategory = "errors::InvalidUserDefinitionError"
InvalidDatabaseDefinitionError ErrorCategory = "errors::InvalidDatabaseDefinitionError"
InvalidOperatorDefinitionError ErrorCategory = "errors::InvalidOperatorDefinitionError"
InvalidAliasDefinitionError ErrorCategory = "errors::InvalidAliasDefinitionError"
InvalidFunctionDefinitionError ErrorCategory = "errors::InvalidFunctionDefinitionError"
InvalidConstraintDefinitionError ErrorCategory = "errors::InvalidConstraintDefinitionError"
InvalidCastDefinitionError ErrorCategory = "errors::InvalidCastDefinitionError"
DuplicateDefinitionError ErrorCategory = "errors::DuplicateDefinitionError"
DuplicateModuleDefinitionError ErrorCategory = "errors::DuplicateModuleDefinitionError"
DuplicateLinkDefinitionError ErrorCategory = "errors::DuplicateLinkDefinitionError"
DuplicatePropertyDefinitionError ErrorCategory = "errors::DuplicatePropertyDefinitionError"
DuplicateUserDefinitionError ErrorCategory = "errors::DuplicateUserDefinitionError"
DuplicateDatabaseDefinitionError ErrorCategory = "errors::DuplicateDatabaseDefinitionError"
DuplicateOperatorDefinitionError ErrorCategory = "errors::DuplicateOperatorDefinitionError"
DuplicateViewDefinitionError ErrorCategory = "errors::DuplicateViewDefinitionError"
DuplicateFunctionDefinitionError ErrorCategory = "errors::DuplicateFunctionDefinitionError"
DuplicateConstraintDefinitionError ErrorCategory = "errors::DuplicateConstraintDefinitionError"
DuplicateCastDefinitionError ErrorCategory = "errors::DuplicateCastDefinitionError"
QueryTimeoutError ErrorCategory = "errors::QueryTimeoutError"
ExecutionError ErrorCategory = "errors::ExecutionError"
InvalidValueError ErrorCategory = "errors::InvalidValueError"
DivisionByZeroError ErrorCategory = "errors::DivisionByZeroError"
NumericOutOfRangeError ErrorCategory = "errors::NumericOutOfRangeError"
IntegrityError ErrorCategory = "errors::IntegrityError"
ConstraintViolationError ErrorCategory = "errors::ConstraintViolationError"
CardinalityViolationError ErrorCategory = "errors::CardinalityViolationError"
MissingRequiredError ErrorCategory = "errors::MissingRequiredError"
TransactionError ErrorCategory = "errors::TransactionError"
TransactionConflictError ErrorCategory = "errors::TransactionConflictError"
TransactionSerializationError ErrorCategory = "errors::TransactionSerializationError"
TransactionDeadlockError ErrorCategory = "errors::TransactionDeadlockError"
ConfigurationError ErrorCategory = "errors::ConfigurationError"
AccessError ErrorCategory = "errors::AccessError"
AuthenticationError ErrorCategory = "errors::AuthenticationError"
ClientError ErrorCategory = "errors::ClientError"
ClientConnectionError ErrorCategory = "errors::ClientConnectionError"
ClientConnectionFailedError ErrorCategory = "errors::ClientConnectionFailedError"
ClientConnectionFailedTemporarilyError ErrorCategory = "errors::ClientConnectionFailedTemporarilyError"
ClientConnectionTimeoutError ErrorCategory = "errors::ClientConnectionTimeoutError"
ClientConnectionClosedError ErrorCategory = "errors::ClientConnectionClosedError"
InterfaceError ErrorCategory = "errors::InterfaceError"
QueryArgumentError ErrorCategory = "errors::QueryArgumentError"
MissingArgumentError ErrorCategory = "errors::MissingArgumentError"
UnknownArgumentError ErrorCategory = "errors::UnknownArgumentError"
InvalidArgumentError ErrorCategory = "errors::InvalidArgumentError"
NoDataError ErrorCategory = "errors::NoDataError"
)ErrorTag is the argument type to Error.HasTag().
type ErrorTag stringconst (
ShouldRetry ErrorTag = "SHOULD_RETRY"
ShouldReconnect ErrorTag = "SHOULD_RECONNECT"
)IsolationLevel documentation can be found here https://www.edgedb.com/docs/edgeql/statements/tx_start#parameters
type IsolationLevel stringThe available levels are:
const (
Serializable IsolationLevel = "serializable"
RepeatableRead IsolationLevel = "repeatable_read"
)Options for connecting to an EdgeDB server
type Options struct {
// Hosts is a slice of database host addresses as one of the following
//
// - an IP address or domain name
//
// - an absolute path to the directory
// containing the database server Unix-domain socket
// (not supported on Windows)
//
// If the slice is empty, the following will be tried, in order:
//
// - host address(es) parsed from the dsn argument
//
// - the value of the EDGEDB_HOST environment variable
//
// - on Unix, common directories used for EdgeDB Unix-domain sockets:
// "/run/edgedb" and "/var/run/edgedb"
//
// - "localhost"
Hosts []string
// Ports is a slice of port numbers to connect to at the server host
// (or Unix-domain socket file extension).
//
// Ports may either be:
//
// - the same length ans Hosts
//
// - a single port to be used all specified hosts
//
// - empty indicating the value parsed from the dsn argument
// should be used, or the value of the EDGEDB_PORT environment variable,
// or 5656 if neither is specified.
Ports []int
// User is the name of the database role used for authentication.
// If not specified, the value parsed from the dsn argument is used,
// or the value of the EDGEDB_USER environment variable,
// or the operating system name of the user running the application.
User string
// Database is the name of the database to connect to.
// If not specified, the value parsed from the dsn argument is used,
// or the value of the EDGEDB_DATABASE environment variable,
// or the operating system name of the user running the application.
Database string
// Password to be used for authentication,
// if the server requires one. If not specified,
// the value parsed from the dsn argument is used,
// or the value of the EDGEDB_PASSWORD environment variable.
// Note that the use of the environment variable is discouraged
// as other users and applications may be able to read it
// without needing specific privileges.
Password string
// ConnectTimeout is used when establishing connections in the background.
ConnectTimeout time.Duration
// WaitUntilAvailable determines how long to wait
// to reestablish a connection.
WaitUntilAvailable time.Duration
// MinConns determines the minimum number of connections.
// If MinConns is zero, 1 will be used.
// Has no effect for single connections.
MinConns uint
// MaxConns determines the maximum number of connections.
// If MaxConns is zero, max(4, runtime.NumCPU()) will be used.
// Has no effect for single connections.
MaxConns uint
// ServerSettings is currently unused.
ServerSettings map[string]string
}Pool is a connection pool and is safe for concurrent use.
type Pool struct {
// contains filtered or unexported fields
}func Connect(ctx context.Context, opts Options) (*Pool, error)Connect a pool of connections to a server.
func ConnectDSN(ctx context.Context, dsn string, opts Options) (*Pool, error)ConnectDSN connects a pool to a server.
dsn is either an instance name https://www.edgedb.com/docs/clients/00_python/instances/#edgedb-instances or it specifies a single string in the following format:
edgedb://user:password@host:port/database?option=value.The following options are recognized: host, port, user, database, password.
func (p *Pool) Acquire(ctx context.Context) (*PoolConn, error)Acquire returns a connection from the pool blocking until a connection is available. Acquired connections must be released to the pool when no longer needed.
func (p *Pool) Close() errorClose 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.
func (p *Pool) Execute(ctx context.Context, cmd string) errorExecute an EdgeQL command (or commands).
func (p *Pool) Query(
ctx context.Context,
cmd string,
out interface{},
args ...interface{},
) errorQuery runs a query and returns the results.
func (p *Pool) QueryJSON(
ctx context.Context,
cmd string,
out *[]byte,
args ...interface{},
) errorQueryJSON runs a query and return the results as JSON.
func (p *Pool) QueryOne(
ctx context.Context,
cmd string,
out interface{},
args ...interface{},
) errorQueryOne runs a singleton-returning query and returns its element. If the query executes successfully but doesn’t return a result a NoDataError is returned.
func (p *Pool) QueryOneJSON(
ctx context.Context,
cmd string,
out *[]byte,
args ...interface{},
) errorQueryOneJSON runs a singleton-returning query. If the query executes successfully but doesn’t have a result a NoDataError is returned.
func (p *Pool) RawTx(ctx context.Context, action Action) errorRawTx runs an action in a transaction. If the action returns an error the transaction is rolled back, otherwise it is committed.
func (p *Pool) RetryingTx(ctx context.Context, action Action) errorRetryingTx does the same as RawTx but retries 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.
PoolConn is a pooled connection.
type PoolConn struct {
// contains filtered or unexported fields
}func (c *PoolConn) Execute(ctx context.Context, cmd string) errorExecute an EdgeQL command (or commands).
func (c *PoolConn) Query(
ctx context.Context,
cmd string,
out interface{},
args ...interface{},
) errorQuery runs a query and returns the results.
func (c *PoolConn) QueryJSON(
ctx context.Context,
cmd string,
out *[]byte,
args ...interface{},
) errorQueryJSON runs a query and return the results as JSON.
func (c *PoolConn) QueryOne(
ctx context.Context,
cmd string,
out interface{},
args ...interface{},
) errorQueryOne runs a singleton-returning query and returns its element. If the query executes successfully but doesn’t return a result a NoDataError is returned.
func (c *PoolConn) QueryOneJSON(
ctx context.Context,
cmd string,
out *[]byte,
args ...interface{},
) errorQueryOneJSON runs a singleton-returning query. If the query executes successfully but doesn’t have a result a NoDataError is returned.
func (c *PoolConn) RawTx(ctx context.Context, action Action) errorRawTx runs an action in a transaction. If the action returns an error the transaction is rolled back, otherwise it is committed.
func (c *PoolConn) Release() errorRelease the connection back to its pool. Release returns an error if called more than once. A PoolConn is not usable after Release has been called.
func (c *PoolConn) RetryingTx(ctx context.Context, action Action) errorRetryingTx does the same as RawTx but retries failed actions if they might succeed on a subsequent attempt.
RetryBackoff returns the duration to wait after the nth attempt before making the next attempt when retrying a transaction.
type RetryBackoff func(n int) time.DurationRetryCondition represents scenarios that can caused a transaction run in RetryingTx() methods to be retried.
type RetryCondition intRetryOptions configures how RetryingTx() retries failed transactions. Use NewRetryOptions to get a default RetryOptions value instead of creating one yourself.
type RetryOptions struct {
// contains filtered or unexported fields
}RetryRule determines how transactions should be retried when run in RetryingTx() methods. See Pool.RetryingTx() for details.
type RetryRule struct {
// contains filtered or unexported fields
}func NewRetryRule() RetryRuleNewRetryRule returns the default RetryRule value.
Tx is a transaction. Use RetryingTx() or RawTx() to get a transaction.
type Tx struct {
// contains filtered or unexported fields
}func (t *Tx) Execute(ctx context.Context, cmd string) errorExecute an EdgeQL command (or commands).
func (t *Tx) Query(
ctx context.Context,
cmd string,
out interface{},
args ...interface{},
) errorQuery runs a query and returns the results.
func (t *Tx) QueryJSON(
ctx context.Context,
cmd string,
out *[]byte,
args ...interface{},
) errorQueryJSON runs a query and return the results as JSON.
TxOptions configures how transactions behave.
type TxOptions struct {
// contains filtered or unexported fields
}func NewTxOptions() TxOptionsNewTxOptions returns the default TxOptions value.
func (o TxOptions) WithDeferrable(d bool) TxOptionsWithDeferrable returns a shallow copy of the pool with the transaction deferrable mode set to d.
