db

type Client ¶

type Client interface {
	WithTransaction(ctx context.Context, forWriting bool, f WithTransactionFunction) error
	Prepare(stmt string) (Stmt, error)
	QueryForRows(ctx context.Context, stmt Stmt, params ...any) (Rows, error)
	ReadObjects(rows Rows, typ reflect.Type) ([]any, error)
	ReadStrings(rows Rows) ([]string, error)
	ReadStringsN(rows Rows, numColumns int) ([][]string, error)
	ReadInt(rows Rows) (int, error)
	ReadStringIntString1or2(rows Rows, readThirdString bool) ([][]string, error)
	Upsert(tx TxClient, stmt Stmt, key string, obj SerializedObject) error
	NewConnection(isTemp bool) (string, error)
	Serialize(obj any, encrypt bool) (SerializedObject, error)
	Deserialize(SerializedObject, any) error
}

Client defines a database client that provides encrypting, decrypting, and database resetting

func NewClient(ctx context.Context, c Connection, encryptor Encryptor, decryptor Decryptor, useTempDir bool, opts ...ClientOption) (Client, string, error)

type ClientOption ¶ added in v0.7.20

type ClientOption func(*client)

func WithEncoding(encType Encoding) ClientOption

type Connection ¶

type Connection interface {
	BeginTx(ctx context.Context, opts *sql.TxOptions) (Tx, error)
	Exec(query string, args ...any) (sql.Result, error)
	Prepare(query string) (*sql.Stmt, error)
	Close() error
}

Connection represents a connection pool.

type Decryptor ¶

type Decryptor interface {
	// Decrypt accepts a chunk of encrypted data, the nonce used to encrypt it and the ID of the used key (as it rotates). It returns the decrypted data or an error.
	Decrypt([]byte, []byte, uint32) ([]byte, error)
}

Decryptor decrypts data previously encrypted by Encryptor.

type Encoding ¶ added in v0.7.20

type Encoding int

const (
	GobEncoding Encoding = iota
	JSONEncoding
	MsgpackEncoding
	GzippedGobEncoding
	GzippedJSONEncoding
)

type Encryptor ¶

type Encryptor interface {
	// Encrypt encrypts the specified data, returning: the encrypted data, the nonce used to encrypt the data, and an ID identifying the key that was used (as it rotates). On failure error is returned instead.
	Encrypt([]byte) ([]byte, []byte, uint32, error)
}

Encryptor encrypts data with a key which is rotated to avoid wear-out.

type QueryError ¶

type QueryError struct {
	QueryString string
	Err         error
}

QueryError encapsulates an error while executing a query

func (e *QueryError) Error() string

func (e *QueryError) Unwrap() error

type Row ¶ added in v0.7.18

type Row interface {
	Err() error
	Scan(dest ...any) error
}

Row implements a subset of the methods provided by sql.Row

type Rows ¶

type Rows interface {
	Next() bool
	Scan(dest ...any) error
	// Close releases any resources held by the rows and returns the first
	// error encountered during iteration. If iteration succeeded, returns
	// any error from closing. Close must be called exactly once after the
	// caller is done iterating.
	Close() error
}

Rows represents sql rows. It exposes methods to navigate the rows, read their outputs, and close them.

Note: Err is intentionally not part of this interface. Iteration errors must be retrieved via Close, which closes the rows and returns the first iteration error (or any close error). Combining them eliminates a footgun with sql.RawBytes targets in Scan: the database/sql Rows.closemu RLock kept open across Scan(*RawBytes) returns is released by Close but not by Err, so calling Err before Close can deadlock against a concurrent Rows.awaitDone writer queued behind the scan-held RLock. See Go issue 60304 and rancher/steve#1206 for the full story.

type SerializedObject ¶ added in v0.7.20

type SerializedObject struct {
	Bytes sql.RawBytes
	// only set if encrypted
	Nonce sql.RawBytes
	KeyID uint32
}

type Stmt ¶ added in v0.7.18

type Stmt interface {
	Exec(args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, args ...any) (Rows, error)
	Close() error

	// SQLStmt unwraps the original sql.Stmt
	SQLStmt() *sql.Stmt

	// GetQueryString returns the original text used to prepare this statement
	GetQueryString() string
}

Stmt is an interface over a subset of sql.Stmt methods rationale: allow mocking

type Tx ¶ added in v0.8.6

type Tx interface {
	Exec(query string, args ...any) (sql.Result, error)
	Stmt(stmt *sql.Stmt) *sql.Stmt
	Commit() error
	Rollback() error
}

Tx represents the methods used from sql.Tx

type TxClient ¶ added in v0.7.18

type TxClient interface {
	Exec(query string, args ...any) (sql.Result, error)
	Stmt(stmt Stmt) Stmt
}

TxClient is an interface over a subset of sql.Tx methods rationale 1: explicitly forbid direct access to Commit and Rollback functionality as that is exclusively dealt with by WithTransaction in ../db rationale 2: allow mocking

func NewTxClient(tx Tx, opts ...TxClientOption) TxClient

type TxClientOption ¶ added in v0.7.19

type TxClientOption func(*txClient)

func WithQueryLogger(logger logging.QueryLogger) TxClientOption

type WithTransactionFunction ¶ added in v0.5.7

type WithTransactionFunction func(tx TxClient) error

WithTransactionFunction is a function that uses a transaction