driver

Documentation

Index

• Constants
• Variables
• type Conn
  • func (c *Conn) Begin() (driver.Tx, error)
  • func (c *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)
  • func (c *Conn) Close() error
  • func (c *Conn) Exec(query string, args []driver.Value) (driver.Result, error)
  • func (c *Conn) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Result, error)
  • func (c *Conn) Prepare(query string) (driver.Stmt, error)
  • func (c *Conn) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)
  • func (c *Conn) Query(query string, args []driver.Value) (driver.Rows, error)
  • func (c *Conn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Rows, error)
• type Connector
  • func (c *Connector) Connect(ctx context.Context) (driver.Conn, error)
  • func (c *Connector) Driver() driver.Driver
• type DialFunc
• type Driver
  • func New(store client.NodeStore, options ...Option) (*Driver, error)
  • func (d *Driver) Open(uri string) (driver.Conn, error)
  • func (d *Driver) OpenConnector(name string) (driver.Connector, error)
  • func (d *Driver) SetContextTimeout(timeout time.Duration)
• type Error
• type NodeInfo
• type NodeStore
• type Option
  • func WithAttemptTimeout(timeout time.Duration) Option
  • func WithConnectionBackoffCap(cap time.Duration) Option
  • func WithConnectionBackoffFactor(factor time.Duration) Option
  • func WithConnectionTimeout(timeout time.Duration) Option
  • func WithContext(context context.Context) Option
  • func WithContextTimeout(timeout time.Duration) Option
  • func WithDialFunc(dial DialFunc) Option
  • func WithLogFunc(log client.LogFunc) Option
  • func WithRetryLimit(limit uint) Option
  • func WithTracing(level client.LogLevel) Option
• type Result
  • func (r *Result) LastInsertId() (int64, error)
  • func (r *Result) RowsAffected() (int64, error)
• type Rows
  • func (r *Rows) Close() error
  • func (r *Rows) ColumnTypeDatabaseTypeName(i int) string
  • func (r *Rows) ColumnTypeScanType(i int) reflect.Type
  • func (r *Rows) Columns() []string
  • func (r *Rows) Next(dest []driver.Value) error
• type Stmt
  • func (s *Stmt) Close() error
  • func (s *Stmt) Exec(args []driver.Value) (driver.Result, error)
  • func (s *Stmt) ExecContext(ctx context.Context, args []driver.NamedValue) (driver.Result, error)
  • func (s *Stmt) NumInput() int
  • func (s *Stmt) Query(args []driver.Value) (driver.Rows, error)
  • func (s *Stmt) QueryContext(ctx context.Context, args []driver.NamedValue) (driver.Rows, error)
• type Tx
  • func (tx *Tx) Commit() error
  • func (tx *Tx) Rollback() error

Constants

const (
	ErrBusy         = 5
	ErrBusyRecovery = 5 | (1 << 8)
	ErrBusySnapshot = 5 | (2 << 8)
)

Error codes. Values here mostly overlap with native SQLite codes.

Variables

var DefaultNodeStore = client.DefaultNodeStore

DefaultNodeStore is a convenience alias of client.DefaultNodeStore.

var ErrNoAvailableLeader = protocol.ErrNoAvailableLeader

ErrNoAvailableLeader is returned as root cause of Open() if there's no leader available in the cluster.

Types

type Conn

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

Conn implements the sql.Conn interface.

func (*Conn) Begin

func (c *Conn) Begin() (driver.Tx, error)

Begin starts and returns a new transaction.

Deprecated: Drivers should implement ConnBeginTx instead (or additionally).

func (*Conn) BeginTx

func (c *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)

BeginTx starts and returns a new transaction. If the context is canceled by the user the sql package will call Tx.Rollback before discarding and closing the connection.

This must check opts.Isolation to determine if there is a set isolation level. If the driver does not support a non-default level and one is set or if there is a non-default isolation level that is not supported, an error must be returned.

This must also check opts.ReadOnly to determine if the read-only value is true to either set the read-only transaction property if supported or return an error if it is not supported.

func (*Conn) Close

func (c *Conn) Close() error

Close invalidates and potentially stops any current prepared statements and transactions, marking this connection as no longer in use.

Because the sql package maintains a free pool of connections and only calls Close when there's a surplus of idle connections, it shouldn't be necessary for drivers to do their own connection caching.

func (*Conn) Exec

func (c *Conn) Exec(query string, args []driver.Value) (driver.Result, error)

Exec is an optional interface that may be implemented by a Conn.

func (*Conn) ExecContext

func (c *Conn) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Result, error)

ExecContext is an optional interface that may be implemented by a Conn.

func (*Conn) Prepare

func (c *Conn) Prepare(query string) (driver.Stmt, error)

Prepare returns a prepared statement, bound to this connection.

func (*Conn) PrepareContext

func (c *Conn) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)

PrepareContext returns a prepared statement, bound to this connection. context is for the preparation of the statement, it must not store the context within the statement itself.

func (*Conn) Query

func (c *Conn) Query(query string, args []driver.Value) (driver.Rows, error)

Query is an optional interface that may be implemented by a Conn.

func (*Conn) QueryContext

func (c *Conn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Rows, error)

QueryContext is an optional interface that may be implemented by a Conn.

type Connector

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

A Connector represents a driver in a fixed configuration and can create any number of equivalent Conns for use by multiple goroutines.

func (*Connector) Connect

func (c *Connector) Connect(ctx context.Context) (driver.Conn, error)

Connect returns a connection to the database.

func (*Connector) Driver

func (c *Connector) Driver() driver.Driver

Driver returns the underlying Driver of the Connector,

type DialFunc

type DialFunc = protocol.DialFunc

DialFunc is a function that can be used to establish a network connection with a dqlite node.

type Driver

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

Driver perform queries against a dqlite server.

func New

func New(store client.NodeStore, options ...Option) (*Driver, error)

NewDriver creates a new dqlite driver, which also implements the driver.Driver interface.

func (*Driver) Open

func (d *Driver) Open(uri string) (driver.Conn, error)

Open establishes a new connection to a SQLite database on the dqlite server.

The given name must be a pure file name without any directory segment, dqlite will connect to a database with that name in its data directory.

Query parameters are always valid except for "mode=memory".

If this node is not the leader, or the leader is unknown an ErrNotLeader error is returned.

func (*Driver) OpenConnector

func (d *Driver) OpenConnector(name string) (driver.Connector, error)

OpenConnector must parse the name in the same format that Driver.Open parses the name parameter.

func (*Driver) SetContextTimeout

func (d *Driver) SetContextTimeout(timeout time.Duration)

SetContextTimeout sets the default client timeout when no context deadline is provided.

DEPRECATED: This API is no a no-op. Users should explicitly pass a context if they wish to cancel their requests, or use the WithContextTimeout option.

type Error

type Error = protocol.Error

Error is returned in case of database errors.

type NodeInfo

type NodeInfo = client.NodeInfo

NodeInfo is a convenience alias of client.NodeInfo.

type NodeStore

type NodeStore = client.NodeStore

NodeStore is a convenience alias of client.NodeStore.

type Option

type Option func(*options)

Option can be used to tweak driver parameters.

func WithAttemptTimeout

func WithAttemptTimeout(timeout time.Duration) Option

WithAttemptTimeout sets the timeout for each individual connection attempt.

The Connector.Connect() and Driver.Open() methods try to find the current leader among the servers in the store that was passed to New(). Each time they attempt to probe an individual server for leadership this timeout will apply, so a server which accepts the connection but it's then unresponsive won't block the line.

If not used, the default is 15 seconds.

func WithConnectionBackoffCap

func WithConnectionBackoffCap(cap time.Duration) Option

WithConnectionBackoffCap sets the maximum connection retry backoff value, (regardless of the backoff factor) for retrying failed connection attempts.

If not used, the default is 1 second.

func WithConnectionBackoffFactor

func WithConnectionBackoffFactor(factor time.Duration) Option

WithConnectionBackoffFactor sets the exponential backoff factor for retrying failed connection attempts.

If not used, the default is 100 milliseconds.

func WithConnectionTimeout

func WithConnectionTimeout(timeout time.Duration) Option

WithConnectionTimeout sets the connection timeout.

If not used, the default is 5 seconds.

DEPRECATED: Connection cancellation is supported via the driver.Connector interface, which is used internally by the stdlib sql package.

func WithContext

func WithContext(context context.Context) Option

WithContext sets a global cancellation context.

DEPRECATED: This API is no a no-op. Users should explicitly pass a context if they wish to cancel their requests.

func WithContextTimeout

func WithContextTimeout(timeout time.Duration) Option

WithContextTimeout sets the default client context timeout for DB.Begin() when no context deadline is provided.

DEPRECATED: Users should use db APIs that support contexts if they wish to cancel their requests.

func WithDialFunc

func WithDialFunc(dial DialFunc) Option

WithDialFunc sets a custom dial function.

func WithLogFunc

func WithLogFunc(log client.LogFunc) Option

WithLogFunc sets a custom logging function.

func WithRetryLimit

func WithRetryLimit(limit uint) Option

WithRetryLimit sets the maximum number of connection retries.

If not used, the default is 0 (unlimited retries)

func WithTracing

func WithTracing(level client.LogLevel) Option

WithTracing will emit a log message at the given level every time a statement gets executed.

type Result

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

Result is the result of a query execution.

func (*Result) LastInsertId

func (r *Result) LastInsertId() (int64, error)

LastInsertId returns the database's auto-generated ID after, for example, an INSERT into a table with primary key.

func (*Result) RowsAffected

func (r *Result) RowsAffected() (int64, error)

RowsAffected returns the number of rows affected by the query.

type Rows

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

Rows is an iterator over an executed query's results.

func (*Rows) Close

func (r *Rows) Close() error

Close closes the rows iterator.

func (*Rows) ColumnTypeDatabaseTypeName

func (r *Rows) ColumnTypeDatabaseTypeName(i int) string

ColumnTypeDatabaseTypeName implements RowsColumnTypeDatabaseTypeName. warning: not thread safe

func (*Rows) ColumnTypeScanType

func (r *Rows) ColumnTypeScanType(i int) reflect.Type

ColumnTypeScanType implements RowsColumnTypeScanType.

func (*Rows) Columns

func (r *Rows) Columns() []string

Columns returns the names of the columns. The number of columns of the result is inferred from the length of the slice. If a particular column name isn't known, an empty string should be returned for that entry.

func (*Rows) Next

func (r *Rows) Next(dest []driver.Value) error

Next is called to populate the next row of data into the provided slice. The provided slice will be the same size as the Columns() are wide.

Next should return io.EOF when there are no more rows.

type Stmt

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

Stmt is a prepared statement. It is bound to a Conn and not used by multiple goroutines concurrently.

func (*Stmt) Close

func (s *Stmt) Close() error

Close closes the statement.

func (*Stmt) Exec

func (s *Stmt) Exec(args []driver.Value) (driver.Result, error)

Exec executes a query that doesn't return rows, such

func (*Stmt) ExecContext

func (s *Stmt) ExecContext(ctx context.Context, args []driver.NamedValue) (driver.Result, error)

ExecContext executes a query that doesn't return rows, such as an INSERT or UPDATE.

ExecContext must honor the context timeout and return when it is canceled.

func (*Stmt) NumInput

func (s *Stmt) NumInput() int

NumInput returns the number of placeholder parameters.

func (*Stmt) Query

func (s *Stmt) Query(args []driver.Value) (driver.Rows, error)

Query executes a query that may return rows, such as a

func (*Stmt) QueryContext

func (s *Stmt) QueryContext(ctx context.Context, args []driver.NamedValue) (driver.Rows, error)

QueryContext executes a query that may return rows, such as a SELECT.

QueryContext must honor the context timeout and return when it is canceled.

type Tx

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

Tx is a transaction.

func (*Tx) Commit

func (tx *Tx) Commit() error

Commit the transaction.

func (*Tx) Rollback

func (tx *Tx) Rollback() error

Rollback the transaction.