Artifact 3074524487286e6214bb5504108598f48e7701a764c53ce45f385de63db0cf28:
- File
docs/site/content/docs/reference/sdk/db/api.md
— part of check-in
[6273a0750d]
at
2026-07-22 23:03:24
on branch trunk
— fix: correct go.mod module path to go-libfossil (#76) (#117)
* fix: correct go.mod module path to go-libfossil (#76)
The module directive still declared github.com/danmestas/libfossil after the repository was renamed to go-libfossil. pkg.go.dev/godoc scraping matches the declared module path against its hosting path, so the stale path broke SDK doc generation.
Rename the module path across all four in-repo modules (root, the two db/driver submodules, observer/otel, and docs/site) and every internal import, plus the release workflow, the doc-generation script, and the docs.
No tag has been published under the go-libfossil path yet, so the cross-module requires cannot resolve from the proxy. Add replace directives pointing the in-repo requires at their local directories so GOWORK=off builds and the CI matrix resolve without a published version. These replaces are ignored by downstream consumers and can be dropped once new-path tags are cut.
* Guard releases against replace directives; regenerate SDK docs
The go-libfossil rename bridges the in-repo modules with `replace` directives. Go refuses a main module that carries them, so a tag cut while they are present breaks `go install .../cmd/libfossil@<tag>` and every `@version` fetch of the driver submodules. Add a Release workflow step that fails the job before anything is published if any tracked go.mod still contains a replace directive, so the bridge is a CI-enforced TODO rather than a silent landmine. The step comment records what unblocks a release: re-tag the submodules with the corrected module paths, bump the root requires, then drop the replace blocks.
Regenerate the SDK reference docs. The previous pass only substituted URLs over the pre-existing generated files, leaving stale signatures (Repo.Timeline was still documented as taking LogOpts rather than TimelineOpts). Note that gomarkdoc must be run outside a git worktree — inside one it silently strips every source link.
Also reword the README rename note, which read as though the import path had not changed, and re-sort the ncruces require block. (user: [email protected], size: 13447) [annotate] [blame] [check-ins using]
title: db
<!-- Code generated by gomarkdoc. DO NOT EDIT -->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) error
func DefaultPragmas
func DefaultPragmas() map[string]string
DefaultPragmas 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) error
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
func SeedNobody(d *DB, caps string) error
SeedNobody inserts a "nobody" user with the given capabilities. This controls anonymous access policy for the repo.
func SeedUser
func SeedUser(d *DB, login string) error
type CheckpointMode
CheckpointMode mirrors SQLite's PRAGMA wal_checkpoint(<mode>) argument.
type CheckpointMode int
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
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) 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
func (d *DB) Close() error
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) Driver
func (d *DB) Driver() string
func (*DB) Exec
func (d *DB) Exec(query string, args ...any) (sql.Result, error)
func (*DB) Path
func (d *DB) Path() string
func (*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.Row
func (*DB) SetApplicationID
func (d *DB) SetApplicationID(id int32) error
func (*DB) SqlDB
func (d *DB) SqlDB() *sql.DB
SqlDB returns the underlying *sql.DB connection.
func (*DB) WithTx
func (d *DB) WithTx(fn func(tx *Tx) error) error
type 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() *DriverConfig
RegisteredDriver 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.Row
Generated by gomarkdoc