edgedb

package module
v0.9.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 15, 2022 License: Apache-2.0 Imports: 44 Imported by: 0

README

The Go driver for EdgeDB

Build Status Join GitHub discussions

Installation

$ go get github.com/edgedb/edgedb-go

Basic Usage

Follow the EdgeDB tutorial to get EdgeDB installed and minimally configured.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/edgedb/edgedb-go"
)

func main() {
	opts := edgedb.Options{
		Database:    "edgedb",
		User:        "edgedb",
		Concurrency: 4,
	}

	ctx := context.Background()
	client, err := edgedb.CreateClient(ctx, opts)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	var result string
	err = client.QuerySingle(ctx, "SELECT 'hello EdgeDB!'", &result)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result)
}

Development

A local installation of EdgeDB is required to run tests. Download EdgeDB from here or build it manually.

To run the test suite run make test. To run lints make lint.

License

edgedb-go is developed and distributed under the Apache 2.0 license.

Documentation

Overview

Package edgedb is the official Go EdgeDB driver. https://www.edgedb.com

Typical usage looks like this: 

package main

import (
    "context"
    "log"

    "github.com/edgedb/edgedb-go"
)

func main() {
    ctx := context.Background()
    client, err := edgedb.CreateClient(ctx, edgedb.Options{})
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    var (
        age   int64 = 21
        users []struct {
            ID   edgedb.UUID `edgedb:"id"`
            Name string      `edgedb:"name"`
        }
    )

    query := "SELECT User{name} FILTER .age = <int64>$0"
    err = client.Query(ctx, query, &users, age)
    ...
}

You can also connect to a database using a DSN: 

url := "edgedb://edgedb@localhost/edgedb"
client, err := edgedb.CreateClientDSN(ctx, url, opts)

Or you can use Option fields. 

opts := edgedb.Options{
    Database:    "edgedb",
    User:        "edgedb",
    Concurrency: 4,
}

client, err := edgedb.CreateClient(ctx, opts)

Errors

edgedb never returns underlying errors directly. If you are checking for things like context expiration use errors.Is() or errors.As(). 

err := client.Query(...)
if errors.Is(err, context.Canceled) { ... }

Most errors returned by the edgedb package will satisfy the edgedb.Error interface which has methods for introspecting. 

err := client.Query(...)

var edbErr edgedb.Error
if errors.As(err, &edbErr) && edbErr.Category(edgedb.NoDataError){
    ...
}

Datatypes

The following list shows the marshal/unmarshal mapping between EdgeDB types and go types: 

EdgeDB                   Go
---------                ---------
Set                      []anytype
array<anytype>           []anytype
tuple                    struct
named tuple              struct
Object                   struct
bool                     bool, edgedb.OptionalBool
bytes                    []byte, edgedb.OptionalBytes
str                      string, edgedb.OptionalStr
anyenum                  string, edgedb.OptionalStr
datetime                 time.Time, edgedb.OptionalDateTime
cal::local_datetime      edgedb.LocalDateTime,
                         edgedb.OptionalLocalDateTime
cal::local_date          edgedb.LocalDate, edgedb.OptionalLocalDate
cal::local_time          edgedb.LocalTime, edgedb.OptionalLocalTime
duration                 time.Duration, edgedb.OptionalDuration
cal::relative_duraation  edgedb.RelativeDuration,
                         edgedb.OptionalRelativeDuration
float32                  float32, edgedb.OptionalFloat32
float64                  float64, edgedb.OptionalFloat64
int16                    int16, edgedb.OptionalFloat16
int32                    int32, edgedb.OptionalInt16
int64                    int64, edgedb.OptionalInt64
uuid                     edgedb.UUID, edgedb.OptionalUUID
json                     []byte, edgedb.OptionalBytes
bigint                   *big.Int, edgedb.OptionalBigInt

decimal                  user defined (see Custom Marshalers)

Shape fields that are not required must use optional types for receiving query results. The edgedb.Optional struct can be embedded to make structs optional.

Custom Marshalers

Interfaces for user defined marshaler/unmarshalers are documented in the internal/marshal package.

Example 
// This source file is part of the EdgeDB open source project.
//
// Copyright 2020-present EdgeDB Inc. and the EdgeDB authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/edgedb/edgedb-go"
)

type User struct {
	ID   edgedb.UUID `edgedb:"id"`
	Name string      `edgedb:"name"`
	DOB  time.Time   `edgedb:"dob"`
}

func main() {
	opts := edgedb.Options{Concurrency: 4}
	ctx := context.Background()
	db, err := edgedb.CreateClientDSN(ctx, "edgedb://edgedb@localhost/test", opts)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	// create a user object type.
	err = db.Execute(ctx, `
		CREATE TYPE User {
			CREATE REQUIRED PROPERTY name -> str;
			CREATE PROPERTY dob -> datetime;
		}
	`)
	if err != nil {
		log.Fatal(err)
	}

	// Insert a new user.
	var inserted struct{ id edgedb.UUID }
	err = db.QuerySingle(ctx, `
		INSERT User {
			name := <str>$0,
			dob := <datetime>$1
		}
	`, &inserted, "Bob", time.Date(1984, 3, 1, 0, 0, 0, 0, time.UTC))
	if err != nil {
		log.Fatal(err)
	}

	// Select users.
	var users []User
	args := map[string]interface{}{"name": "Bob"}
	query := "SELECT User {name, dob} FILTER .name = <str>$name"
	err = db.Query(ctx, query, &users, args)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(users)
}

Index

Examples

Constants

View Source 
const (
	// TxConflict indicates that the server could not complete a transaction
	// because it encountered a deadlock or serialization error.
	TxConflict = iota

	// NetworkError indicates that the transaction was interupted
	// by a network error.
	NetworkError
)

The following conditions can be configured with a custom RetryRule. See RetryOptions.

Variables

View Source 
var (
	// ParseUUID parses s into a UUID or returns an error.
	ParseUUID = edgedbtypes.ParseUUID

	// NewLocalDateTime returns a new LocalDateTime
	NewLocalDateTime = edgedbtypes.NewLocalDateTime

	// NewLocalDate returns a new LocalDate
	NewLocalDate = edgedbtypes.NewLocalDate

	// NewLocalTime returns a new LocalTime
	NewLocalTime = edgedbtypes.NewLocalTime

	// NewRelativeDuration returns a new RelativeDuration
	NewRelativeDuration = edgedbtypes.NewRelativeDuration
)

Functions

This section is empty.

Types

type Client added in v0.9.0 

type Client struct {
	// contains filtered or unexported fields
}

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

func CreateClient added in v0.9.0 

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.

func CreateClientDSN added in v0.9.0 

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: 

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

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

func (*Client) Close added in v0.9.0 

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.

func (*Client) EnsureConnected added in v0.9.0 

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

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

func (*Client) Execute added in v0.9.0 

func (p *Client) Execute(ctx context.Context, cmd string) error

Execute an EdgeQL command (or commands).

func (*Client) Query added in v0.9.0 

func (p *Client) Query(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) error

Query runs a query and returns the results.

func (*Client) QueryJSON added in v0.9.0 

func (p *Client) QueryJSON(
	ctx context.Context,
	cmd string,
	out *[]byte,
	args ...interface{},
) error

QueryJSON runs a query and return the results as JSON.

func (*Client) QuerySingle added in v0.9.0 

func (p *Client) QuerySingle(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) 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.

func (*Client) QuerySingleJSON added in v0.9.0 

func (p *Client) QuerySingleJSON(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) error

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

func (*Client) Tx added in v0.9.0 

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.

func (Client) WithRetryOptions added in v0.9.0 

func (p Client) WithRetryOptions(
	opts RetryOptions,
) *Client

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

func (Client) WithTxOptions added in v0.9.0 

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

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

type Duration 

type Duration = edgedbtypes.Duration

Duration represents a span of time.

type Error 

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
}

Error is the error type returned from edgedb.

type ErrorCategory 

type ErrorCategory string

ErrorCategory values represent EdgeDB's error types. 

const (
	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"
)

type ErrorTag 

type ErrorTag string

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

const (
	ShouldRetry     ErrorTag = "SHOULD_RETRY"
	ShouldReconnect ErrorTag = "SHOULD_RECONNECT"
)

type IsolationLevel added in v0.6.0 

type IsolationLevel string

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

const (
	Serializable   IsolationLevel = "serializable"
	RepeatableRead IsolationLevel = "repeatable_read"
)

The available levels are:

type LocalDate 

type LocalDate = edgedbtypes.LocalDate

LocalDate is a date without a time zone.

type LocalDateTime 

type LocalDateTime = edgedbtypes.LocalDateTime

LocalDateTime is a date and time without a time zone.

type LocalTime 

type LocalTime = edgedbtypes.LocalTime

LocalTime is a time without a time zone.

type Memory added in v0.9.0 

type Memory = edgedbtypes.Memory

Memory represents memory in bytes

type Optional added in v0.8.0 

type Optional = edgedbtypes.Optional

Optional ...

type OptionalBigInt added in v0.8.0 

type OptionalBigInt = edgedbtypes.OptionalBigInt

OptionalBigInt is a big.Int that is not required.

func NewOptionalBigInt added in v0.8.1 

func NewOptionalBigInt(v *big.Int) OptionalBigInt

NewOptionalBigInt is a convenience function for creating an OptionalBigInt with its value set to v.

type OptionalBool added in v0.7.0 

type OptionalBool = edgedbtypes.OptionalBool

OptionalBool is a bool value that is not required.

func NewOptionalBool added in v0.7.0 

func NewOptionalBool(v bool) OptionalBool

NewOptionalBool is a convenience function for creating an OptionalBool with its value set to v.

type OptionalBytes added in v0.8.0 

type OptionalBytes = edgedbtypes.OptionalBytes

OptionalBytes is a []byte value that is not required.

func NewOptionalBytes added in v0.8.1 

func NewOptionalBytes(v []byte) OptionalBytes

NewOptionalBytes is a convenience function for creating an OptionalBytes with its value set to v.

type OptionalDateTime added in v0.8.0 

type OptionalDateTime = edgedbtypes.OptionalDateTime

OptionalDateTime is a time.Time that is not required.

func NewOptionalDateTime added in v0.8.1 

func NewOptionalDateTime(v time.Time) OptionalDateTime

NewOptionalDateTime is a convenience function for creating an OptionalDateTime with its value set to v.

type OptionalDuration added in v0.8.0 

type OptionalDuration = edgedbtypes.OptionalDuration

OptionalDuration is a Duration that is not required.

func NewOptionalDuration added in v0.8.1 

func NewOptionalDuration(v Duration) OptionalDuration

NewOptionalDuration is a convenience function for creating an OptionalDuration with its value set to v.

type OptionalFloat32 added in v0.8.0 

type OptionalFloat32 = edgedbtypes.OptionalFloat32

OptionalFloat32 is a float32 that is not required.

func NewOptionalFloat32 added in v0.8.1 

func NewOptionalFloat32(v float32) OptionalFloat32

NewOptionalFloat32 is a convenience function for creating an OptionalFloat32 with its value set to v.

type OptionalFloat64 added in v0.8.0 

type OptionalFloat64 = edgedbtypes.OptionalFloat64

OptionalFloat64 is a float64 that is not required.

func NewOptionalFloat64 added in v0.8.1 

func NewOptionalFloat64(v float64) OptionalFloat64

NewOptionalFloat64 is a convenience function for creating an OptionalFloat64 with its value set to v.

type OptionalInt16 added in v0.8.0 

type OptionalInt16 = edgedbtypes.OptionalInt16

OptionalInt16 is an int16 that is not required.

func NewOptionalInt16 added in v0.8.1 

func NewOptionalInt16(v int16) OptionalInt16

NewOptionalInt16 is a convenience function for creating an OptionalInt16 with its value set to v.

type OptionalInt32 added in v0.8.0 

type OptionalInt32 = edgedbtypes.OptionalInt32

OptionalInt32 is an int32 that is not required.

func NewOptionalInt32 added in v0.8.1 

func NewOptionalInt32(v int32) OptionalInt32

NewOptionalInt32 is a convenience function for creating an OptionalInt32 with its value set to v.

type OptionalInt64 added in v0.8.0 

type OptionalInt64 = edgedbtypes.OptionalInt64

OptionalInt64 is an int64 that is not required.

func NewOptionalInt64 added in v0.8.1 

func NewOptionalInt64(v int64) OptionalInt64

NewOptionalInt64 is a convenience function for creating an OptionalInt64 with its value set to v.

type OptionalLocalDate added in v0.8.0 

type OptionalLocalDate = edgedbtypes.OptionalLocalDate

OptionalLocalDate is a LocalDate that is not required.

func NewOptionalLocalDate added in v0.8.1 

func NewOptionalLocalDate(v LocalDate) OptionalLocalDate

NewOptionalLocalDate is a convenience function for creating an OptionalLocalDate with its value set to v.

type OptionalLocalDateTime added in v0.8.0 

type OptionalLocalDateTime = edgedbtypes.OptionalLocalDateTime

OptionalLocalDateTime is a LocalDateTime that is not required.

func NewOptionalLocalDateTime added in v0.8.1 

func NewOptionalLocalDateTime(v LocalDateTime) OptionalLocalDateTime

NewOptionalLocalDateTime is a convenience function for creating an OptionalLocalDateTime with its value set to v.

type OptionalLocalTime added in v0.8.0 

type OptionalLocalTime = edgedbtypes.OptionalLocalTime

OptionalLocalTime is a LocalTime that is not required.

func NewOptionalLocalTime added in v0.8.1 

func NewOptionalLocalTime(v LocalTime) OptionalLocalTime

NewOptionalLocalTime is a convenience function for creating an OptionalLocalTime with its value set to v.

type OptionalMemory added in v0.9.0 

type OptionalMemory = edgedbtypes.OptionalMemory

OptionalMemory is a Memory that is not required.

func NewOptionalMemory added in v0.9.0 

func NewOptionalMemory(v Memory) OptionalMemory

NewOptionalMemory is a convenience function for creating an OptionalMemory with its value set to v.

type OptionalRelativeDuration added in v0.8.0 

type OptionalRelativeDuration = edgedbtypes.OptionalRelativeDuration

OptionalRelativeDuration is a RelativeDuration that is not required.

func NewOptionalRelativeDuration added in v0.8.1 

func NewOptionalRelativeDuration(v RelativeDuration) OptionalRelativeDuration

NewOptionalRelativeDuration is a convenience function for creating an OptionalRelativeDuration with its value set to v.

type OptionalStr added in v0.8.0 

type OptionalStr = edgedbtypes.OptionalStr

OptionalStr is a string that is not required.

func NewOptionalStr added in v0.8.1 

func NewOptionalStr(v string) OptionalStr

NewOptionalStr is a convenience function for creating an OptionalStr with its value set to v.

type OptionalUUID added in v0.8.0 

type OptionalUUID = edgedbtypes.OptionalUUID

OptionalUUID is a UUID that is not required.

func NewOptionalUUID added in v0.8.1 

func NewOptionalUUID(v UUID) OptionalUUID

NewOptionalUUID is a convenience function for creating an OptionalUUID with its value set to v.

type Options 

type Options struct {
	// Host is an EdgeDB server host address, given as either an IP address or
	// domain name. (Unix-domain socket paths are not supported)
	//
	// Host cannot be specified alongside the 'dsn' argument, or
	// CredentialsFile option. Host will override all other credentials
	// resolved from any environment variables, or project credentials with
	// their defaults.
	Host string

	// Port is a port number to connect to at the server host.
	//
	// Port cannot be specified alongside the 'dsn' argument, or
	// CredentialsFile option. Port will override all other credentials
	// resolved from any environment variables, or project credentials with
	// their defaults.
	Port int

	// Credentials is a JSON string containing connection credentials.
	//
	// Credentials cannot be specified alongside the 'dsn' argument, Host,
	// Port, or CredentialsFile.  Credentials will override all other
	// credentials not present in the credentials string with their defaults.
	Credentials []byte

	// CredentialsFile is a path to a file containing connection credentials.
	//
	// CredentialsFile cannot be specified alongside the 'dsn' argument, Host,
	// Port, or Credentials.  CredentialsFile will override all other
	// credentials not present in the credentials file with their defaults.
	CredentialsFile string

	// User is the name of the database role used for authentication.
	//
	// If not specified, the value is resolved from any compound
	// argument/option, then from EDGEDB_USER, then any compound environment
	// variable, then project credentials.
	User string

	// Database is the name of the database to connect to.
	//
	// If not specified, the value is resolved from any compound
	// argument/option, then from EDGEDB_DATABASE, then any compound
	// environment variable, then project credentials.
	Database string

	// Password to be used for authentication, if the server requires one.
	//
	// If not specified, the value is resolved from any compound
	// argument/option, then from EDGEDB_PASSWORD, then any compound
	// environment variable, then project credentials.
	// 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 OptionalStr

	// 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

	// Concurrency determines the maximum number of connections.
	// If Concurrency is zero, max(4, runtime.NumCPU()) will be used.
	// Has no effect for single connections.
	Concurrency uint

	// Parameters used to configure TLS connections to EdgeDB server.
	TLSOptions TLSOptions

	// Read the TLS certificate from this file.
	// DEPRECATED, use TLSOptions.CAFile instead.
	TLSCAFile string

	// Specifies how strict TLS validation is.
	// DEPRECATED, use TLSOptions.SecurityMode instead.
	TLSSecurity string

	// ServerSettings is currently unused.
	ServerSettings map[string][]byte
}

Options for connecting to an EdgeDB server

type RelativeDuration added in v0.7.0 

type RelativeDuration = edgedbtypes.RelativeDuration

RelativeDuration represents a fuzzy/human span of time.

type RetryBackoff added in v0.6.0 

type RetryBackoff func(n int) time.Duration

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

type RetryCondition added in v0.6.0 

type RetryCondition int

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

type RetryOptions added in v0.6.0 

type RetryOptions struct {
	// contains filtered or unexported fields
}

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

func (RetryOptions) WithCondition added in v0.6.0 

func (o RetryOptions) WithCondition(
	condition RetryCondition,
	rule RetryRule,
) RetryOptions

WithCondition sets the retry rule for the specified condition.

func (RetryOptions) WithDefault added in v0.6.0 

func (o RetryOptions) WithDefault(rule RetryRule) RetryOptions

WithDefault sets the rule for all conditions to rule.

type RetryRule added in v0.6.0 

type RetryRule struct {
	// contains filtered or unexported fields
}

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

func NewRetryRule added in v0.6.0 

func NewRetryRule() RetryRule

NewRetryRule returns the default RetryRule value.

func (RetryRule) WithAttempts added in v0.6.0 

func (r RetryRule) WithAttempts(attempts int) RetryRule

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

func (RetryRule) WithBackoff added in v0.6.0 

func (r RetryRule) WithBackoff(fn RetryBackoff) RetryRule

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

type Subtx added in v0.8.0 

type Subtx struct {
	// contains filtered or unexported fields
}

Subtx is a subtransaction.

func (*Subtx) Execute added in v0.8.0 

func (t *Subtx) Execute(ctx context.Context, cmd string) error

Execute an EdgeQL command (or commands).

func (*Subtx) Query added in v0.8.0 

func (t *Subtx) Query(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) error

Query runs a query and returns the results.

func (*Subtx) QueryJSON added in v0.8.0 

func (t *Subtx) QueryJSON(
	ctx context.Context,
	cmd string,
	out *[]byte,
	args ...interface{},
) error

QueryJSON runs a query and return the results as JSON.

func (*Subtx) QuerySingle added in v0.8.0 

func (t *Subtx) QuerySingle(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) 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.

func (*Subtx) QuerySingleJSON added in v0.8.0 

func (t *Subtx) QuerySingleJSON(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) error

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

func (*Subtx) Subtx added in v0.8.0 

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 added in v0.8.0 

type SubtxBlock func(context.Context, *Subtx) error

SubtxBlock is work to be done in a subtransaction.

type TLSOptions added in v0.9.1 

type TLSOptions struct {
	// PEM-encoded CA certificate
	CA []byte
	// Path to a PEM-encoded CA certificate file
	CAFile string
	// Determines how strict we are with TLS checks
	SecurityMode TLSSecurityMode
}

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

type TLSSecurityMode added in v0.9.1 

type TLSSecurityMode string

TLSSecurityMode specifies how strict TLS validation is. 

const (
	// TLSModeDefault makes security mode inferred from other options
	TLSModeDefault TLSSecurityMode = "default"
	// TLSModeInsecure results in no certificate verification whatsoever
	TLSModeInsecure TLSSecurityMode = "insecure"
	// TLSModeNoHostVerification enables certificate verification
	// against CAs, but hostname matching is not performed.
	TLSModeNoHostVerification TLSSecurityMode = "no_host_verification"
	// TLSModeStrict enables full certificate and hostname verification.
	TLSModeStrict TLSSecurityMode = "strict"
)

type Tx 

type Tx struct {
	// contains filtered or unexported fields
}

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

Example

Transactions can be executed using the Tx() method. Note that queries are executed on the Tx object. Queries executed on the client in a transaction callback will not run in the transaction and will be applied immediately. In edgedb-go the callback may be re-run if any of the queries fail in a way that might succeed on subsequent attempts. Transaction behavior can be configured with TxOptions and the retrying behavior can be configured with RetryOptions. 

err := client.Tx(ctx, func(ctx context.Context, tx *Tx) error {
	return tx.Execute(ctx, "INSERT User { name := 'Don' }")
})
if err != nil {
	log.Println(err)
}

func (*Tx) Execute added in v0.6.0 

func (t *Tx) Execute(ctx context.Context, cmd string) error

Execute an EdgeQL command (or commands).

func (*Tx) Query added in v0.6.0 

func (t *Tx) Query(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) error

Query runs a query and returns the results.

func (*Tx) QueryJSON added in v0.6.0 

func (t *Tx) QueryJSON(
	ctx context.Context,
	cmd string,
	out *[]byte,
	args ...interface{},
) error

QueryJSON runs a query and return the results as JSON.

func (*Tx) QuerySingle added in v0.8.0 

func (t *Tx) QuerySingle(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) 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.

func (*Tx) QuerySingleJSON added in v0.8.0 

func (t *Tx) QuerySingleJSON(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) error

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

func (*Tx) Subtx added in v0.8.0 

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 added in v0.8.0 

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

TxBlock is work to be done in a transaction.

type TxOptions added in v0.6.0 

type TxOptions struct {
	// contains filtered or unexported fields
}

TxOptions configures how transactions behave.

func NewTxOptions added in v0.6.0 

func NewTxOptions() TxOptions

NewTxOptions returns the default TxOptions value.

func (TxOptions) WithDeferrable added in v0.6.0 

func (o TxOptions) WithDeferrable(d bool) TxOptions

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

func (TxOptions) WithIsolation added in v0.6.0 

func (o TxOptions) WithIsolation(i IsolationLevel) TxOptions

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

func (TxOptions) WithReadOnly added in v0.6.0 

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.

type UUID 

type UUID = edgedbtypes.UUID

UUID a universally unique identifier

Source Files

View all Source files

Directories

Path Synopsis
edgedb module
aspect
buff
cache
cardinality
cmd/generr command
codecs
descriptor
edgedbtypes
format
header
introspect
marshal
Package marshal documents marshaling interfaces.
 Package marshal documents marshaling interfaces.
message
snc
soc
Package soc has utilities for working with sockets.
 Package soc has utilities for working with sockets.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.