db

package
v0.0.0-...-3c4d601 Latest Latest
Warning

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

 Go to latest Published: Feb 21, 2025 License: AGPL-3.0 Imports: 12 Imported by: 1

Documentation

Overview

Package db defines database utility functions.

These functions currently work on a sqlite database. Other databases may not work with functions in this package.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNoOpMigration = errors.New("migration no-op")

ErrNoOpMigration is returned when there was no work for the migration to perform.

View Source 
var ErrUnableToRead = errors.New("unable to read database")

ErrUnableToRead is returned when the accessor cannot be read.

Functions

func GetUserVersion 

func GetUserVersion(ctx context.Context, q Queryable) (userVersion int32, err error)

GetUserVersion returns the user version field stored in the sqlite database if the database was never initiliazed with a version, it would return 0 as the version.

func Initialize 

func Initialize(accessor Accessor, migrations []Migration) error

Initialize creates or upgrades a DB accessor in a new atomic context. The Migration slice is ordered and must contain all prior migrations in order to determine which need to be called.

func InitializeWithContext 

func InitializeWithContext(ctx context.Context, tx *sql.Tx, migrations []Migration) error

InitializeWithContext creates or upgrades a DB accessor.

func IsErrBusy 

func IsErrBusy(inerr error) bool

IsErrBusy examine the input inerr variable of type error and determine if it's a sqlite3 error for the ErrBusy error code.

func LoggedRetry 

func LoggedRetry(fn func() error, log logging.Logger) (err error)

LoggedRetry executes a function repeatedly as long as it returns an error that indicates database contention that warrants a retry. Sends warnings and errors to log.

func ResetTransactionWarnDeadline 

func ResetTransactionWarnDeadline(ctx context.Context, tx interface{}, deadline time.Time) (prevDeadline time.Time, err error)

ResetTransactionWarnDeadline allow the atomic function to extend its warn deadline by setting a new deadline. The Accessor can be copied and therefore isn't suitable for multi-threading directly, however, the transaction context and transaction object can be used to uniquely associate the request with a particular deadline. the function fails if the given transaction is not on the stack of the provided context.

func Retry 

func Retry(fn func() error) (err error)

Retry executes a function repeatedly as long as it returns an error that indicates database contention that warrants a retry. Sends warnings and errors to logging.Base()

func SetUserVersion 

func SetUserVersion(ctx context.Context, e Executable, userVersion int32) (previousUserVersion int32, err error)

SetUserVersion sets the userVersion as the new user version, and return the old version.

func URI 

func URI(filename string, readOnly bool, memory bool) string

URI returns the sqlite URI given a db filename as an input.

Types

type Accessor 

type Accessor struct {
	Handle *sql.DB
	// contains filtered or unexported fields
}

An Accessor manages a sqlite database handle and any outstanding batching operations.

func MakeAccessor 

func MakeAccessor(dbfilename string, readOnly bool, inMemory bool) (Accessor, error)

MakeAccessor creates a new Accessor.

func MakeErasableAccessor 

func MakeErasableAccessor(dbfilename string) (Accessor, error)

MakeErasableAccessor creates a new Accessor with the secure_delete pragma set; see https://www.sqlite.org/pragma.html#pragma_secure_delete It is not read-only and not in-memory (otherwise, erasability doesn't matter)

func (*Accessor) Atomic 

func (db *Accessor) Atomic(fn idemFn, extras ...interface{}) (err error)

Atomic executes a piece of code with respect to the database atomically. For transactions where readOnly is false, sync determines whether or not to wait for the result. The return error of fn should be a native sqlite3.Error type or an error wrapping it. DO NOT return a custom error - the internal logic of Atomic expects an sqlite error and uses that value.

func (*Accessor) AtomicContext 

func (db *Accessor) AtomicContext(ctx context.Context, fn idemFn, retryClearFn func(context.Context), extras ...interface{}) (err error)

AtomicContext executes a piece of code with respect to the database atomically. For transactions where readOnly is false, sync determines whether or not to wait for the result. Like for Atomic, the return error of fn should be a native sqlite3.Error type or an error wrapping it. If retryClearFn is provided, it will be called in between retries of calls to fn, if the error is a temporary error that will be retried. This helps a caller that might change in-memory state inside fn.

func (*Accessor) Close 

func (db *Accessor) Close()

Close closes the connection.

func (*Accessor) GetPageCount 

func (db *Accessor) GetPageCount(ctx context.Context) (pageCount uint64, err error)

GetPageCount returns the total number of pages in the database

func (*Accessor) GetPageSize 

func (db *Accessor) GetPageSize(ctx context.Context) (pageSize uint64, err error)

GetPageSize returns the number of bytes per database page

func (*Accessor) IsSharedCacheConnection 

func (db *Accessor) IsSharedCacheConnection() bool

IsSharedCacheConnection returns whether this connection was created using shared-cache connection or not. we use shared cache for in-memory databases

func (*Accessor) SetLogger 

func (db *Accessor) SetLogger(log logging.Logger)

SetLogger sets the Logger, mainly for unit test quietness

func (*Accessor) SetSynchronousMode 

func (db *Accessor) SetSynchronousMode(ctx context.Context, mode SynchronousMode, fullfsync bool) (err error)

SetSynchronousMode updates the synchronous mode of the connection

func (*Accessor) Vacuum 

func (db *Accessor) Vacuum(ctx context.Context) (stats VacuumStats, err error)

Vacuum perform a full-vacuum on the given database. In order for the vacuum to succeed, the storage needs to have double the amount of the current database size ( roughly ), and we cannot have any other transaction ( either read or write ) being active.

type ErrUnknownVersion 

type ErrUnknownVersion struct {
	CurrentVersion   int32
	SupportedVersion int32
}

ErrUnknownVersion is returned when a migration to the current version is not available.

func MakeErrUnknownVersion 

func MakeErrUnknownVersion(currentVersion, supportedVersion int32) *ErrUnknownVersion

MakeErrUnknownVersion makes an ErrUnknownVersion.

func (*ErrUnknownVersion) Error 

func (err *ErrUnknownVersion) Error() string

Error implements the error interface.

type ErrUpgradeFailure 

type ErrUpgradeFailure struct {
	SchemaVersionFrom int32
	SchemaVersionTo   int32
}

ErrUpgradeFailure is returned when a migration returns an error.

func MakeErrUpgradeFailure 

func MakeErrUpgradeFailure(from, to int32) *ErrUpgradeFailure

MakeErrUpgradeFailure makes an ErrUpgradeFailure.

func (*ErrUpgradeFailure) Error 

func (err *ErrUpgradeFailure) Error() string

Error implements the error interface.

type Executable 

type Executable interface {
	Queryable
	Exec(query string, args ...interface{}) (sql.Result, error)
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
}

Executable is similar but has write methods as well.

type Migration 

type Migration func(ctx context.Context, tx *sql.Tx, newDatabase bool) error

Migration is used to upgrade a database from one version to the next. The Migration slice is ordered and must contain all prior migrations in order to determine which need to be called.

type Pair 

type Pair struct {
	Rdb Accessor
	Wdb Accessor
}

Pair represents two accessors - read and write

func OpenErasablePair 

func OpenErasablePair(filename string) (p Pair, err error)

OpenErasablePair opens the filename with both reading and writing accessors with the secure_delete pragma set, using MakeErasableAccessor.

func OpenPair 

func OpenPair(filename string, memory bool) (p Pair, err error)

OpenPair opens the filename with both reading and writing accessors.

func (Pair) Close 

func (p Pair) Close()

Close the read and write accessors

type Queryable 

type Queryable interface {
	Prepare(query string) (*sql.Stmt, error)
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
	Query(query string, args ...interface{}) (*sql.Rows, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
	QueryRow(query string, args ...interface{}) *sql.Row
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
}

Queryable is meant to represent the union of a transaction (sql.Tx) and the underlying database (sql.DB), so that code issuing a single read-only query can be run directly on the sql.DB object without creating a short-lived transaction for a single SELECT query.

Queryable captures only a subset of Go's SQL API for issuing reads; if new code needs additional methods to query a SQL DB, they should be added here as needed.

type SynchronousMode 

type SynchronousMode int

SynchronousMode is the syncronious modes supported by sqlite database. 

const (
	// SynchronousModeOff (0), SQLite continues without syncing as soon as it has handed data off to the operating system. If the application running SQLite crashes,
	// the data will be safe, but the database might become corrupted if the operating system crashes or the computer loses power before that data has been written to the
	// disk surface. On the other hand, commits can be orders of magnitude faster with synchronous OFF.
	SynchronousModeOff SynchronousMode = 0
	// SynchronousModeNormal (1), the SQLite database engine will still sync at the most critical moments, but less often than in FULL mode. There is a very small
	// (though non-zero) chance that a power failure at just the wrong time could corrupt the database in journal_mode=DELETE on an older filesystem.
	// WAL mode is safe from corruption with synchronous=NORMAL, and probably DELETE mode is safe too on modern filesystems. WAL mode is always consistent with synchronous=NORMAL,
	// but WAL mode does lose durability. A transaction committed in WAL mode with synchronous=NORMAL might roll back following a power loss or system crash.
	// Transactions are durable across application crashes regardless of the synchronous setting or journal mode.
	// The synchronous=NORMAL setting is a good choice for most applications running in WAL mode.
	SynchronousModeNormal SynchronousMode = 1
	// SynchronousModeFull (2), the SQLite database engine will use the xSync method of the VFS to ensure that all content is safely written to the disk surface prior to continuing.
	// This ensures that an operating system crash or power failure will not corrupt the database. FULL synchronous is very safe, but it is also slower.
	// FULL is the most commonly used synchronous setting when not in WAL mode.
	SynchronousModeFull SynchronousMode = 2
	// SynchronousModeExtra synchronous is like FULL with the addition that the directory containing a rollback journal is synced after that journal is unlinked to commit a
	// transaction in DELETE mode. EXTRA provides additional durability if the commit is followed closely by a power loss.
	SynchronousModeExtra SynchronousMode = 3
)

type VacuumStats 

type VacuumStats struct {
	// PagesBefore is the number of pages in the database before the vacuum operation
	PagesBefore uint64
	// SizeBefore is the amount of data used by the database ( number of pages * size of a page) before the vacuum operation
	SizeBefore uint64
	// PagesAfter is the number of pages in the database after the vacuum operation
	PagesAfter uint64
	// SizeAfter is the amount of data used by the database ( number of pages * size of a page) after the vacuum operation
	SizeAfter uint64
}

VacuumStats returns the database statistics before and after a vacuum operation

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.