sql

Documentation

Overview

Package sql defines common type required by SQL database implementations and consumers.

Index

• Variables
• func Int64(val interface{}) (int64, bool)
• func IsFatalDBError(err error) bool
• type AccessMode
• type AccessModer
• type ColumnStatistics
• type CommandTag
• type DB
• type DelayedReadTxMaker
• type Executor
• type OuterReadTx
• type PreparedTx
• type PreparedTxMaker
• type QueryScanner
• type ReadTxMaker
• type ResultSet
• type SnapshotTxMaker
• type Statistics
  • func (s *Statistics) String() string
• type Subscriber
• type Tx
• type TxMaker
• type ValCount

Variables

var (
	ErrNoTransaction = errors.New("no transaction")
	ErrNoRows        = errors.New("no rows in result set")
	ErrDBFailure     = errors.New("database failure") // fatal! should kill node
)

Functions

func Int64

func Int64(val interface{}) (int64, bool)

func IsFatalDBError

func IsFatalDBError(err error) bool

Types

type AccessMode

type AccessMode uint8

AccessMode is the type of access to a database. It can be read-write or read-only.

const (
	// ReadWrite is the default access mode.
	// It allows for reading and writing to the database.
	ReadWrite AccessMode = iota
	// ReadOnly allows for reading from the database, but not writing.
	ReadOnly
)

type AccessModer

type AccessModer interface {
	// AccessMode gets the access mode of the database or transaction.
	AccessMode() AccessMode
}

AccessModer may be satisfied by implementations of Tx and DB, but is not universally required for those interfaces (type assert as needed).

type ColumnStatistics

type ColumnStatistics struct {
	NullCount int64

	Min      any
	MinCount int

	Max      any
	MaxCount int

	// DistinctCount is harder. For example, unless we sub-sample
	// (deterministically), tracking distinct values could involve a data
	// structure with the same number of elements as rows in the table.
	DistinctCount int64

	AvgSize int64 // maybe: length of text, length of array, otherwise not used for scalar?

}

ColumnStatistics contains statistics about a column.

type CommandTag

type CommandTag struct {
	// Text is the text of the command tag.
	Text string
	// RowsAffected is the number of rows affected by the command.
	RowsAffected int64
}

CommandTag is the result of a command execution.

type DB

type DB interface {
	Executor
	TxMaker
}

DB is a top level database interface, which may directly execute queries or create transactions, which may be closed or create additional nested transactions.

Some implementations may also be an PreparedTxMaker and/or a ReadTxMaker. Embed with those interfaces to compose the minimal interface required.

type DelayedReadTxMaker

type DelayedReadTxMaker interface {
	BeginDelayedReadTx() OuterReadTx
}

DelayedReadTxMaker is an interface that creates a transaction for reading from the database. The transaction won't actually be created until it is used for the first time, which is useful for avoiding unnecessary transactions.

type Executor

type Executor interface {
	// Execute executes a query or command.
	Execute(ctx context.Context, stmt string, args ...any) (*ResultSet, error)
}

Executor is an interface that can execute queries.

type OuterReadTx

type OuterReadTx interface {
	Tx
	Subscriber
}

OuterReadTx is the outermost read-only database transaction.

type PreparedTx

type PreparedTx interface {
	Tx
	Subscriber
	Precommit(ctx context.Context, changes chan<- any) ([]byte, error)
}

PreparedTx is an outermost database transaction that uses two-phase commit with the Precommit method.

NOTE: A PreparedTx may be used where only a Tx or DB is required since those interfaces are a subset of the PreparedTx method set. It takes a writer to write the full changeset to. If the writer is nil, the changeset will not be written.

type PreparedTxMaker

type PreparedTxMaker interface {
	BeginPreparedTx(ctx context.Context) (PreparedTx, error)
}

PreparedTxMaker is the special kind of transaction that creates a transaction that has a Precommit method (see OuterTx), which supports obtaining a commit ID using a (two-phase) prepared transaction prior to Commit. This is a different method name so that an implementation may satisfy both PreparedTxMaker and TxMaker.

type QueryScanner

type QueryScanner interface {
	QueryScanFn(ctx context.Context, stmt string,
		scans []any, fn func() error, args ...any) error
}

QueryScanner represents a type that provides the ability to execute an SQL statement, where for each row:

1. result values are scanned into the variables in the scans slice
2. the provided function is then called

The function would typically capture the variables in the scans slice, allowing it to operator on the values. For instance, append the values to slices allocated by the caller, or perform reduction operations like sum/mean/min/etc.

NOTE: This method may end up being included in the Tx interface alongside Executor since all of the concrete transaction implementations provided by this package implement this method.

type ReadTxMaker

type ReadTxMaker interface {
	BeginReadTx(ctx context.Context) (OuterReadTx, error)
}

ReadTxMaker can make read-only transactions. This is necessarily an outermost transaction since nested transactions inherit their access mode from their parent. Many read-only transactions can be made at once.

type ResultSet

type ResultSet struct {
	Columns []string
	Rows    [][]any
	Status  CommandTag
}

ResultSet is the result of a query or execution. It contains the returned columns and the rows.

type SnapshotTxMaker

type SnapshotTxMaker interface {
	BeginSnapshotTx(ctx context.Context) (Tx, string, error)
}

SnapshotTxMaker is an interface that creates a transaction for taking a snapshot of the database. This uses serializable isolation level to ensure internal consistency.

type Statistics

type Statistics struct {
	RowCount int64

	ColumnStatistics []ColumnStatistics
}

Statistics contains statistics about a table or a Plan. A Statistics can be derived directly from the underlying table, or derived from the statistics of its children.

func (*Statistics) String

func (s *Statistics) String() string

type Subscriber

type Subscriber interface {
	// Subscribe subscribes to notifications passed using the special `notice()`
	// function. Only `notice()` calls made after the subscription, on this tx,
	// will be received. A done function is returned that should be called to
	// signal that no more statements that emit notices will be executed. The
	// channel will only be closed after all notices have been sent AND the done
	// is called, or if the database shuts down prematurely. In case of an
	// unexpected DB shutdown, an empty string is sent on the channel before it
	// is closed. It is the caller's responsibility to call done.
	Subscribe(ctx context.Context) (ch <-chan string, done func(context.Context) error, err error)
}

Subscriber is a transaction that can be subscribed to. When subscribed, the passed channel will receive notifications. Only one subscription is allowed per transaction.

type Tx

type Tx interface {
	Executor
	TxMaker // recursive interface

	// Rollback rolls back the transaction.
	Rollback(ctx context.Context) error
	// Commit commits the transaction.
	Commit(ctx context.Context) error
}

Tx represents a database transaction. It can be nested within other transactions, and create new nested transactions. An implementation of Tx may also be an AccessModer, but it is not required.

type TxMaker

type TxMaker interface {
	BeginTx(ctx context.Context) (Tx, error)
}

TxMaker is an interface that creates a new transaction. In the context of the recursive Tx interface, is creates a nested transaction.

type ValCount

type ValCount struct {
	Val   any
	Count int
}