Documentation
¶
Overview ¶
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/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 Register(cfg DriverConfig)
- 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 (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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateRepoSchema ¶
func DefaultPragmas ¶
DefaultPragmas returns the default pragma settings.
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 ScanInt ¶
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 ¶
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 ¶
ScanTime converts a scanned mtime value to time.Time. Same driver-compatibility rationale as ScanJulianDay.
func SeedConfig ¶
SeedConfig 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 ¶
SeedNobody inserts a "nobody" user with the given capabilities. This controls anonymous access policy for the repo.
Types ¶
type CheckpointMode ¶ added in v0.6.0
type CheckpointMode int
CheckpointMode mirrors SQLite's PRAGMA wal_checkpoint(<mode>) argument.
const ( // 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 ¶ added in v0.6.0
func (m CheckpointMode) String() string
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB wraps a SQLite database connection.
func OpenWith ¶
func OpenWith(path string, cfg OpenConfig) (*DB, error)
OpenWith opens a SQLite database with explicit configuration.
func (*DB) ApplicationID ¶
func (*DB) Checkpoint ¶ added in v0.6.0
func (d *DB) Checkpoint(mode CheckpointMode) error
Checkpoint 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 ¶
Close 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) SetApplicationID ¶
type DriverConfig ¶
type DriverConfig struct {
Name string
BuildDSN func(path string, pragmas map[string]string) string
}
DriverConfig defines a SQLite driver's name and DSN builder.
func RegisteredDriver ¶
func RegisteredDriver() *DriverConfig
RegisteredDriver returns a copy of the currently registered driver config, or nil if none.
type OpenConfig ¶
type OpenConfig struct {
Driver string // override driver name (empty = use registered driver)
Pragmas map[string]string // additional/override pragmas (merged with defaults)
}
OpenConfig allows callers to customize driver selection and pragmas.
type Querier ¶
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)
}
Querier is the common interface satisfied by both *DB and *Tx. Functions that need to work inside transactions accept Querier instead of *DB.
Source Files
Directories