db

package
v0.8.0-alpha Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 16 Imported by: 0

Documentation

Overview

Package db wraps the SQLite store (pure Go driver, no CGO) and migrations.

Index

Constants

This section is empty.

Variables

View Source
var ErrNoDatabase = errors.New("there is no database in this folder")

ErrNoDatabase: there's no database in that folder, which is what a new install looks like.

View Source
var Trace func(query string, took time.Duration)

Trace, when set, is told of every statement and how long it took, a query's until its rows are closed. Only builds for measuring set it (docs/PERFORMANCE.md), before the database opens; otherwise it costs one comparison per statement.

Functions

func BuildAt

func BuildAt(ctx context.Context, path string, v Versions) (*sql.DB, error)

BuildAt makes an empty database in dir with exactly these versions of the schema, and returns it open on one connection with foreign keys off, ready to take rows.

It and OpenPlainFile are for working copies only, never the live database, so their rollback journal stays in memory: on disk, every statement made and deleted a journal file, and on Windows each delete can wait on the virus scanner, which held a backup's check for minutes. A crash loses only the copy, which is made again.

func Now

func Now() int64

func OpenForReading

func OpenForReading(dataDir string) (*sql.DB, error)

OpenForReading opens the database of a data folder for looking only: no migrations, no writes, and a short wait if a server is holding it. For tools that run beside a server, or in place of one that won't start, where a broken database has to be an answer rather than a failure. The caller closes it.

func OpenForeign

func OpenForeign(path string) (*sql.DB, error)

OpenForeign opens a database file from outside, to read, trusting nothing in it.

func OpenPlainFile

func OpenPlainFile(path string) (*sql.DB, error)

OpenPlainFile opens a working copy with no pool and no checks on foreign keys, for rewriting one before it's used.

func QuoteIdent

func QuoteIdent(s string) string

QuoteIdent writes a table or column name for a statement.

func RemoveOrphans

func RemoveOrphans(ctx context.Context, d *sql.DB) (int64, error)

RemoveOrphans deletes rows whose parent has gone, and says how many.

func RestoreTriggers

func RestoreTriggers(ctx context.Context, path string) error

RestoreTriggers puts this program's triggers on a database they were taken off for a bulk rewrite, from a clean build of the same schema rather than anything in the file.

func SnapshotTo

func SnapshotTo(ctx context.Context, live *sql.DB, path string) error

SnapshotTo writes a consistent copy of the live database to path, while it's in use: VACUUM INTO reads one point in time and takes no write lock.

Types

type DB

type DB struct {
	*sql.DB
}

func Open

func Open(dataDir string) (*DB, error)

func OpenExisting

func OpenExisting(dataDir string, readOnly bool) (*DB, error)

OpenExisting opens <dataDir>/wms.db without migrating or creating it. readOnly keeps every statement from writing. The first read happens here, so a file that isn't a database at all answers with an error rather than a handle.

func (*DB) Columns

func (d *DB) Columns(ctx context.Context, table string) ([]TableColumn, error)

Columns lists a table's columns. table comes from Tables, never from a person.

func (*DB) GetSetting

func (d *DB) GetSetting(ctx context.Context, key, def string) string

Setting helpers.

func (*DB) Optimize

func (d *DB) Optimize(ctx context.Context)

Optimize lets SQLite refresh its query statistics; cheap, and done after a scan has changed a lot of rows.

func (*DB) SetSetting

func (d *DB) SetSetting(ctx context.Context, key, value string) error

func (*DB) Settings

func (d *DB) Settings(ctx context.Context) (map[string]string, error)

Settings is every setting saved, in one statement, for pages that show many at once.

func (*DB) Tables

func (d *DB) Tables(ctx context.Context) ([]string, error)

Tables lists the ordinary tables, leaving out SQLite's own.

type Recovered

type Recovered struct {
	Tables   []RecoveredTable `json:"tables"`
	Copied   int64            `json:"copied"`
	Lost     int64            `json:"lost"`
	Refused  int64            `json:"refused"`
	Unlinked int64            `json:"unlinked"` // rows removed because what they pointed at was lost
	Unread   int              `json:"unread"`   // tables that couldn't be read at all
}

Recovered is the result of a recovery.

func RecoverInto

func RecoverInto(ctx context.Context, src, dst string) (res *Recovered, err error)

RecoverInto writes a new wms.db in dst from what can be read of the one in src. dst must be a new, empty folder of the caller's. A panic in the driver is turned into an error: a damaged file must never take down whoever is trying to repair it.

type RecoveredTable

type RecoveredTable struct {
	Name   string `json:"name"`
	Copied int64  `json:"copied"`
	// Lost is what couldn't be copied. Where a damaged stretch hides how many rows it
	// held, this is how many row numbers it spans, so it can be more than there were.
	Lost    int64 `json:"lost"`
	Refused int64 `json:"refused"` // rows the new table wouldn't take
	Failed  bool  `json:"failed"`  // nothing of this table could be read at all
}

RecoveredTable says how one table came through.

type TableColumn

type TableColumn struct {
	Name string
	Type string
}

TableColumn is one column of a table, as the database says.

type Versions

type Versions struct {
	Main     int `json:"main"`
	TV       int `json:"tv"`
	Metadata int `json:"metadata"`
	Music    int `json:"music"`
	Games    int `json:"games"`
	// LibTranscode: library transcoding's tables.
	LibTranscode int `json:"libTranscode"`
}

Versions says how far each track of migrations has gone.

func CurrentVersions

func CurrentVersions() Versions

CurrentVersions is what this program builds.

func ReadVersions

func ReadVersions(ctx context.Context, q interface {
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}, prefix string) (Versions, error)

ReadVersions reads a database's versions without changing it.

func (Versions) Newer

func (v Versions) Newer(than Versions) bool

Newer says whether v has anything this program doesn't know about.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL