我的书签
添加书签
移除书签API
type Client
Client is a connection pool and is safe for concurrent use.
1. type Client struct {
2. // contains filtered or unexported fields
3. }
function CreateClient
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.
function CreateClientDSN
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.
method Close
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.
method EnsureConnected
1. func (p *Client) EnsureConnected(ctx context.Context) error
EnsureConnected forces the client to connect if it hasn’t already.
method Execute
1. func (p *Client) Execute(ctx context.Context, cmd string) error
Execute an EdgeQL command (or commands).
method Query
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.
method QueryJSON
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.
method QuerySingle
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.
method QuerySingleJSON
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.
method Tx
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.
method WithRetryOptions
1. func (p Client) WithRetryOptions(
2. opts RetryOptions,
3. ) *Client
WithRetryOptions returns a shallow copy of the client with the RetryOptions set to opts.
method WithTxOptions
1. func (p Client) WithTxOptions(opts TxOptions) *Client
WithTxOptions returns a shallow copy of the client with the TxOptions set to opts.
type Error
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. }
type ErrorCategory
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. ResultCardinalityMismatchError ErrorCategory = "errors::ResultCardinalityMismatchError"
11. CapabilityError ErrorCategory = "errors::CapabilityError"
12. UnsupportedCapabilityError ErrorCategory = "errors::UnsupportedCapabilityError"
13. DisabledCapabilityError ErrorCategory = "errors::DisabledCapabilityError"
14. QueryError ErrorCategory = "errors::QueryError"
15. InvalidSyntaxError ErrorCategory = "errors::InvalidSyntaxError"
16. EdgeQLSyntaxError ErrorCategory = "errors::EdgeQLSyntaxError"
17. SchemaSyntaxError ErrorCategory = "errors::SchemaSyntaxError"
18. GraphQLSyntaxError ErrorCategory = "errors::GraphQLSyntaxError"
19. InvalidTypeError ErrorCategory = "errors::InvalidTypeError"
20. InvalidTargetError ErrorCategory = "errors::InvalidTargetError"
21. InvalidLinkTargetError ErrorCategory = "errors::InvalidLinkTargetError"
22. InvalidPropertyTargetError ErrorCategory = "errors::InvalidPropertyTargetError"
23. InvalidReferenceError ErrorCategory = "errors::InvalidReferenceError"
24. UnknownModuleError ErrorCategory = "errors::UnknownModuleError"
25. UnknownLinkError ErrorCategory = "errors::UnknownLinkError"
26. UnknownPropertyError ErrorCategory = "errors::UnknownPropertyError"
27. UnknownUserError ErrorCategory = "errors::UnknownUserError"
28. UnknownDatabaseError ErrorCategory = "errors::UnknownDatabaseError"
29. UnknownParameterError ErrorCategory = "errors::UnknownParameterError"
30. SchemaError ErrorCategory = "errors::SchemaError"
31. SchemaDefinitionError ErrorCategory = "errors::SchemaDefinitionError"
32. InvalidDefinitionError ErrorCategory = "errors::InvalidDefinitionError"
33. InvalidModuleDefinitionError ErrorCategory = "errors::InvalidModuleDefinitionError"
34. InvalidLinkDefinitionError ErrorCategory = "errors::InvalidLinkDefinitionError"
35. InvalidPropertyDefinitionError ErrorCategory = "errors::InvalidPropertyDefinitionError"
36. InvalidUserDefinitionError ErrorCategory = "errors::InvalidUserDefinitionError"
37. InvalidDatabaseDefinitionError ErrorCategory = "errors::InvalidDatabaseDefinitionError"
38. InvalidOperatorDefinitionError ErrorCategory = "errors::InvalidOperatorDefinitionError"
39. InvalidAliasDefinitionError ErrorCategory = "errors::InvalidAliasDefinitionError"
40. InvalidFunctionDefinitionError ErrorCategory = "errors::InvalidFunctionDefinitionError"
41. InvalidConstraintDefinitionError ErrorCategory = "errors::InvalidConstraintDefinitionError"
42. InvalidCastDefinitionError ErrorCategory = "errors::InvalidCastDefinitionError"
43. DuplicateDefinitionError ErrorCategory = "errors::DuplicateDefinitionError"
44. DuplicateModuleDefinitionError ErrorCategory = "errors::DuplicateModuleDefinitionError"
45. DuplicateLinkDefinitionError ErrorCategory = "errors::DuplicateLinkDefinitionError"
46. DuplicatePropertyDefinitionError ErrorCategory = "errors::DuplicatePropertyDefinitionError"
47. DuplicateUserDefinitionError ErrorCategory = "errors::DuplicateUserDefinitionError"
48. DuplicateDatabaseDefinitionError ErrorCategory = "errors::DuplicateDatabaseDefinitionError"
49. DuplicateOperatorDefinitionError ErrorCategory = "errors::DuplicateOperatorDefinitionError"
50. DuplicateViewDefinitionError ErrorCategory = "errors::DuplicateViewDefinitionError"
51. DuplicateFunctionDefinitionError ErrorCategory = "errors::DuplicateFunctionDefinitionError"
52. DuplicateConstraintDefinitionError ErrorCategory = "errors::DuplicateConstraintDefinitionError"
53. DuplicateCastDefinitionError ErrorCategory = "errors::DuplicateCastDefinitionError"
54. QueryTimeoutError ErrorCategory = "errors::QueryTimeoutError"
55. ExecutionError ErrorCategory = "errors::ExecutionError"
56. InvalidValueError ErrorCategory = "errors::InvalidValueError"
57. DivisionByZeroError ErrorCategory = "errors::DivisionByZeroError"
58. NumericOutOfRangeError ErrorCategory = "errors::NumericOutOfRangeError"
59. IntegrityError ErrorCategory = "errors::IntegrityError"
60. ConstraintViolationError ErrorCategory = "errors::ConstraintViolationError"
61. CardinalityViolationError ErrorCategory = "errors::CardinalityViolationError"
62. MissingRequiredError ErrorCategory = "errors::MissingRequiredError"
63. TransactionError ErrorCategory = "errors::TransactionError"
64. TransactionConflictError ErrorCategory = "errors::TransactionConflictError"
65. TransactionSerializationError ErrorCategory = "errors::TransactionSerializationError"
66. TransactionDeadlockError ErrorCategory = "errors::TransactionDeadlockError"
67. ConfigurationError ErrorCategory = "errors::ConfigurationError"
68. AccessError ErrorCategory = "errors::AccessError"
69. AuthenticationError ErrorCategory = "errors::AuthenticationError"
70. ClientError ErrorCategory = "errors::ClientError"
71. ClientConnectionError ErrorCategory = "errors::ClientConnectionError"
72. ClientConnectionFailedError ErrorCategory = "errors::ClientConnectionFailedError"
73. ClientConnectionFailedTemporarilyError ErrorCategory = "errors::ClientConnectionFailedTemporarilyError"
74. ClientConnectionTimeoutError ErrorCategory = "errors::ClientConnectionTimeoutError"
75. ClientConnectionClosedError ErrorCategory = "errors::ClientConnectionClosedError"
76. InterfaceError ErrorCategory = "errors::InterfaceError"
77. QueryArgumentError ErrorCategory = "errors::QueryArgumentError"
78. MissingArgumentError ErrorCategory = "errors::MissingArgumentError"
79. UnknownArgumentError ErrorCategory = "errors::UnknownArgumentError"
80. InvalidArgumentError ErrorCategory = "errors::InvalidArgumentError"
81. NoDataError ErrorCategory = "errors::NoDataError"
82. )
type ErrorTag
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. )
type IsolationLevel
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. RepeatableRead IsolationLevel = "repeatable_read"
4. )
type Options
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. }
type RetryBackoff
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
type RetryCondition
RetryCondition represents scenarios that can caused a transaction run in Tx() methods to be retried.
1. type RetryCondition int
type RetryOptions
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. }
method WithCondition
1. func (o RetryOptions) WithCondition(
2. condition RetryCondition,
3. rule RetryRule,
4. ) RetryOptions
WithCondition sets the retry rule for the specified condition.
method WithDefault
1. func (o RetryOptions) WithDefault(rule RetryRule) RetryOptions
WithDefault sets the rule for all conditions to rule.
type RetryRule
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. }
function NewRetryRule
1. func NewRetryRule() RetryRule
NewRetryRule returns the default RetryRule value.
method WithAttempts
1. func (r RetryRule) WithAttempts(attempts int) RetryRule
WithAttempts sets the rule’s attempts. attempts must be greater than zero.
method WithBackoff
1. func (r RetryRule) WithBackoff(fn RetryBackoff) RetryRule
WithBackoff returns a copy of the RetryRule with backoff set to fn.
type Subtx
Subtx is a subtransaction.
1. type Subtx struct {
2. // contains filtered or unexported fields
3. }
method Execute
1. func (t *Subtx) Execute(ctx context.Context, cmd string) error
Execute an EdgeQL command (or commands).
method Query
1. func (t *Subtx) Query(
2. ctx context.Context,
3. cmd string,
4. out interface{},
5. args ...interface{},
6. ) error
Query runs a query and returns the results.
method QueryJSON
1. func (t *Subtx) 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.
method QuerySingle
1. func (t *Subtx) 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.
method QuerySingleJSON
1. func (t *Subtx) 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.
method Subtx
1. func (t *Subtx) Subtx(ctx context.Context, action SubtxBlock) error
Subtx runs an action in a savepoint. If the action returns an error the savepoint is rolled back, otherwise it is released.
type SubtxBlock
SubtxBlock is work to be done in a subtransaction.
1. type SubtxBlock func(context.Context, *Subtx) error
type TLSOptions
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. }
type TLSSecurityMode
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. )
type Tx
Tx is a transaction. Use Client.Tx() to get a transaction.
1. type Tx struct {
2. // contains filtered or unexported fields
3. }
method Execute
1. func (t *Tx) Execute(ctx context.Context, cmd string) error
Execute an EdgeQL command (or commands).
method Query
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.
method QueryJSON
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.
method QuerySingle
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.
method QuerySingleJSON
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.
method Subtx
1. func (t *Tx) Subtx(ctx context.Context, action SubtxBlock) error
Subtx runs an action in a savepoint. If the action returns an error the savepoint is rolled back, otherwise it is released.
type TxBlock
TxBlock is work to be done in a transaction.
1. type TxBlock func(context.Context, *Tx) error
type TxOptions
TxOptions configures how transactions behave.
1. type TxOptions struct {
2. // contains filtered or unexported fields
3. }
function NewTxOptions
1. func NewTxOptions() TxOptions
NewTxOptions returns the default TxOptions value.
method WithDeferrable
1. func (o TxOptions) WithDeferrable(d bool) TxOptions
WithDeferrable returns a shallow copy of the client with the transaction deferrable mode set to d.
method WithIsolation
1. func (o TxOptions) WithIsolation(i IsolationLevel) TxOptions
WithIsolation returns a copy of the TxOptions with the isolation level set to i.
method WithReadOnly
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.
