sql

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 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 Int64Valuer ¶

type Int64Valuer interface {
	Int64Value() (pgtype.Int8, error)
}

Int64Valuer is for internal use so a pgtype.Numeric can be recognized by our Int64 helper below.

type Int64er ¶

type Int64er interface {
	Int64() int64
}

type Int64errer ¶

type Int64errer interface {
	Int64() (int64, error)
}

Int64errer is for internal use so our Numeric type can be recognized by the Int64 function in addition to a pgtype.Numeric.

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 ReservedReadTxMaker ¶ added in v0.10.1

type ReservedReadTxMaker interface {
	BeginReservedReadTx(ctx context.Context) (Tx, error)
}

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