edgedb

package module
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2021 License: Apache-2.0 Imports: 41 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",
		MinConns: 1,
		MaxConns: 4,
	}

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

	var result string
	err = pool.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://edgedb.com

Typical usage looks like this: 

import (
    "context"
    "log"

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

opts := edgedb.Options{
    MinConns: 1,
    MaxConns: 4,
}

func main() {
    ctx := context.Background()
    pool, err := edgedb.ConnectDSN(ctx, "my_instance", opts)
    if err != nil {
        log.Fatal(err)
    }
    defer pool.Close()

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

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

You can also connect to a database using a DSN: 

url := "edgedb://edgedb@localhost/edgedb"
pool, err := edgedb.ConnectDSN(ctx, url, opts)

Or you can use Option fields. 

opts := edgedb.Options{
    Database: "edgedb",
    User:     "edgedb",
    MinConns: 1,
    MaxConns: 4,
}

pool, err := edgedb.Connect(ctx, opts)

Pooling

Most use cases will benefit from the concurrency safe pool implementation returned from Connect() and ConnectDSN(). Pool.RetryingTx() or Pool.RawTx() will give you access to a single connection.

Errors

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

err := pool.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 := pool.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 fileds 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{
		MinConns: 1,
		MaxConns: 4,
	}

	ctx := context.Background()
	db, err := edgedb.ConnectDSN(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 Conn deprecated 

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

Conn is a single Conn to a server. Conn is not safe for concurrent use. Pool should be preferred over Conn for most use cases.

Deprecated: use a Pool from Connect() or ConnectDSN()

func ConnectOne deprecated 

func ConnectOne(ctx context.Context, opts Options) (*Conn, error)

ConnectOne establishes a connection to an EdgeDB server.

Deprecated: use Connect() instead

func ConnectOneDSN deprecated 

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.

Deprecated: use ConnectDSN() instead

func (*Conn) Close 

func (c *Conn) Close() error

Close closes the connection. Connections are not usable after they are closed.

func (*Conn) Execute added in v0.6.0 

func (c *Conn) Execute(ctx context.Context, cmd string) error

Execute an EdgeQL command (or commands).

func (*Conn) Query added in v0.6.0 

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

Query runs a query and returns the results.

func (*Conn) QueryJSON added in v0.6.0 

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

QueryJSON runs a query and return the results as JSON.

func (*Conn) QueryOne deprecated added in v0.6.0 

func (c *Conn) QueryOne(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) error

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

Deprecated: use QuerySingle() instead

func (*Conn) QueryOneJSON deprecated added in v0.6.0 

func (c *Conn) QueryOneJSON(
	ctx context.Context,
	cmd string,
	out *[]byte,
	args ...interface{},
) error

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

Deprecated: use QuerySingleJSON() instead

func (*Conn) QuerySingle added in v0.8.0 

func (c *Conn) 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 (*Conn) QuerySingleJSON added in v0.8.0 

func (c *Conn) QuerySingleJSON(
	ctx context.Context,
	cmd string,
	out *[]byte,
	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 (*Conn) RawTx added in v0.6.0 

func (c *Conn) RawTx(ctx context.Context, action TxBlock) error

RawTx runs an action in a transaction. If the action returns an error the transaction is rolled back, otherwise it is committed.

func (*Conn) RetryingTx added in v0.6.0 

func (c *Conn) RetryingTx(
	ctx context.Context,
	action TxBlock,
) error

RetryingTx does the same as RawTx but retries failed actions if they might succeed on a subsequent attempt.

func (Conn) WithRetryOptions added in v0.6.0 

func (c Conn) WithRetryOptions(opts RetryOptions) *Conn

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

func (Conn) WithTxOptions added in v0.6.0 

func (c Conn) WithTxOptions(opts TxOptions) *Conn

WithTxOptions returns a shallow copy of the connection 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/edgeql/statements/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 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 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 {
	// 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

	// Read the TLS certificate from this file
	TLSCAFile string

	// If false don't verify the server's hostname when using TLS.
	TLSVerifyHostname OptionalBool

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

Options for connecting to an EdgeDB server

type Pool 

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

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

func Connect 

func Connect(ctx context.Context, opts Options) (*Pool, error)

Connect a pool of connections to a server.

func ConnectDSN 

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 (*Pool) Acquire deprecated 

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.

Deprecated: use the query methods on Pool instead

func (*Pool) Close 

func (p *Pool) 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 (*Pool) Execute added in v0.6.0 

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

Execute an EdgeQL command (or commands).

func (*Pool) Query added in v0.6.0 

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

Query runs a query and returns the results.

func (*Pool) QueryJSON added in v0.6.0 

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

QueryJSON runs a query and return the results as JSON.

func (*Pool) QueryOne deprecated added in v0.6.0 

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

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

Deprecated: use QuerySingle()

func (*Pool) QueryOneJSON deprecated added in v0.6.0 

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

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

Deprecated: use QuerySingleJSON()

func (*Pool) QuerySingle added in v0.8.0 

func (p *Pool) 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 (*Pool) QuerySingleJSON added in v0.8.0 

func (p *Pool) QuerySingleJSON(
	ctx context.Context,
	cmd string,
	out *[]byte,
	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 (*Pool) RawTx added in v0.6.0 

func (p *Pool) RawTx(ctx context.Context, action TxBlock) error

RawTx runs an action in a transaction. If the action returns an error the transaction is rolled back, otherwise it is committed.

func (*Pool) RetryingTx added in v0.6.0 

func (p *Pool) RetryingTx(ctx context.Context, action TxBlock) error

RetryingTx 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.

func (Pool) WithRetryOptions added in v0.6.0 

func (p Pool) WithRetryOptions(opts RetryOptions) *Pool

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

func (Pool) WithTxOptions added in v0.6.0 

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

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

type PoolConn deprecated 

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

PoolConn is a pooled connection.

Deprecated: use the query methods on Pool instead

func (*PoolConn) Execute added in v0.6.0 

func (c *PoolConn) Execute(ctx context.Context, cmd string) error

Execute an EdgeQL command (or commands).

func (*PoolConn) Query added in v0.6.0 

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

Query runs a query and returns the results.

func (*PoolConn) QueryJSON added in v0.6.0 

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

QueryJSON runs a query and return the results as JSON.

func (*PoolConn) QueryOne deprecated added in v0.6.0 

func (c *PoolConn) QueryOne(
	ctx context.Context,
	cmd string,
	out interface{},
	args ...interface{},
) error

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

Deprecated: use QuerySingle()

func (*PoolConn) QueryOneJSON deprecated added in v0.6.0 

func (c *PoolConn) QueryOneJSON(
	ctx context.Context,
	cmd string,
	out *[]byte,
	args ...interface{},
) error

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

Deprecated: use QuerySingleJSON()

func (*PoolConn) QuerySingle added in v0.8.0 

func (c *PoolConn) 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 (*PoolConn) QuerySingleJSON added in v0.8.0 

func (c *PoolConn) QuerySingleJSON(
	ctx context.Context,
	cmd string,
	out *[]byte,
	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 (*PoolConn) RawTx added in v0.6.0 

func (c *PoolConn) RawTx(ctx context.Context, action TxBlock) error

RawTx runs an action in a transaction. If the action returns an error the transaction is rolled back, otherwise it is committed.

func (*PoolConn) Release 

func (c *PoolConn) Release() error

Release 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 (*PoolConn) RetryingTx added in v0.6.0 

func (c *PoolConn) RetryingTx(ctx context.Context, action TxBlock) error

RetryingTx does the same as RawTx but retries failed actions if they might succeed on a subsequent attempt.

func (PoolConn) WithRetryOptions added in v0.6.0 

func (c PoolConn) WithRetryOptions(opts RetryOptions) *PoolConn

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

func (PoolConn) WithTxOptions added in v0.6.0 

func (c PoolConn) WithTxOptions(opts TxOptions) *PoolConn

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

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 RetryingTx() methods to be retried.

type RetryOptions added in v0.6.0 

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

RetryOptions configures how RetryingTx() 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 RetryingTx() methods. See Pool.RetryingTx() 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 *[]byte,
	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 Tx 

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

Tx is a transaction. Use RetryingTx() or RawTx() to get a transaction.

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) QueryOne deprecated added in v0.6.0 

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

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

Deprecated: use QuerySingle()

func (*Tx) QueryOneJSON deprecated added in v0.6.0 

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

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

Deprecated: use QuerySingleJSON()

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 *[]byte,
	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 pool 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 pool 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
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.