db
db
import "github.com/danmestas/go-libfossil/db"Package db provides a SQLite database layer with pluggable drivers.
Two SQLite drivers ship with libfossil — modernc (pure Go, default) and ncruces (WASM-capable). Select one at build time by importing its driver package:
import _ "github.com/danmestas/go-libfossil/db/driver/modernc"Open and OpenWith handle DSN construction, WAL/pragma setup, and WASM-specific workarounds. Use DB.WithTx for transaction scoping with automatic rollback on error.
The Querier interface (Exec, QueryRow, Query) is satisfied by both DB and Tx, allowing callers to write transaction-agnostic code.
Index
- func CreateRepoSchema(d *DB) error
- func DefaultPragmas() map[string]string
- func OpenSQL(path string, cfg OpenConfig, params map[string]string) (*sql.DB, error)
- func Register(cfg DriverConfig)
- func SQLDriverAndDSN(path string, cfg OpenConfig, params map[string]string) (string, string)
- func ScanInt(v any) (int, bool)
- func ScanJulianDay(v any) (float64, bool)
- func ScanTime(v any) (time.Time, bool)
- func SeedConfig(d *DB, rng simio.Rand, projectCode string) error
- func SeedNobody(d *DB, caps string) error
- func SeedUser(d *DB, login string) error
- type CheckpointMode
- type DB
- func Open(path string) (*DB, error)
- func OpenWith(path string, cfg OpenConfig) (*DB, error)
- func (d *DB) ApplicationID() (int32, error)
- func (d *DB) Checkpoint(mode CheckpointMode) error
- func (d *DB) Close() error
- func (d *DB) Driver() string
- func (d *DB) Exec(query string, args …any) (sql.Result, error)
- func (d *DB) Path() string
- func (d *DB) Query(query string, args …any) (*sql.Rows, error)
- func (d *DB) QueryRow(query string, args …any) *sql.Row
- func (d *DB) SetApplicationID(id int32) error
- func (d *DB) SqlDB() *sql.DB
- func (d *DB) WithTx(fn func(tx *Tx) error) error
- type DriverConfig
- type OpenConfig
- type Querier
- type Tx
func CreateRepoSchema
func CreateRepoSchema(d *DB) errorfunc DefaultPragmas
func DefaultPragmas() map[string]stringDefaultPragmas returns the default pragma settings.
func OpenSQL
func OpenSQL(path string, cfg OpenConfig, params map[string]string) (*sql.DB, error)OpenSQL opens a raw *sql.DB using the registered driver and the same DSN construction as OpenWith. params are appended as URI query parameters after driver pragmas, so callers can request options such as mode=ro without constructing driver-specific DSNs.
func Register
func Register(cfg DriverConfig)Register registers a SQLite driver for use by Open/OpenWith. Must be called exactly once (typically from a driver package’s init()). Panics if called more than once.
func SQLDriverAndDSN
func SQLDriverAndDSN(path string, cfg OpenConfig, params map[string]string) (string, string)SQLDriverAndDSN returns the driver name and DSN OpenWith would use, with optional URI query params appended after driver-specific options.
func ScanInt
func ScanInt(v any) (int, bool)ScanInt converts a scanned value to int. SQLite drivers differ on BOOLEAN columns: modernc returns int64, ncruces returns bool. Scan the column into an `any` variable, then pass it here.
func ScanJulianDay
func ScanJulianDay(v any) (float64, bool)ScanJulianDay converts a scanned mtime value to a float64 Julian Day Number. SQLite drivers return mtime differently: modernc returns float64, ncruces returns time.Time for DATETIME/TIMESTAMP/DATE columns. Scan the column into an `any` variable, then pass it here.
func ScanTime
func ScanTime(v any) (time.Time, bool)ScanTime converts a scanned mtime value to time.Time. Same driver-compatibility rationale as ScanJulianDay.
func SeedConfig
func SeedConfig(d *DB, rng simio.Rand, projectCode string) errorSeedConfig seeds the config table with project-code, server-code, and schema markers. If projectCode is empty, a fresh 40-char lowercase-hex project-code is generated from rng. If non-empty, it must match ^[0-9a-f]{40}$; otherwise an error is returned and no rows are written. Server-code is always generated.
func SeedNobody
func SeedNobody(d *DB, caps string) errorSeedNobody inserts a “nobody” user with the given capabilities. This controls anonymous access policy for the repo.
func SeedUser
func SeedUser(d *DB, login string) errortype CheckpointMode
CheckpointMode mirrors SQLite’s PRAGMA wal_checkpoint(<mode>) argument.
type CheckpointMode intconst (
// CheckpointPassive checkpoints frames not held by readers; never blocks.
// Appropriate for periodic background checkpoints.
CheckpointPassive CheckpointMode = iota
// CheckpointFull blocks new writers until all frames are checkpointed.
CheckpointFull
// CheckpointRestart is FULL plus restarts the WAL file.
CheckpointRestart
// CheckpointTruncate is RESTART plus truncates the WAL file to zero bytes.
// Produces the most compact on-disk file and is what Close uses.
CheckpointTruncate
)func (CheckpointMode) String
func (m CheckpointMode) String() stringtype DB
DB wraps a SQLite database connection.
type DB struct {
// contains filtered or unexported fields
}func Open
func Open(path string) (*DB, error)Open opens a SQLite database with the registered driver and default pragmas.
func OpenWith
func OpenWith(path string, cfg OpenConfig) (*DB, error)OpenWith opens a SQLite database with explicit configuration.
func (*DB) ApplicationID
func (d *DB) ApplicationID() (int32, error)func (*DB) Checkpoint
func (d *DB) Checkpoint(mode CheckpointMode) errorCheckpoint runs PRAGMA wal_checkpoint(<mode>) against the database. Safe to call on a live database. PASSIVE never blocks; TRUNCATE produces the most compact on-disk layout. On a non-WAL database the underlying PRAGMA is a no-op and returns nil.
func (*DB) Close
func (d *DB) Close() errorClose runs PRAGMA wal_checkpoint(TRUNCATE) before closing the underlying connection so the on-disk file is readable by external SQLite/fossil tooling. The WASM/WASI build path does not use WAL, so the checkpoint is skipped there. Checkpoint errors are joined with the close error so the connection is always closed regardless of checkpoint outcome.
func (*DB) Driver
func (d *DB) Driver() stringfunc (*DB) Exec
func (d *DB) Exec(query string, args ...any) (sql.Result, error)func (*DB) Path
func (d *DB) Path() stringfunc (*DB) Query
func (d *DB) Query(query string, args ...any) (*sql.Rows, error)func (*DB) QueryRow
func (d *DB) QueryRow(query string, args ...any) *sql.Rowfunc (*DB) SetApplicationID
func (d *DB) SetApplicationID(id int32) errorfunc (*DB) SqlDB
func (d *DB) SqlDB() *sql.DBSqlDB returns the underlying *sql.DB connection.
func (*DB) WithTx
func (d *DB) WithTx(fn func(tx *Tx) error) errortype DriverConfig
DriverConfig defines a SQLite driver’s name and DSN builder.
type DriverConfig struct {
Name string
BuildDSN func(path string, pragmas map[string]string) string
}func RegisteredDriver
func RegisteredDriver() *DriverConfigRegisteredDriver returns a copy of the currently registered driver config, or nil if none.
type OpenConfig
OpenConfig allows callers to customize driver selection and pragmas.
type OpenConfig struct {
Driver string // override driver name (empty = use registered driver)
Pragmas map[string]string // additional/override pragmas (merged with defaults)
}type Querier
Querier is the common interface satisfied by both *DB and *Tx. Functions that need to work inside transactions accept Querier instead of *DB.
type Querier interface {
Exec(query string, args ...any) (sql.Result, error)
QueryRow(query string, args ...any) *sql.Row
Query(query string, args ...any) (*sql.Rows, error)
}type Tx
type Tx struct {
// contains filtered or unexported fields
}func (*Tx) Exec
func (t *Tx) Exec(query string, args ...any) (sql.Result, error)func (*Tx) Query
func (t *Tx) Query(query string, args ...any) (*sql.Rows, error)func (*Tx) QueryRow
func (t *Tx) QueryRow(query string, args ...any) *sql.RowGenerated by gomarkdoc