sqlite

Documentation

Overview

Package sqlite opens the one SQLite handle of a site with every connection rule on, on Linux and macOS only.

Index

• Constants
• Variables
• func Classify(err error) error
• func Migrate(ctx context.Context, db *sql.DB, m Migrations) (err error)
• func NewSnapshotter(db *sql.DB) dbkit.Snapshotter
• func Open(address string, opts Options) (*sql.DB, error)
• func Rebuild(ctx context.Context, db *sql.DB, ...) (err error)
• type Migrations
• type Options
• type Synchronous

Constants

const LibcVersion = "v1.77.1"

LibcVersion is the modernc.org/libc version the driver is pinned with.

Variables

var ErrSnapshotRunning = errors.New("dbkit: another snapshot is writing into this folder")

ErrSnapshotRunning is the error of a snapshot into a folder another snapshot is writing into.

Functions

func Classify

func Classify(err error) error

Classify returns err wrapped in its dbkit error class, or err unchanged when it has none or already carries it.

func Migrate

func Migrate(ctx context.Context, db *sql.DB, m Migrations) (err error)

Migrate applies every pending migration of m to the database of db while it holds the lock file beside it.

func NewSnapshotter

func NewSnapshotter(db *sql.DB) dbkit.Snapshotter

NewSnapshotter returns a Snapshotter of the database of db.

func Open

func Open(address string, opts Options) (*sql.DB, error)

Open returns a handle on the SQLite file of address with every connection rule on, and connects to nothing.

func Rebuild

func Rebuild(ctx context.Context, db *sql.DB, done func(context.Context, *sql.Tx) (bool, error),
	steps func(context.Context, *sql.Tx) error) (err error)

Rebuild runs steps for a goose RunDB migration in one transaction with foreign keys off, unless done answers true.

Types

type Migrations

type Migrations struct {
	// Table is the owner's version table, a plain identifier that is no SQLite keyword and starts with no sqlite_.
	Table string
	// FS holds the owner's SQL migration files at its root, and nil means none.
	FS fs.FS
	// Go are the owner's Go migrations, each built with goose.NewGoMigration.
	Go []*goose.Migration
	// LockWait is how long a run waits for the migration lock, above zero.
	LockWait time.Duration
	// LockPoll is how often a waiting run tries the migration lock, above zero.
	LockPoll time.Duration
}

Migrations are the migrations of one owner and how a run of them waits for the migration lock.

type Options

type Options struct {
	// BusyTimeout is how long a connection waits for a lock, from 1ms to 596h31m23.647s.
	BusyTimeout time.Duration
	// CacheSize is the page cache of each connection in kibibytes, from 1 to 2147483647.
	CacheSize int
	// MaxConns caps the open and idle connections, 2 or more, each holding a page cache of CacheSize.
	MaxConns int
	// Synchronous is SynchronousNormal or SynchronousFull.
	Synchronous Synchronous
	// JournalSizeLimit is the size in bytes the write-ahead log keeps after a checkpoint, and nil sets no limit.
	JournalSizeLimit *int64
	// Functions are the Go functions SQL may call, one list built once per process, and nil means none.
	Functions *dbkit.FunctionList
	// BaseFolder is the absolute folder a relative path resolves against, and empty refuses a relative path.
	BaseFolder string
	// Create lets Open accept a missing file, which the first connection creates.
	Create bool
	// Logger receives the notes of the handle, and nil discards them.
	Logger *slog.Logger
}

Options configures one SQLite handle. BusyTimeout, CacheSize, MaxConns and Synchronous are required.

type Synchronous

type Synchronous int

Synchronous is how often SQLite syncs the write-ahead log to disk.

const (
	// SynchronousNormal syncs the write-ahead log at each checkpoint.
	SynchronousNormal Synchronous = iota + 1
	// SynchronousFull syncs the write-ahead log at every commit.
	SynchronousFull
)