sqldb

package module
v2.0.0-...-6b53079 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 11, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultSqliteMaxConns is the default number of maximum open
	// connections for SQLite. SQLite only supports a single writer, so a
	// low default reduces contention on the busy_timeout and limits
	// resource usage.
	DefaultSqliteMaxConns = 2

	// DefaultPostgresMaxConns is the number of permitted active and idle
	// connections. We want to limit this so it isn't unlimited. We use the
	// same value for the number of idle connections as, this can speed up
	// queries given a new connection doesn't need to be established each
	// time.
	DefaultPostgresMaxConns = 25
)
View Source 
const (
	// DefaultNumTxRetries is the default number of times we'll retry a
	// transaction if it fails with an error that permits transaction
	// repetition.
	DefaultNumTxRetries = 20

	// DefaultInitialRetryDelay is the default initial delay between
	// retries. This will be used to generate a random delay between -50%
	// and +50% of this value, so 20 to 60 milliseconds. The retry will be
	// doubled after each attempt until we reach DefaultMaxRetryDelay. We
	// start with a random value to avoid multiple goroutines that are
	// created at the same time to effectively retry at the same time.
	DefaultInitialRetryDelay = time.Millisecond * 40

	// DefaultMaxRetryDelay is the default maximum delay between retries.
	DefaultMaxRetryDelay = time.Second * 3
)
View Source 
const (
	// DefaultSqliteBusyTimeout is the default busy_timeout value used
	// when no BusyTimeout is configured.
	DefaultSqliteBusyTimeout = 5 * time.Second
)
View Source 
const (
	PostgresTag = "15"
)
View Source 
const Subsystem = "SQL2"

Subsystem defines the logging code for this subsystem.

Variables

View Source 
var (
	// TargetLatest is a MigrationTarget that migrates to the latest
	// version available.
	TargetLatest = func(mig *migrate.Migrate, _ int, _ uint) error {
		return mig.Up()
	}

	// TargetVersion is a MigrationTarget that migrates to the given
	// version.
	TargetVersion = func(version uint) MigrationTarget {
		return func(mig *migrate.Migrate, _ int, _ uint) error {
			return mig.Migrate(version)
		}
	}

	// ErrMigrationDowngrade is returned when a database downgrade is
	// detected.
	ErrMigrationDowngrade = errors.New("database downgrade detected")
)
View Source 
var (
	// DefaultPostgresFixtureLifetime is the default maximum time a Postgres
	// test fixture is being kept alive. After that time the docker
	// container will be terminated forcefully, even if the tests aren't
	// fully executed yet. So this time needs to be chosen correctly to be
	// longer than the longest expected individual test run time.
	DefaultPostgresFixtureLifetime = 10 * time.Minute
)
View Source 
var (
	// DefaultStoreTimeout is the default timeout used for any interaction
	// with the storage/database.
	DefaultStoreTimeout = time.Second * 10
)
View Source 
var (
	// ErrMigrationMismatch is returned when a migrated record does not
	// match the original record.
	ErrMigrationMismatch = fmt.Errorf("migrated record does not match " +
		"original record")
)
View Source 
var (
	// ErrTxRetriesExceeded is returned when a transaction is retried more
	// than the max allowed valued without a success.
	ErrTxRetriesExceeded = errors.New("db tx retries exceeded")
)
View Source 
var (
	// MaxValidSQLTime is the maximum valid time that can be rendered as a
	// time string and can be used for comparisons in SQL.
	MaxValidSQLTime = time.Date(9999, 12, 31, 23, 59, 59, 999999, time.UTC)
)
View Source 
var NoOpReset = func() {}

NoOpReset is a no-op function that can be used as a default reset function ExecTx calls.

Functions

func ApplyAllMigrations 

func ApplyAllMigrations(executor MigrationExecutor, sets []MigrationSet) error

ApplyAllMigrations applies both the SQLC and custom in-code migrations to the SQLite database.

func CompareRecords 

func CompareRecords(original, migrated any, identifier string) error

CompareRecords checks if the original and migrated objects are equal. If they are not, it returns an error with a unified diff of the two objects.

func DisableLog 

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func ExecuteBatchQuery 

func ExecuteBatchQuery[I any, T any, R any](ctx context.Context,
	cfg *QueryConfig, inputItems []I, convertFunc ConvertFunc[I, T],
	queryFunc BatchQueryFunc[T, R], callback ItemCallbackFunc[R]) error

ExecuteBatchQuery executes a query in batches over a slice of input items. It converts the input items to a query type using the provided convertFunc, executes the query in batches using the provided queryFunc, and applies the callback to each result. This is useful for queries using the "WHERE x IN []slice" pattern. It takes that slice, splits it into batches of size MaxBatchSize, and executes the query for each batch.

NOTE: it is the caller's responsibility to ensure that the expected return results are unique across all pages. Meaning that if the input items are split up, a result that is returned in one page should not be expected to be returned in another page.

func ExecuteCollectAndBatchWithSharedDataQuery 

func ExecuteCollectAndBatchWithSharedDataQuery[C any, T any, I any, D any](
	ctx context.Context, cfg *QueryConfig, initialCursor C,
	pageQueryFunc PagedQueryFunc[C, T],
	extractPageCursor CursorExtractFunc[T, C],
	collectFunc CollectFunc[T, I],
	batchDataFunc CollectAndBatchDataQueryFunc[I, D],
	processItem ItemWithBatchDataProcessFunc[T, D]) error

ExecuteCollectAndBatchWithSharedDataQuery implements a page-by-page processing pattern where each page is immediately processed with batch-loaded data before moving to the next page.

It: 1. Fetches a page of items using cursor-based pagination 2. Collects identifiers from that page and batch loads shared data 3. Processes each item in the page with the shared batch data 4. Moves to the next page and repeats

Parameters: - initialCursor: starting cursor for pagination - pageQueryFunc: fetches a page of items - extractPageCursor: extracts cursor from paginated item for next page - collectFunc: extracts identifier from paginated item - batchDataFunc: batch loads shared data from collected IDs for one page - processItem: processes each item with the shared batch data

func ExecutePaginatedQuery 

func ExecutePaginatedQuery[C any, T any](ctx context.Context, cfg *QueryConfig,
	initialCursor C, queryFunc PagedQueryFunc[C, T],
	extractCursor CursorExtractFunc[T, C],
	processItem ItemProcessFunc[T]) error

ExecutePaginatedQuery executes a cursor-based paginated query. It continues fetching pages until no more results are returned, processing each item with the provided callback.

Parameters: - initialCursor: the starting cursor value (e.g., 0, -1, "", etc.). - queryFunc: function that fetches a page given cursor and limit. - extractCursor: function that extracts cursor from an item for next page. - processItem: function that processes each individual item.

NOTE: it is the caller's responsibility to "undo" any processing done on items if the query fails on a later page.

func ExecuteSQLTransactionWithRetry 

func ExecuteSQLTransactionWithRetry(ctx context.Context, makeTx MakeTx,
	rollbackTx RollbackTx, txBody TxBody, onBackoff OnBackoff,
	opts *txExecutorOptions) error

ExecuteSQLTransactionWithRetry is a helper function that executes a transaction with retry logic. It will retry the transaction if it fails with a serialization error. The function will return an error if the transaction fails with a non-retryable error, the context is cancelled or the number of retries is exceeded.

func ExtractBool 

func ExtractBool(b sql.NullBool) bool

ExtractBool turns a NullBool into a boolean. This can be useful when reading directly from the database, as this function handles extracting the inner value from the "option"-like struct.

func ExtractOptSqlInt32 

func ExtractOptSqlInt32[T constraints.Integer](num sql.NullInt32) fn.Option[T]

ExtractOptSqlInt32 turns a NullInt32 into an option of a numerical type.

func ExtractSqlInt16 

func ExtractSqlInt16[T constraints.Integer](num sql.NullInt16) T

ExtractSqlInt16 turns a NullInt16 into a numerical type. This can be useful when reading directly from the database, as this function handles extracting the inner value from the "option"-like struct.

func ExtractSqlInt32 

func ExtractSqlInt32[T constraints.Integer](num sql.NullInt32) T

ExtractSqlInt32 turns a NullInt32 into a numerical type. This can be useful when reading directly from the database, as this function handles extracting the inner value from the "option"-like struct.

func ExtractSqlInt32Ptr 

func ExtractSqlInt32Ptr[T constraints.Integer](num sql.NullInt32) *T

ExtractSqlInt32Ptr turns a NullInt32 into a pointer to a numerical type.

func ExtractSqlInt64 

func ExtractSqlInt64[T constraints.Integer](num sql.NullInt64) T

ExtractSqlInt64 turns a NullInt64 into a numerical type. This can be useful when reading directly from the database, as this function handles extracting the inner value from the "option"-like struct.

func ExtractSqlInt64Ptr 

func ExtractSqlInt64Ptr[T constraints.Integer](num sql.NullInt64) *T

ExtractSqlInt64Ptr turns a NullInt64 into a pointer to a numerical type.

func IsDeadlockError 

func IsDeadlockError(err error) bool

IsDeadlockError returns true if the given error is a deadlock error.

func IsSchemaError 

func IsSchemaError(err error) bool

IsSchemaError returns true if the given error is a schema error.

func IsSerializationError 

func IsSerializationError(err error) bool

IsSerializationError returns true if the given error is a serialization error.

func IsSerializationOrDeadlockError 

func IsSerializationOrDeadlockError(err error) bool

IsSerializationOrDeadlockError returns true if the given error is either a deadlock error or a serialization error.

func MapSQLError 

func MapSQLError(err error) error

MapSQLError attempts to interpret a given error as a database agnostic SQL error.

func RandomDBName 

func RandomDBName(t testing.TB) string

RandomDBName generates a random database name.

func SQLInt16 

func SQLInt16[T constraints.Integer](num T) sql.NullInt16

SQLInt16 turns a numerical integer type into the NullInt16 that sql/sqlc uses when an integer field can be permitted to be NULL.

We use this constraints.Integer constraint here which maps to all signed and unsigned integer types.

func SQLInt32 

func SQLInt32[T constraints.Integer](num T) sql.NullInt32

SQLInt32 turns a numerical integer type into the NullInt32 that sql/sqlc uses when an integer field can be permitted to be NULL.

We use this constraints.Integer constraint here which maps to all signed and unsigned integer types.

func SQLInt64 

func SQLInt64[T constraints.Integer](num T) sql.NullInt64

SQLInt64 turns a numerical integer type into the NullInt64 that sql/sqlc uses when an integer field can be permitted to be NULL.

We use this constraints.Integer constraint here which maps to all signed and unsigned integer types.

func SQLPtrInt32 

func SQLPtrInt32[T constraints.Integer](num *T) sql.NullInt32

SQLPtrInt32 turns a pointer to a numerical integer type into the NullInt32 that sql/sqlc uses.

func SQLPtrInt64 

func SQLPtrInt64[T constraints.Integer](num *T) sql.NullInt64

SQLPtrInt64 turns a pointer to a numerical integer type into the NullInt64 that sql/sqlc uses.

func SQLStr 

func SQLStr(s string) sql.NullString

SQLStr turns a string into the NullString that sql/sqlc uses when a string can be permitted to be NULL.

NOTE: If the input string is empty, it returns a NullString with Valid set to false. If this is not the desired behavior, consider using SQLStrValid instead.

func SQLStrValid 

func SQLStrValid(s string) sql.NullString

SQLStrValid turns a string into the NullString that sql/sqlc uses when a string can be permitted to be NULL.

NOTE: Valid is always set to true, even if the input string is empty.

func SQLTime 

func SQLTime(t time.Time) sql.NullTime

SQLTime turns a time.Time into the NullTime that sql/sqlc uses when a time can be permitted to be NULL.

func SqlBool 

func SqlBool(b bool) sql.NullBool

SqlBool turns a boolean into the NullBool that sql/sqlc uses when a boolean field can be permitted to be NULL.

func SqlOptInt32 

func SqlOptInt32[T constraints.Integer](num fn.Option[T]) sql.NullInt32

SqlOptInt32 turns an option of a numerical integer type into the NullInt32 that sql/sqlc uses when an integer field can be permitted to be NULL.

func UseLogger 

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type BackendType 

type BackendType uint8

BackendType is an enum that represents the type of database backend we're using. 

const (
	// BackendTypeUnknown indicates we're using an unknown backend.
	BackendTypeUnknown BackendType = iota

	// BackendTypeSqlite indicates we're using a SQLite backend.
	BackendTypeSqlite

	// BackendTypePostgres indicates we're using a Postgres backend.
	BackendTypePostgres
)

type BaseDB 

type BaseDB struct {
	*sql.DB

	// BackendType defines the type of database backend the database is.
	BackendType BackendType

	// SkipMigrations can be set to true to skip running any migrations
	// during the iinitialization of the database.
	SkipMigrations bool
}

BaseDB is the base database struct that each implementation can embed to gain some common functionality.

func (*BaseDB) Backend 

func (s *BaseDB) Backend() BackendType

Backend returns the type of the database backend used.

func (*BaseDB) BeginTx 

func (s *BaseDB) BeginTx(ctx context.Context, opts TxOptions) (*sql.Tx, error)

BeginTx wraps the normal sql specific BeginTx method with the TxOptions interface. This interface is then mapped to the concrete sql tx options struct.

type BatchQueryFunc 

type BatchQueryFunc[T any, R any] func(context.Context, []T) ([]R, error)

BatchQueryFunc represents a function that takes a batch of converted items and returns results.

type BatchedQuerier 

type BatchedQuerier interface {
	// BeginTx creates a new database transaction given the set of
	// transaction options.
	BeginTx(ctx context.Context, options TxOptions) (*sql.Tx, error)

	// Backend returns the type of the database backend used.
	Backend() BackendType
}

BatchedQuerier is a generic interface that allows callers to create a new database transaction based on an abstract type that implements the TxOptions interface.

type BatchedTx 

type BatchedTx[Q any] interface {
	// ExecTx will execute the passed txBody, operating upon generic
	// parameter Q (usually a storage interface) in a single transaction.
	//
	// The set of TxOptions are passed in order to allow the caller to
	// specify if a transaction should be read-only and optionally what
	// type of concurrency control should be used.
	ExecTx(ctx context.Context, txOptions TxOptions,
		txBody func(Q) error, reset func()) error

	// Backend returns the type of the database backend used.
	Backend() BackendType
}

BatchedTx is a generic interface that represents the ability to execute several operations to a given storage interface in a single atomic transaction. Typically, Q here will be some subset of the main sqlc.Querier interface allowing it to only depend on the routines it needs to implement any additional business logic.

type CollectAndBatchDataQueryFunc 

type CollectAndBatchDataQueryFunc[ID any, BatchData any] func(context.Context,
	[]ID) (BatchData, error)

CollectAndBatchDataQueryFunc represents a function that batch loads additional data for collected identifiers, returning the batch data that applies to all items.

type CollectFunc 

type CollectFunc[T any, ID any] func(T) (ID, error)

CollectFunc represents a function that extracts an identifier from a paginated item.

type ConvertFunc 

type ConvertFunc[I any, T any] func(I) T

ConvertFunc represents a function that converts from input type to query type for the batch query.

type CursorExtractFunc 

type CursorExtractFunc[T any, C any] func(T) C

CursorExtractFunc represents a function that extracts the cursor value from an item. This cursor will be used for the next page fetch.

type DB 

type DB interface {
	MigrationExecutor

	// GetBaseDB returns the underlying BaseDB instance.
	GetBaseDB() *BaseDB
}

DB is an interface that represents a generic SQL database. It provides methods to apply migrations and access the underlying database connection.

type ErrDeadlockError 

type ErrDeadlockError struct {
	DbError error
}

ErrDeadlockError is an error type which represents a database agnostic error where transactions have led to cyclic dependencies in lock acquisition.

func (ErrDeadlockError) Error 

func (e ErrDeadlockError) Error() string

Error returns the error message.

func (ErrDeadlockError) Unwrap 

func (e ErrDeadlockError) Unwrap() error

Unwrap returns the wrapped error.

type ErrSQLUniqueConstraintViolation 

type ErrSQLUniqueConstraintViolation struct {
	DBError error
}

ErrSQLUniqueConstraintViolation is an error type which represents a database agnostic SQL unique constraint violation.

func (ErrSQLUniqueConstraintViolation) Error 

func (e ErrSQLUniqueConstraintViolation) Error() string

type ErrSchemaError 

type ErrSchemaError struct {
	DbError error
}

ErrSchemaError is an error type which represents a database agnostic error that the schema of the database is incorrect for the given query.

func (ErrSchemaError) Error 

func (e ErrSchemaError) Error() string

Error returns the error message.

func (ErrSchemaError) Unwrap 

func (e ErrSchemaError) Unwrap() error

Unwrap returns the wrapped error.

type ErrSerializationError 

type ErrSerializationError struct {
	DBError error
}

ErrSerializationError is an error type which represents a database agnostic error that a transaction couldn't be serialized with other concurrent db transactions.

func (ErrSerializationError) Error 

func (e ErrSerializationError) Error() string

Error returns the error message.

func (ErrSerializationError) Unwrap 

func (e ErrSerializationError) Unwrap() error

Unwrap returns the wrapped error.

type ItemCallbackFunc 

type ItemCallbackFunc[R any] func(context.Context, R) error

ItemCallbackFunc represents a function that processes individual results.

type ItemProcessFunc 

type ItemProcessFunc[T any] func(context.Context, T) error

ItemProcessFunc represents a function that processes individual items.

type ItemWithBatchDataProcessFunc 

type ItemWithBatchDataProcessFunc[T any, BatchData any] func(context.Context,
	T, BatchData) error

ItemWithBatchDataProcessFunc represents a function that processes individual items along with shared batch data.

type MakeTx 

type MakeTx func() (Tx, error)

MakeTx is a function that creates a new transaction. It returns a Tx and an error if the transaction cannot be created. This is used to abstract the creation of a transaction from the actual transaction logic in order to be able to reuse the transaction retry logic in other packages.

type MigrateOpt 

type MigrateOpt func(*migrateOptions)

MigrateOpt is a functional option that can be passed to migrate related methods to modify behavior.

func WithLatestVersion 

func WithLatestVersion(version uint) MigrateOpt

WithLatestVersion allows callers to override the default latest version setting.

func WithProgrammaticMigrations 

func WithProgrammaticMigrations(
	programmaticMigrs map[uint]migrate.ProgrammaticMigrEntry) MigrateOpt

WithProgrammaticMigrations is an option that can be used to set a map of ProgrammaticMigrEntry functions that can be used to execute a Golang based migration step. The key is the migration version and the value is the Golang migration function entry that should be run for the migration version.

type MigrationDescriptor 

type MigrationDescriptor struct {
	// Name is the name of the migration.
	Name string

	// Version represents the "global" database version for this migration.
	// Unlike the schema version tracked by golang-migrate, it encompasses
	// all migrations, including those managed by golang-migrate as well
	// as custom in-code migrations.
	Version int

	// SchemaVersion represents the schema version tracked by golang-migrate
	// at which the migration is applied.
	SchemaVersion int
}

MigrationDescriptor is a description struct that describes SQL migrations. Each migration is associated with a specific schema version and a global database version. Migrations are applied in the order of their global database version. If a migration includes a non-nil MigrationFn, it is executed after the SQL schema has been migrated to the corresponding schema version.

type MigrationExecutor 

type MigrationExecutor interface {
	// ExecuteMigrations runs database migrations for the given migration
	// set using the executor's default production migration target. A
	// migration may include a schema change, a custom migration function,
	// or both.
	ExecuteMigrations(set MigrationSet) error
}

MigrationExecutor is an interface that abstracts the migration functionality.

type MigrationSet 

type MigrationSet struct {
	// TrackingTableName is the name of the table used by golang-migrate to
	// track the current schema version.
	TrackingTableName string

	// SQLFiles is the embedded file system containing the SQL migration
	// files.
	SQLFiles embed.FS

	// SQLFileDirectory is the directory containing the SQL migration files.
	SQLFileDirectory string

	// MakeProgrammaticMigrations is a function that returns a map of
	// ProgrammaticMigrEntry functions that can be used to execute a Golang
	// based migration step. The key is the migration version and the value
	// is the Golang migration function entry that should be run for the
	// migration version. Note that a database version can be either an SQL
	// migration or a programmatic migration, but not both at the same time.
	MakeProgrammaticMigrations func(
		*BaseDB) (map[uint]migrate.ProgrammaticMigrEntry, error)

	// LatestMigrationVersion is the latest migration version of the
	// database. This is used to implement downgrade protection for the
	// daemon.
	LatestMigrationVersion uint

	// Descriptors defines a list of migrations to be applied to the
	// database. Each migration is assigned a version number that documents
	// and validates the expected execution order.
	// The schema version, tracked by golang-migrate, ensures migrations are
	// applied to the correct schema. For migrations involving only schema
	// changes, the migration function can be left nil. For custom
	// migrations an implemented migration function is required.
	Descriptors []MigrationDescriptor
}

MigrationSet encapsulates all necessary information to manage and apply a series of SQL migrations, and corresponding code migrations, to a database.

type MigrationTarget 

type MigrationTarget func(mig *migrate.Migrate,
	currentDbVersion int, maxMigrationVersion uint) error

MigrationTarget is a functional option that can be passed to applyMigrations to specify a target version to migrate to. `currentDbVersion` is the current (migration) version of the database, or None if unknown. `maxMigrationVersion` is the maximum migration version known to the driver, or None if unknown.

type OnBackoff 

type OnBackoff func(retry int, delay time.Duration)

OnBackoff is a function that is called when a transaction is retried due to a serialization error. The function is called with the retry attempt number and the delay before the next retry.

type PagedQueryFunc 

type PagedQueryFunc[C any, T any] func(context.Context, C, int32) ([]T, error)

PagedQueryFunc represents a function that fetches a page of results using a cursor. It returns the fetched items and should return an empty slice when no more results.

type PostgresConfig 

type PostgresConfig struct {
	Dsn                string        `long:"dsn" description:"Database connection string."`
	Timeout            time.Duration `long:"timeout" description:"Database connection timeout. Set to zero to disable."`
	MaxOpenConnections int           `long:"maxconnections" description:"Max open connections to keep alive to the database server."`
	MaxIdleConnections int           `long:"maxidleconnections" description:"Max number of idle connections to keep in the connection pool."`
	ConnMaxLifetime    time.Duration `` /* 139-byte string literal not displayed */
	ConnMaxIdleTime    time.Duration `` /* 137-byte string literal not displayed */
	RequireSSL         bool          `long:"requiressl" description:"Whether to require using SSL (mode: require) when connecting to the server."`
	SkipMigrations     bool          `long:"skipmigrations" description:"Skip applying migrations on startup."`
	QueryConfig        `group:"query" namespace:"query"`
}

PostgresConfig holds the postgres database configuration.

func (*PostgresConfig) Validate 

func (p *PostgresConfig) Validate() error

Validate checks that the PostgresConfig values are valid.

type PostgresStore 

type PostgresStore struct {
	*BaseDB
	// contains filtered or unexported fields
}

PostgresStore is a database store implementation that uses a Postgres backend.

func NewPostgresStore 

func NewPostgresStore(cfg *PostgresConfig) (*PostgresStore, error)

NewPostgresStore creates a new store that is backed by a Postgres database backend.

func NewTestPostgresDB 

func NewTestPostgresDB(t testing.TB, fixture *TestPgFixture,
	sets []MigrationSet) *PostgresStore

NewTestPostgresDB is a helper function that creates a Postgres database for testing using the given fixture.

func NewTestPostgresDBWithVersion 

func NewTestPostgresDBWithVersion(t testing.TB, fixture *TestPgFixture,
	sets MigrationSet, version uint) *PostgresStore

NewTestPostgresDBWithVersion is a helper function that creates a Postgres database for testing and migrates it to the given version.

func (*PostgresStore) ExecuteMigrations 

func (s *PostgresStore) ExecuteMigrations(set MigrationSet) error

ExecuteMigrations runs migrations for the Postgres database using the default production migration target.

func (*PostgresStore) GetBaseDB 

func (s *PostgresStore) GetBaseDB() *BaseDB

GetBaseDB returns the underlying BaseDB instance for the Postgres store. It is a trivial helper method to comply with the sqldb.DB interface.

func (*PostgresStore) GetSchemaVersion 

func (s *PostgresStore) GetSchemaVersion() (int, bool, error)

GetSchemaVersion returns the current schema version of the Postgres database.

func (*PostgresStore) SetSchemaVersion 

func (s *PostgresStore) SetSchemaVersion(version int, dirty bool) error

SetSchemaVersion sets the schema version of the Postgres database.

NOTE: This alters the internal database schema tracker. USE WITH CAUTION!!!

type QueryConfig 

type QueryConfig struct {
	// MaxBatchSize is the maximum number of items included in a batch
	// query IN clauses list.
	MaxBatchSize uint32 `` /* 178-byte string literal not displayed */

	// MaxPageSize is the maximum number of items returned in a single page
	// of results. This is used for paginated queries.
	MaxPageSize uint32 `` /* 137-byte string literal not displayed */
}

QueryConfig holds configuration values for SQL queries.

func DefaultPostgresConfig 

func DefaultPostgresConfig() *QueryConfig

DefaultPostgresConfig returns a default configuration for SQL queries to a Postgres backend.

func DefaultSQLiteConfig 

func DefaultSQLiteConfig() *QueryConfig

DefaultSQLiteConfig returns a default configuration for SQL queries to a SQLite backend.

func (*QueryConfig) Validate 

func (c *QueryConfig) Validate(sqlite bool) error

Validate checks that the QueryConfig values are valid.

type QueryCreator 

type QueryCreator[Q any] func(*sql.Tx) Q

QueryCreator is a generic function that's used to create a Querier, which is a type of interface that implements storage related methods from a database transaction. This will be used to instantiate an object callers can use to apply multiple modifications to an object interface in a single atomic transaction.

type RollbackTx 

type RollbackTx func(tx Tx) error

RollbackTx is a function that is called when a transaction needs to be rolled back due to a serialization error. By using this intermediate function, we can avoid having to return rollback errors that are not actionable by the caller.

type SqliteConfig 

type SqliteConfig struct {
	Timeout            time.Duration `long:"timeout" description:"The time after which a database query should be timed out."`
	BusyTimeout        time.Duration `` /* 126-byte string literal not displayed */
	MaxConnections     int           `long:"maxconnections" description:"The maximum number of open connections to the database."`
	MaxIdleConnections int           `long:"maxidleconnections" description:"Max number of idle connections to keep in the connection pool."`
	ConnMaxLifetime    time.Duration `` /* 139-byte string literal not displayed */
	PragmaOptions      []string      `` /* 219-byte string literal not displayed */
	SkipMigrations     bool          `long:"skipmigrations" description:"Skip applying migrations on startup."`

	// SkipMigrationDbBackup if true, then a backup of the database will not
	// be created before applying migrations.
	SkipMigrationDbBackup bool `long:"skipmigrationdbbackup" description:"Skip creating a backup of the database before applying migrations."`

	QueryConfig `group:"query" namespace:"query"`
}

SqliteConfig holds all the config arguments needed to interact with our sqlite DB.

func (*SqliteConfig) MaxConns 

func (s *SqliteConfig) MaxConns() int

MaxConns returns the effective maximum number of SQLite connections.

func (*SqliteConfig) MaxIdleConns 

func (s *SqliteConfig) MaxIdleConns() int

MaxIdleConns returns the effective maximum number of idle SQLite connections.

func (*SqliteConfig) Validate 

func (p *SqliteConfig) Validate() error

Validate checks that the SqliteConfig values are valid.

type SqliteStore 

type SqliteStore struct {
	DbPath string

	Config *SqliteConfig

	*BaseDB
}

SqliteStore is a database store implementation that uses a sqlite backend.

func NewSqliteStore 

func NewSqliteStore(cfg *SqliteConfig, dbPath string) (*SqliteStore, error)

NewSqliteStore attempts to open a new sqlite database based on the passed config.

func NewTestDB 

func NewTestDB(t *testing.T, sets []MigrationSet) *SqliteStore

NewTestDB is a helper function that creates an SQLite database for testing.

func NewTestDBWithVersion 

func NewTestDBWithVersion(t *testing.T, set MigrationSet,
	version uint) *SqliteStore

NewTestDBWithVersion is a helper function that creates an SQLite database for testing and migrates it to the given version.

func NewTestSqliteDB 

func NewTestSqliteDB(t testing.TB, sets []MigrationSet) *SqliteStore

NewTestSqliteDB is a helper function that creates an SQLite database for testing.

func NewTestSqliteDBFromPath 

func NewTestSqliteDBFromPath(t *testing.T, dbPath string,
	sets []MigrationSet) *SqliteStore

NewTestSqliteDBFromPath is a helper function that creates a SQLite database for testing from a given database file path.

func NewTestSqliteDBWithVersion 

func NewTestSqliteDBWithVersion(t *testing.T, set MigrationSet,
	version uint) *SqliteStore

NewTestSqliteDBWithVersion is a helper function that creates an SQLite database for testing and migrates it to the given version.

func (*SqliteStore) ExecuteMigrations 

func (s *SqliteStore) ExecuteMigrations(set MigrationSet) error

ExecuteMigrations runs migrations for the sqlite database using the default production migration target.

func (*SqliteStore) GetBaseDB 

func (s *SqliteStore) GetBaseDB() *BaseDB

GetBaseDB returns the underlying BaseDB instance for the SQLite store. It is a trivial helper method to comply with the sqldb.DB interface.

func (*SqliteStore) GetSchemaVersion 

func (s *SqliteStore) GetSchemaVersion() (int, bool, error)

GetSchemaVersion returns the current schema version of the SQLite database.

func (*SqliteStore) SetSchemaVersion 

func (s *SqliteStore) SetSchemaVersion(version int, dirty bool) error

SetSchemaVersion sets the schema version of the SQLite database.

NOTE: This alters the internal database schema tracker. USE WITH CAUTION!!!

type TestPgFixture 

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

TestPgFixture is a test fixture that starts a Postgres 11 instance in a docker container.

func NewTestPgFixture 

func NewTestPgFixture(t testing.TB, expiry time.Duration) *TestPgFixture

NewTestPgFixture constructs a new TestPgFixture starting up a docker container running Postgres 15. The started container will expire in after the passed duration.

func (*TestPgFixture) DB 

func (f *TestPgFixture) DB() *sql.DB

func (*TestPgFixture) GetConfig 

func (f *TestPgFixture) GetConfig(dbName string) *PostgresConfig

GetConfig returns the full config of the Postgres node.

func (*TestPgFixture) TearDown 

func (f *TestPgFixture) TearDown(t testing.TB)

TearDown stops the underlying docker container.

type TransactionExecutor 

type TransactionExecutor[Query any] struct {
	BatchedQuerier
	// contains filtered or unexported fields
}

TransactionExecutor is a generic struct that abstracts away from the type of query a type needs to run under a database transaction, and also the set of options for that transaction. The QueryCreator is used to create a query given a database transaction created by the BatchedQuerier.

func NewTransactionExecutor 

func NewTransactionExecutor[Querier any](db BatchedQuerier,
	createQuery QueryCreator[Querier],
	opts ...TxExecutorOption) *TransactionExecutor[Querier]

NewTransactionExecutor creates a new instance of a TransactionExecutor given a Querier query object and a concrete type for the type of transactions the Querier understands.

func (*TransactionExecutor[Q]) Backend 

func (t *TransactionExecutor[Q]) Backend() BackendType

Backend returns the type of database backend used by the executor.

func (*TransactionExecutor[Q]) ExecTx 

func (t *TransactionExecutor[Q]) ExecTx(ctx context.Context,
	txOptions TxOptions, txBody func(Q) error, reset func()) error

ExecTx is a wrapper for txBody to abstract the creation and commit of a db transaction. The db transaction is embedded in a `*Queries` that txBody needs to use when executing each one of the queries that need to be applied atomically. This can be used by other storage interfaces to parameterize the type of query and options run, in order to have access to batched operations related to a storage object.

type Tx 

type Tx interface {
	// Commit commits the database transaction, an error should be returned
	// if the commit isn't possible.
	Commit() error

	// Rollback rolls back an incomplete database transaction.
	// Transactions that were able to be committed can still call this as a
	// noop.
	Rollback() error
}

Tx represents a database transaction that can be committed or rolled back.

type TxBody 

type TxBody func(tx Tx) error

TxBody represents the function type for transactions. It returns an error to indicate success or failure.

type TxExecutorOption 

type TxExecutorOption func(*txExecutorOptions)

TxExecutorOption is a functional option that allows us to pass in optional argument when creating the executor.

func WithTxRetries 

func WithTxRetries(numRetries int) TxExecutorOption

WithTxRetries is a functional option that allows us to specify the number of times a transaction should be retried if it fails with a repeatable error.

func WithTxRetryDelay 

func WithTxRetryDelay(delay time.Duration) TxExecutorOption

WithTxRetryDelay is a functional option that allows us to specify the delay to wait before a transaction is retried.

type TxOptions 

type TxOptions interface {
	// ReadOnly returns true if the transaction should be read only.
	ReadOnly() bool
}

TxOptions represents a set of options one can use to control what type of database transaction is created. Transaction can be either read or write.

func ReadTxOpt 

func ReadTxOpt() TxOptions

ReadTxOpt returns a TxOptions that indicates that the transaction should be a read-only transaction.

func WriteTxOpt 

func WriteTxOpt() TxOptions

WriteTxOpt returns a TxOptions that indicates that the transaction should be a write transaction.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.