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 (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
- type ErrUpgradeFailure
- type Migration
- type Pair
- type Queryable
- type SynchronousMode
- type VacuumStats
Constants ¶
This section is empty.
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 ¶
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 ¶
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 ¶
InitializeWithContext creates or upgrades a DB accessor.
func IsErrBusy ¶
IsErrBusy examine the input inerr variable of type error and determine if it's a sqlite3 error for the ErrBusy error code.
func LoggedRetry ¶
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 ¶
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()
Types ¶
type Accessor ¶
An Accessor manages a sqlite database handle and any outstanding batching operations.
Accessor는 sqlite db를 다루고 배칭 오퍼레이션을 수행한다.
func MakeAccessor ¶
MakeAccessor creates a new Accessor.
func MakeErasableAccessor ¶
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 ¶
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) GetPageCount ¶
GetPageCount returns the total number of pages in the database
func (*Accessor) GetPageSize ¶
GetPageSize returns the number of bytes per database page
func (*Accessor) IsSharedCacheConnection ¶
IsSharedCacheConnection returns whether this connection was created using shared-cache connection or not. we use shared cache for in-memory databases
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 ¶
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 ¶
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 ¶
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 ¶
Pair represents two accessors - read and write
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