sql

Documentation

Overview

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

Index

• Variables
• func Int64(val interface{}) (int64, bool)
• type AccessMode
• type AccessModer
• type CommandTag
• type DB
• type Executor
• type OuterTx
• type OuterTxMaker
• type ReadTxMaker
• type ResultSet
• type SnapshotTxMaker
• type Tx
• type TxMaker

Variables

var (
	ErrNoTransaction = errors.New("no transaction")
	ErrNoRows        = errors.New("no rows in result set")
)

Functions

func Int64

func Int64(val interface{}) (int64, 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 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 OuterTxMaker and/or a ReadTxMaker. Embed with those interfaces to compose the minimal interface required.

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 OuterTx

type OuterTx interface {
	Tx
	Precommit(ctx context.Context) ([]byte, error)
}

OuterTx is the outermost database transaction.

NOTE: An OuterTx may be used where only a Tx or DB is required since those interfaces are a subset of the OuterTx method set.

type OuterTxMaker

type OuterTxMaker interface {
	BeginOuterTx(ctx context.Context) (OuterTx, error)
}

OuterTxMaker 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 OuterTxMaker and TxMaker.

type ReadTxMaker

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

ReadTxMaker can make read-only transactions. 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 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.