db

package
v8.24.2 Latest Latest
Warning

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

 Go to latest Published: May 4, 2024 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package db exposes a lightweight abstraction over the SQLite code. It performs some basic mapping of lower-level types to rqlite types.

Index

Constants

View Source 
const (
	// ModeReadOnly is the mode to open a database in read-only mode.
	ModeReadOnly = true
	// ModeReadWrite is the mode to open a database in read-write mode.
	ModeReadWrite = false
)
View Source 
const (
	SQLiteHeaderSize = 32
)

Variables

View Source 
var (
	// ErrWALReplayDirectoryMismatch is returned when the WAL file(s) are not in the same
	// directory as the database file.
	ErrWALReplayDirectoryMismatch = errors.New("WAL file(s) not in same directory as database file")

	// ErrQueryTimeout is returned when a query times out.
	ErrQueryTimeout = errors.New("query timeout")

	// ErrExecuteTimeout is returned when an execute times out.
	ErrExecuteTimeout = errors.New("execute timeout")
)
View Source 
var DBVersion string

DBVersion is the SQLite version.

Functions

func CheckIntegrity 

func CheckIntegrity(path string, full bool) (bool, error)

CheckIntegrity runs a PRAGMA integrity_check on the database at the given path. If full is true, a full integrity check is performed, otherwise a quick check.

func EnsureDeleteMode added in v8.16.1 

func EnsureDeleteMode(path string) error

EnsureDeleteMode ensures the database at the given path is in DELETE mode.

func IsDELETEModeEnabled 

func IsDELETEModeEnabled(b []byte) bool

IsDELETEModeEnabled checks that the supplied data looks like a SQLite file with DELETE mode enabled.

func IsDELETEModeEnabledSQLiteFile 

func IsDELETEModeEnabledSQLiteFile(path string) bool

IsDELETEModeEnabledSQLiteFile checks that the supplied path looks like a SQLite with DELETE mode enabled.

func IsValidSQLiteData 

func IsValidSQLiteData(b []byte) bool

IsValidSQLiteData checks that the supplied data looks like a SQLite data. See https://www.sqlite.org/fileformat.html.

func IsValidSQLiteFile 

func IsValidSQLiteFile(path string) bool

IsValidSQLiteFile checks that the supplied path looks like a SQLite file. A nonexistent file is considered invalid.

func IsValidSQLiteWALData 

func IsValidSQLiteWALData(b []byte) bool

IsValidSQLiteWALData checks that the supplied data looks like a SQLite WAL file.

func IsValidSQLiteWALFile 

func IsValidSQLiteWALFile(path string) bool

IsValidSQLiteWALFile checks that the supplied path looks like a SQLite WAL file. See https://www.sqlite.org/fileformat2.html#walformat. A nonexistent file is considered invalid.

func IsWALModeEnabled 

func IsWALModeEnabled(b []byte) bool

IsWALModeEnabled checks that the supplied data looks like a SQLite data with WAL mode enabled.

func IsWALModeEnabledSQLiteFile 

func IsWALModeEnabledSQLiteFile(path string) bool

IsWALModeEnabledSQLiteFile checks that the supplied path looks like a SQLite with WAL mode enabled.

func MakeDSN added in v8.16.6 

func MakeDSN(path string, readOnly, fkEnabled, walEnabled bool) string

MakeDSN returns a SQLite DSN for the given path, with the given options.

func RemoveFiles 

func RemoveFiles(path string) error

RemoveFiles removes the SQLite database file, and any associated WAL and SHM files.

func ReplayWAL 

func ReplayWAL(path string, wals []string, deleteMode bool) error

ReplayWAL replays the given WAL files into the database at the given path, in the order given by the slice. The supplied WAL files must be in the same directory as the database file and are deleted as a result of the replay operation. If deleteMode is true, the database file will be in DELETE mode after the replay operation, otherwise it will be in WAL mode. Finally, regardless of deleteMode, there will be no "true" WAL file after the replay operation.

func ResetStats 

func ResetStats()

ResetStats resets the expvar stats for this module. Mostly for test purposes.

func WALPath added in v8.14.0 

func WALPath(dbPath string) string

WALPath returns the path to the WAL file for the given database path.

Types

type CheckpointMode added in v8.18.2 

type CheckpointMode int

CheckpointMode is the mode in which a checkpoint runs. 

const (
	// CheckpointRestart instructs the checkpoint to run in restart mode.
	CheckpointRestart CheckpointMode = iota
	// CheckpointTruncate instructs the checkpoint to run in truncate mode.
	CheckpointTruncate
)

type DB 

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

DB is the SQL database.

func Open 

func Open(dbPath string, fkEnabled, wal bool) (retDB *DB, retErr error)

Open opens a file-based database, creating it if it does not exist. After this function returns, an actual SQLite file will always exist.

func (*DB) Backup 

func (db *DB) Backup(path string, vacuum bool) error

Backup writes a consistent snapshot of the database to the given file. The resultant SQLite database file will be in DELETE mode. This function can be called when changes to the database are in flight.

func (*DB) BusyTimeout added in v8.18.2 

func (db *DB) BusyTimeout() (rwMs, roMs int, err error)

BusyTimeout returns the current busy timeout value.

func (*DB) Checkpoint 

func (db *DB) Checkpoint(mode CheckpointMode) error

Checkpoint checkpoints the WAL file. If the WAL file is not enabled, this function is a no-op.

func (*DB) CheckpointWithTimeout 

func (db *DB) CheckpointWithTimeout(mode CheckpointMode, dur time.Duration) (err error)

CheckpointWithTimeout performs a WAL checkpoint. If the checkpoint does not run to completion within the given duration, an error is returned. If the duration is 0, the busy timeout is not modified before executing the checkpoint.

func (*DB) Close 

func (db *DB) Close() error

Close closes the underlying database connection.

func (*DB) CompileOptions 

func (db *DB) CompileOptions() ([]string, error)

CompileOptions returns the SQLite compilation options.

func (*DB) ConnectionPoolStats 

func (db *DB) ConnectionPoolStats(sqlDB *sql.DB) *PoolStats

ConnectionPoolStats returns database pool statistics

func (*DB) Copy 

func (db *DB) Copy(dstDB *DB) error

Copy copies the contents of the database to the given database. All other attributes of the given database remain untouched e.g. whether it's an on-disk database, except the database will be placed in DELETE mode. This function can be called when changes to the source database are in flight.

func (*DB) DBLastModified added in v8.16.8 

func (db *DB) DBLastModified() (time.Time, error)

DBLastModified returns the last modified time of the database file.

func (*DB) DBSum added in v8.16.8 

func (db *DB) DBSum() (string, error)

DBSum returns the MD5 checksum of the database file.

func (*DB) DisableCheckpointing 

func (db *DB) DisableCheckpointing() error

DisableCheckpointing disables the automatic checkpointing that occurs when the WAL reaches a certain size. This is key for full control of snapshotting. and can be useful for testing.

func (*DB) Dump 

func (db *DB) Dump(w io.Writer) error

Dump writes a consistent snapshot of the database in SQL text format. This function can be called when changes to the database are in flight.

func (*DB) EnableCheckpointing 

func (db *DB) EnableCheckpointing() error

EnableCheckpointing enables the automatic checkpointing that occurs when the WAL reaches a certain size.

func (*DB) Execute 

func (db *DB) Execute(req *command.Request, xTime bool) ([]*command.ExecuteQueryResponse, error)

Execute executes queries that modify the database.

func (*DB) ExecuteStringStmt 

func (db *DB) ExecuteStringStmt(query string) ([]*command.ExecuteQueryResponse, error)

ExecuteStringStmt executes a single query that modifies the database. This is primarily a convenience function.

func (*DB) ExecuteStringStmtWithTimeout added in v8.19.0 

func (db *DB) ExecuteStringStmtWithTimeout(query string, timeout time.Duration) ([]*command.ExecuteQueryResponse, error)

ExecuteStringStmtWithTimeout executes a single query that modifies the database. It also sets a timeout for the query. This is primarily a convenience function.

func (*DB) FKEnabled 

func (db *DB) FKEnabled() bool

FKEnabled returns whether Foreign Key constraints are enabled.

func (*DB) FileSize 

func (db *DB) FileSize() (int64, error)

FileSize returns the size of the SQLite file on disk. If running in on-memory mode, this function returns 0.

func (*DB) GetCheckpointing 

func (db *DB) GetCheckpointing() (int, error)

GetCheckpointing returns the current checkpointing setting.

func (*DB) GetSynchronousMode 

func (db *DB) GetSynchronousMode() (int, error)

GetSynchronousMode returns the current synchronous mode.

func (*DB) IntegrityCheck added in v8.16.8 

func (db *DB) IntegrityCheck(full bool) ([]*command.QueryRows, error)

IntegrityCheck runs a PRAGMA integrity_check on the database. If full is true, a full integrity check is performed, otherwise a quick check. It returns after hitting the first integrity failure, if any.

func (*DB) LastModified added in v8.16.1 

func (db *DB) LastModified() (time.Time, error)

LastModified returns the last modified time of the database file, or the WAL file, whichever is most recent.

func (*DB) Path 

func (db *DB) Path() string

Path returns the path of this database.

func (*DB) Query 

func (db *DB) Query(req *command.Request, xTime bool) ([]*command.QueryRows, error)

Query executes queries that return rows, but don't modify the database.

func (*DB) QueryStringStmt 

func (db *DB) QueryStringStmt(query string) ([]*command.QueryRows, error)

QueryStringStmt executes a single query that return rows, but don't modify database.

func (*DB) QueryStringStmtWithTimeout added in v8.19.0 

func (db *DB) QueryStringStmtWithTimeout(query string, tx bool, timeout time.Duration) ([]*command.QueryRows, error)

QueryStringStmtWithTimeout executes a single query that return rows, but don't modify database. It also sets a timeout for the query.

func (*DB) Request 

func (db *DB) Request(req *command.Request, xTime bool) ([]*command.ExecuteQueryResponse, error)

Request processes a request that can contain both executes and queries.

func (*DB) RequestStringStmts 

func (db *DB) RequestStringStmts(stmts []string) ([]*command.ExecuteQueryResponse, error)

RequestStringStmts processes a request that can contain both executes and queries.

func (*DB) RequestStringStmtsWithTimeout added in v8.19.0 

func (db *DB) RequestStringStmtsWithTimeout(stmts []string, timeout time.Duration) ([]*command.ExecuteQueryResponse, error)

RequestStringStmtsWithTimeout processes a request that can contain both executes and queries.

func (*DB) Serialize 

func (db *DB) Serialize() ([]byte, error)

Serialize returns a byte slice representation of the SQLite database. For an ordinary on-disk database file, the serialization is just a copy of the disk file. If the database is in WAL mode, a temporary on-disk copy is made, and it is this copy that is serialized. This function must not be called while any writes are happening to the database.

func (*DB) SetBusyTimeout added in v8.18.2 

func (db *DB) SetBusyTimeout(rwMs, roMs int) (err error)

SetBusyTimeout sets the busy timeout for the database. If a timeout is is less than zero it is not set.

func (*DB) SetSynchronousMode 

func (db *DB) SetSynchronousMode(mode string) error

SetSynchronousMode sets the synchronous mode of the database.

func (*DB) Size 

func (db *DB) Size() (int64, error)

Size returns the size of the database in bytes. "Size" is defined as page_count * schema.page_size.

func (*DB) Stats 

func (db *DB) Stats() (map[string]interface{}, error)

Stats returns status and diagnostics for the database.

func (*DB) StmtReadOnly 

func (db *DB) StmtReadOnly(sql string) (bool, error)

StmtReadOnly returns whether the given SQL statement is read-only. As per https://www.sqlite.org/c3ref/stmt_readonly.html, this function may not return 100% correct results, but should cover most scenarios.

func (*DB) StmtReadOnlyWithConn 

func (db *DB) StmtReadOnlyWithConn(sql string, conn *sql.Conn) (bool, error)

StmtReadOnlyWithConn returns whether the given SQL statement is read-only, using the given connection.

func (*DB) Vacuum 

func (db *DB) Vacuum() error

Vacuum runs a VACUUM on the database.

func (*DB) VacuumInto added in v8.16.8 

func (db *DB) VacuumInto(path string) error

VacuumInto VACUUMs the database into the file at path

func (*DB) WALEnabled 

func (db *DB) WALEnabled() bool

WALEnabled returns whether WAL mode is enabled.

func (*DB) WALLastModified added in v8.16.8 

func (db *DB) WALLastModified() (time.Time, error)

WALLastModified returns the last modified time of the WAL file.

func (*DB) WALPath 

func (db *DB) WALPath() string

WALPath returns the path to the WAL file for this database.

func (*DB) WALSize 

func (db *DB) WALSize() (int64, error)

WALSize returns the size of the SQLite WAL file on disk. If running in WAL mode is not enabled, this function returns 0.

func (*DB) WALSum added in v8.16.8 

func (db *DB) WALSum() (string, error)

WALSum returns the MD5 checksum of the WAL file.

type PoolStats 

type PoolStats struct {
	MaxOpenConnections int           `json:"max_open_connections"`
	OpenConnections    int           `json:"open_connections"`
	InUse              int           `json:"in_use"`
	Idle               int           `json:"idle"`
	WaitCount          int64         `json:"wait_count"`
	WaitDuration       time.Duration `json:"wait_duration"`
	MaxIdleClosed      int64         `json:"max_idle_closed"`
	MaxIdleTimeClosed  int64         `json:"max_idle_time_closed"`
	MaxLifetimeClosed  int64         `json:"max_lifetime_closed"`
}

PoolStats represents connection pool statistics

type SwappableDB added in v8.17.0 

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

SwappableDB is a wrapper around DB that allows the underlying database to be swapped out in a thread-safe manner.

func OpenSwappable added in v8.17.0 

func OpenSwappable(dbPath string, fkEnabled, wal bool) (*SwappableDB, error)

OpenSwappable returns a new SwappableDB instance, which opens the database at the given path.

func (*SwappableDB) Backup added in v8.17.0 

func (s *SwappableDB) Backup(path string, vacuum bool) error

Backup calls Backup on the underlying database.

func (*SwappableDB) Checkpoint added in v8.17.0 

func (s *SwappableDB) Checkpoint(mode CheckpointMode) error

Checkpoint calls Checkpoint on the underlying database.

func (*SwappableDB) Close added in v8.17.0 

func (s *SwappableDB) Close() error

Close closes the underlying database.

func (*SwappableDB) Dump added in v8.17.0 

func (s *SwappableDB) Dump(w io.Writer) error

Dump calls Dump on the underlying database.

func (*SwappableDB) Execute added in v8.17.0 

func (s *SwappableDB) Execute(ex *command.Request, xTime bool) ([]*command.ExecuteQueryResponse, error)

Execute calls Execute on the underlying database.

func (*SwappableDB) FKEnabled added in v8.17.0 

func (s *SwappableDB) FKEnabled() bool

FKEnabled calls FKEnabled on the underlying database.

func (*SwappableDB) FileSize added in v8.24.0 

func (s *SwappableDB) FileSize() (int64, error)

FileSize calls FileSize on the underlying database.

func (*SwappableDB) Path added in v8.17.0 

func (s *SwappableDB) Path() string

Path calls Path on the underlying database.

func (*SwappableDB) Query added in v8.17.0 

func (s *SwappableDB) Query(q *command.Request, xTime bool) ([]*command.QueryRows, error)

Query calls Query on the underlying database.

func (*SwappableDB) QueryStringStmt added in v8.17.0 

func (s *SwappableDB) QueryStringStmt(query string) ([]*command.QueryRows, error)

QueryStringStmt calls QueryStringStmt on the underlying database.

func (*SwappableDB) Request added in v8.17.0 

func (s *SwappableDB) Request(req *command.Request, xTime bool) ([]*command.ExecuteQueryResponse, error)

Request calls Request on the underlying database.

func (*SwappableDB) Serialize added in v8.17.0 

func (s *SwappableDB) Serialize() ([]byte, error)

Serialize calls Serialize on the underlying database.

func (*SwappableDB) Stats added in v8.17.0 

func (s *SwappableDB) Stats() (map[string]interface{}, error)

Stats returns the underlying database's stats.

func (*SwappableDB) StmtReadOnly added in v8.17.0 

func (s *SwappableDB) StmtReadOnly(sql string) (bool, error)

StmtReadOnly calls StmtReadOnly on the underlying database.

func (*SwappableDB) Swap added in v8.17.0 

func (s *SwappableDB) Swap(path string, fkConstraints, walEnabled bool) error

Swap swaps the underlying database with that at the given path. The Swap operation may fail on some platforms if the file at path is open by another process. It is the caller's responsibility to ensure the file at path is not in use.

func (*SwappableDB) VacuumInto added in v8.17.0 

func (s *SwappableDB) VacuumInto(path string) error

VacuumInto calls VacuumInto on the underlying database.

func (*SwappableDB) WALEnabled added in v8.17.0 

func (s *SwappableDB) WALEnabled() bool

WALEnabled calls WALEnabled on the underlying database.

Source Files

View all Source files

Directories

Path Synopsis
wal
walr

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.