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/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 ¶
- Constants
- func CreateRepoSchema(d *DB) error
- func DefaultPragmas() map[string]string
- func OpenSQL(path string, cfg OpenConfig, params map[string]string) (*sql.DB, error)
- func ReceiptID(q Querier) (int64, 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 ScanTextJulianDay(v any) (float64, bool)
- func ScanTime(v any) (time.Time, bool)
- func SeedConfig(d *DB, rng simio.Rand, projectCode string) error
- func SeedDefaultUsers(d *DB, rng simio.Rand) 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) Bound() bool
- 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) PoolExecs() int64
- 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) UseReceipt(rc *Receipt) *Receipt
- func (d *DB) WithBoundReadTx(fn func(bound *DB) error) error
- func (d *DB) WithBoundTx(fn func(bound *DB) error) error
- func (d *DB) WithReadTx(fn func(tx *Tx) error) error
- func (d *DB) WithTx(fn func(tx *Tx) error) error
- func (d *DB) WriteTxns() int64
- func (d *DB) Writes() int64
- type DriverConfig
- type OpenConfig
- type Querier
- type Receipt
- type Tx
Constants ¶
const ( HashPolicySHA1 = 0 HashPolicyAuto = 1 HashPolicySHA3 = 2 HashPolicySHA3Only = 3 HashPolicyShunSHA1 = 4 )
Fossil's hash-policy config values, in Fossil's own order (see `fossil help hash-policy`). The row holds the integer as text.
Naming follows from the value: SHA1 below HashPolicySHA3, SHA3 at or above it, except HashPolicyAuto, which names with SHA1 until a SHA3 artifact enters the repo. From HashPolicySHA3Only up, an artifact already stored under a legacy SHA1 name is not reused.
Variables ¶
This section is empty.
Functions ¶
func CreateRepoSchema ¶
func DefaultPragmas ¶
DefaultPragmas returns the default pragma settings.
func OpenSQL ¶
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 ReceiptID ¶ added in v0.14.0
ReceiptID returns the rcvid content stored through q is recorded under: the receipt of q's transaction, which is the one given by UseReceipt or, when none was, one made for that transaction alone. Content stored outside a transaction is a receipt of its own.
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 ¶
SQLDriverAndDSN returns the driver name and DSN OpenWith would use, with optional URI query params appended after driver-specific options.
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.
The float64 branch returns the scanned value verbatim, and that exactness is load-bearing rather than incidental. A float64 read off the row IS the stored value, so any "canonicalizing" transform can only move it away from what the row holds. Two consumers compare a scanned mtime against other stored mtimes and would silently return a wrong answer (never an error) if the value were perturbed even by one ulp:
- Timeline's pagination cursor, whose predicate `e.mtime < ? OR (e.mtime = ? AND b.rid < ?)` needs the cursor to compare exactly equal to the row it came from. Raise it by an ulp and that row repeats as the next page's first row; lower it and rows are skipped.
- tag propagation's `tagxref.mtime < ?`, where SQLite compares the bound value against raw stored floats.
Neither is hypothetical for values this library did not write: a value another writer computed differently, or at finer than millisecond resolution, is not on the grid TimeToJulian writes, and snapping it to that grid changes it.
The time.Time branch is the one case where a transform is required rather than harmful — see timeToJulian.
func ScanTextJulianDay ¶ added in v0.11.0
ScanTextJulianDay is ScanJulianDay for a column fossil writes as SQL text: event, plink, attachment and forumpost times. Those hold the 16-digit form (fsltype.TextJulianDayFromMillis), so a time.Time a driver hands back is converted to that form rather than to the exact julianday() ScanJulianDay gives for tagxref.mtime. A float64 passes through unchanged either way.
func ScanTime ¶
ScanTime converts a scanned mtime value to time.Time, at the millisecond SQLite's date functions give it: the time a check-in's D card records. Same driver-compatibility rationale as ScanJulianDay.
func SeedConfig ¶
SeedConfig seeds the config table with project-code, server-code, the schema markers, and hash-policy. 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.
hash-policy is seeded to sha3, which is what `fossil init` writes and so what a repo created here has to say to name its artifacts the same way. A clone is the exception: it adopts its source's policy, not this one, so sync.Clone drops the row the same way it drops project-code.
func SeedDefaultUsers ¶ added in v0.11.0
SeedDefaultUsers inserts the four built-in users `fossil new` creates, with fossil's capabilities (src/db.c db_create_default_users). nobody's set is what every unauthenticated sync request is granted, so it is clone, read and zip only: check-in rights must be granted explicitly. developer and reader are templates other users inherit through v and u. anonymous gets a random password, as fossil gives it; the others have none, so no login can reach them (VerifyLogin requires a stored password).
func SeedNobody ¶
SeedNobody inserts a "nobody" user with the given capabilities. This controls anonymous access policy for the repo. A new repository gets fossil's built-in users from SeedDefaultUsers instead.
Types ¶
type CheckpointMode ¶
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 ¶
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) Bound ¶ added in v0.15.0
Bound reports whether d is a DB WithBoundTx handed its callback, whose statements run in a transaction that d does not own.
func (*DB) Checkpoint ¶
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) PoolExecs ¶ added in v0.8.0
PoolExecs returns how many statements have been executed on the pool rather than inside a transaction. Each one runs in its own implicit transaction, so it costs a BEGIN IMMEDIATE and an fsync of its own and contests the database's single write lock independently of every other. A path that issues one per artifact therefore degrades from slow to failing the moment anything else writes, which is what issue #200 cost a large pull. Tests pin the per-round budget against this counter.
func (*DB) SetApplicationID ¶
func (*DB) UseReceipt ¶ added in v0.14.0
UseReceipt is Tx.UseReceipt for the transaction a bound DB runs in. Only a bound DB has a transaction to give it to.
func (*DB) WithBoundReadTx ¶ added in v0.15.0
WithBoundReadTx is WithBoundTx over a read transaction (see WithReadTx): a DB bound to one snapshot that takes no write lock. fn must not write.
func (*DB) WithBoundTx ¶ added in v0.12.0
WithBoundTx runs fn in one write transaction and hands it a DB bound to that transaction. Every statement on the bound DB runs in the transaction, and every WithTx or WithBoundTx on it is a savepoint there, so code written against a *DB, including code that opens its own transactions, joins this one instead of contending for the write lock from a second connection. The transaction commits when fn returns nil and rolls back everything fn did otherwise. The bound DB is valid only until fn returns, and it cannot be closed or checkpointed, nor hand out its *sql.DB. On a DB that is itself bound, WithBoundTx is a savepoint of that transaction, as WithTx is.
func (*DB) WithReadTx ¶ added in v0.15.0
WithReadTx runs fn in a read transaction: one snapshot of the database, taken without the write lock, so it neither waits for a writer nor holds one up. fn must not write; the drivers refuse or contest a write in it. The transaction ends when fn returns, with nothing to commit. On a bound DB it runs fn in the bound transaction, as WithTx does.
func (*DB) WithTx ¶
WithTx runs fn in a write transaction, which commits when fn returns nil and rolls back otherwise. On a DB that WithBoundTx bound, it runs fn in a savepoint of the bound transaction instead, so it neither waits for a second connection nor commits on its own: fn's error undoes only fn's writes, and the bound transaction decides whether the rest commits.
func (*DB) WriteTxns ¶ added in v0.8.0
WriteTxns counts transactions begun through WithTx. Each is its own BEGIN IMMEDIATE and fsync, and each takes the single write lock independently, so a path that opens one per artifact is both slow and fragile under contention -- the cost issue #200 measured at roughly three per received file. Tests pin the per-round transaction budget against this, which PoolExecs cannot see: moving a per-artifact write from the pool into its own transaction leaves PoolExecs unchanged while the real cost stays.
func (*DB) Writes ¶ added in v0.16.2
Writes counts writes of this DB that have finished: pool Exec calls that returned and WithTx transactions that ended, committed or not. A reader that keeps what it read across calls compares two counts to learn whether a write may have landed in between; counting at the end, not the start, is what makes an unchanged count mean that. A write through another handle on the same file, in this process or another, is not counted.
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.
type Receipt ¶ added in v0.14.0
type Receipt struct {
UID int64
Nonce string
IPAddr string
Clock simio.Clock
// contains filtered or unexported fields
}
Receipt is one arrival of content in the repository: a commit, a sync or clone, a push a server accepts. Fossil records each as a row of rcvfrom, made the first time that arrival stores anything (content_rcvid_init in src/content.c), and every blob or unversioned file it stores names the row in its rcvid. A receipt that stores nothing leaves no row.
The fields are what the row will hold, read when it is made: UID is the user.uid the content came from, Nonce the nonce of the login card that authenticated it, and IPAddr the peer's address or, for local content, a description of its source. An empty Nonce or IPAddr is stored as NULL, as fossil stores an absent one. The row's mtime is the Julian day of the moment it is made, by Clock (nil means real time).
A Receipt is not safe for concurrent use.
func (*Receipt) ID ¶ added in v0.14.0
ID returns the rcvid of the receipt's row, making the row through q if the receipt has none yet. Fossil holds that id for its process in g.rcvid and never looks at the row again (src/content.c, content_rcvid_init); a fossil whose transaction rolls back ends with it. A Receipt outlives transactions, so the transaction or savepoint that makes its row also forgets it if it rolls back (Tx.forgetFrom), and the next use makes a fresh row rather than naming one some other insert may since have taken. A kept id costs no query.
A row made through a Querier that is neither a Tx nor a DB is taken as kept; a row made in one transaction should not be used from another connection before that transaction commits.
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
func (*Tx) UseReceipt ¶ added in v0.14.0
UseReceipt makes rc the receipt content stored in t is recorded under, and returns the one it replaces so a caller can put it back.
Source Files
Directories