db

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

• Variables
• func GetUserVersion(ctx context.Context, tx *sql.Tx) (userVersion int32, err error)
• func Initialize(accessor Accessor, migrations []Migration) error
• func InitializeWithContext(ctx context.Context, tx *sql.Tx, migrations []Migration) error
• func IsErrBusy(inerr error) bool
• func LoggedRetry(fn func() error, log logging.Logger) (err error)
• func ResetTransactionWarnDeadline(ctx context.Context, tx *sql.Tx, deadline time.Time) (prevDeadline time.Time, err error)
• func Retry(fn func() error) (err error)
• func SetUserVersion(ctx context.Context, tx *sql.Tx, userVersion int32) (previousUserVersion int32, err error)
• func URI(filename string, readOnly bool, memory bool) string
• type Accessor
  • func MakeAccessor(dbfilename string, readOnly bool, inMemory bool) (Accessor, error)
  • func MakeErasableAccessor(dbfilename string) (Accessor, error)
  • func (db *Accessor) Atomic(fn idemFn, extras ...interface{}) (err error)
  • func (db *Accessor) Close()
  • func (db *Accessor) GetPageCount(ctx context.Context) (pageCount uint64, err error)
  • func (db *Accessor) GetPageSize(ctx context.Context) (pageSize uint64, err error)
  • func (db *Accessor) IsSharedCacheConnection() bool
  • func (db *Accessor) SetLogger(log logging.Logger)
  • func (db *Accessor) SetSynchronousMode(ctx context.Context, mode SynchronousMode, fullfsync bool) (err error)
  • func (db *Accessor) Vacuum(ctx context.Context) (stats VacuumStats, err error)
• type ErrUnknownVersion
  • func MakeErrUnknownVersion(currentVersion, supportedVersion int32) *ErrUnknownVersion
  • func (err *ErrUnknownVersion) Error() string
• type ErrUpgradeFailure
  • func MakeErrUpgradeFailure(from, to int32) *ErrUpgradeFailure
  • func (err *ErrUpgradeFailure) Error() string
• type Migration
• type Pair
  • func OpenPair(filename string, memory bool) (p Pair, err error)
  • func (p Pair) Close()
• type Queryable
• type SynchronousMode
• type VacuumStats

Variables

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

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

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, tx *sql.Tx) (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 *sql.Tx, deadline time.Time) (prevDeadline time.Time, err error)

ResetTransactionWarnDeadline allow the atomic function to extend it's 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, tx *sql.Tx, 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.

Accessor는 sqlite db를 다루고 배칭 오퍼레이션을 수행한다.

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.

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 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 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)
	Query(query string, args ...interface{}) (*sql.Rows, error)
	QueryRow(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