Artifact [3824fba956]

Artifact 3824fba956019dbf5297c119273b9d1b10a48789bc2c8b85680d86f8bfd5addf:

• File docs/site/content/docs/reference/sdk/db/api.md — part of check-in [f30849a466] at 2026-04-26 14:14:53 on branch trunk — docs: usability improvements from DX audit (#9)

  Implements all seven recommended changes from the docs audit:

  1. SDK pages now show package names in nav. Add scripts/prepend-sdk-frontmatter.sh that prepends '--- title: <pkg> ---' to each gomarkdoc-generated api.md; wired into 'make docs-gen-sdk'. Sidebar previously showed five undifferentiated 'API' entries; now shows cli, db, dst, libfossil, observer/otel.

  2. /examples/ populated with paragraphs + GitHub deep-links for embed-repo-api and wasm. No longer a placeholder pointing back at the repo.

  3. Architecture page gets an inline SVG mirroring the landing-page diagram. Self-contained CSS (uses currentColor + ember accent) so it tracks Hextra's light/dark theme without depending on the landing's CSS scope.

  4. Cross-links added: quickstart -> production + extension-points, migration -> architecture, architecture -> extension-points. Extension Points and Production patterns are now reachable via prose, not just the sidebar.

  5. /docs/ landing expanded from 3 sentences to a 7-line subsection map calling out each page's purpose.

  6. Version indicator in navbar (libfossil v0.4.2). Override layouts/_partials/navbar-title.html mimics Hextra's default and appends a small mono version tag from .Site.Params.version.

  7. New /docs/production/ page covering error handling, context cancellation, telemetry wiring, repo-handle lifetime, and driver selection — the patterns the quickstart's log.Fatal shortcuts gloss over. (user: [email protected], size: 9901) [annotate] [blame] [check-ins using]

---
title: db
---

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# db

```go
import "github.com/danmestas/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/libfossil/db/driver/modernc"
```

[Open](<#Open>) and [OpenWith](<#OpenWith>) handle DSN construction, WAL/pragma setup, and WASM\-specific workarounds. Use [DB.WithTx](<#DB.WithTx>) for transaction scoping with automatic rollback on error.

The [Querier](<#Querier>) interface \(Exec, QueryRow, Query\) is satisfied by both [DB](<#DB>) and [Tx](<#Tx>), allowing callers to write transaction\-agnostic code.

## Index

- [func CreateRepoSchema\(d \*DB\) error](<#CreateRepoSchema>)
- [func DefaultPragmas\(\) map\[string\]string](<#DefaultPragmas>)
- [func Register\(cfg DriverConfig\)](<#Register>)
- [func ScanInt\(v any\) \(int, bool\)](<#ScanInt>)
- [func ScanJulianDay\(v any\) \(float64, bool\)](<#ScanJulianDay>)
- [func ScanTime\(v any\) \(time.Time, bool\)](<#ScanTime>)
- [func SeedConfig\(d \*DB, rng simio.Rand\) error](<#SeedConfig>)
- [func SeedNobody\(d \*DB, caps string\) error](<#SeedNobody>)
- [func SeedUser\(d \*DB, login string\) error](<#SeedUser>)
- [type DB](<#DB>)
  - [func Open\(path string\) \(\*DB, error\)](<#Open>)
  - [func OpenWith\(path string, cfg OpenConfig\) \(\*DB, error\)](<#OpenWith>)
  - [func \(d \*DB\) ApplicationID\(\) \(int32, error\)](<#DB.ApplicationID>)
  - [func \(d \*DB\) Close\(\) error](<#DB.Close>)
  - [func \(d \*DB\) Driver\(\) string](<#DB.Driver>)
  - [func \(d \*DB\) Exec\(query string, args ...any\) \(sql.Result, error\)](<#DB.Exec>)
  - [func \(d \*DB\) Path\(\) string](<#DB.Path>)
  - [func \(d \*DB\) Query\(query string, args ...any\) \(\*sql.Rows, error\)](<#DB.Query>)
  - [func \(d \*DB\) QueryRow\(query string, args ...any\) \*sql.Row](<#DB.QueryRow>)
  - [func \(d \*DB\) SetApplicationID\(id int32\) error](<#DB.SetApplicationID>)
  - [func \(d \*DB\) SqlDB\(\) \*sql.DB](<#DB.SqlDB>)
  - [func \(d \*DB\) WithTx\(fn func\(tx \*Tx\) error\) error](<#DB.WithTx>)
- [type DriverConfig](<#DriverConfig>)
  - [func RegisteredDriver\(\) \*DriverConfig](<#RegisteredDriver>)
- [type OpenConfig](<#OpenConfig>)
- [type Querier](<#Querier>)
- [type Tx](<#Tx>)
  - [func \(t \*Tx\) Exec\(query string, args ...any\) \(sql.Result, error\)](<#Tx.Exec>)
  - [func \(t \*Tx\) Query\(query string, args ...any\) \(\*sql.Rows, error\)](<#Tx.Query>)
  - [func \(t \*Tx\) QueryRow\(query string, args ...any\) \*sql.Row](<#Tx.QueryRow>)


<a name="CreateRepoSchema"></a>
## func [CreateRepoSchema](<https://github.com/danmestas/libfossil/blob/main/db/schema.go#L193>)

```go
func CreateRepoSchema(d *DB) error
```



<a name="DefaultPragmas"></a>
## func [DefaultPragmas](<https://github.com/danmestas/libfossil/blob/main/db/config.go#L10>)

```go
func DefaultPragmas() map[string]string
```

DefaultPragmas returns the default pragma settings.

<a name="Register"></a>
## func [Register](<https://github.com/danmestas/libfossil/blob/main/db/register.go#L14>)

```go
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.

<a name="ScanInt"></a>
## func [ScanInt](<https://github.com/danmestas/libfossil/blob/main/db/scan.go#L43>)

```go
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.

<a name="ScanJulianDay"></a>
## func [ScanJulianDay](<https://github.com/danmestas/libfossil/blob/main/db/scan.go#L12>)

```go
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.

<a name="ScanTime"></a>
## func [ScanTime](<https://github.com/danmestas/libfossil/blob/main/db/scan.go#L27>)

```go
func ScanTime(v any) (time.Time, bool)
```

ScanTime converts a scanned mtime value to time.Time. Same driver\-compatibility rationale as ScanJulianDay.

<a name="SeedConfig"></a>
## func [SeedConfig](<https://github.com/danmestas/libfossil/blob/main/db/schema.go#L235>)

```go
func SeedConfig(d *DB, rng simio.Rand) error
```



<a name="SeedNobody"></a>
## func [SeedNobody](<https://github.com/danmestas/libfossil/blob/main/db/schema.go#L224>)

```go
func SeedNobody(d *DB, caps string) error
```

SeedNobody inserts a "nobody" user with the given capabilities. This controls anonymous access policy for the repo.

<a name="SeedUser"></a>
## func [SeedUser](<https://github.com/danmestas/libfossil/blob/main/db/schema.go#L208>)

```go
func SeedUser(d *DB, login string) error
```



<a name="DB"></a>
## type [DB](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L10-L14>)

DB wraps a SQLite database connection.

```go
type DB struct {
    // contains filtered or unexported fields
}
```

<a name="Open"></a>
### func [Open](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L17>)

```go
func Open(path string) (*DB, error)
```

Open opens a SQLite database with the registered driver and default pragmas.

<a name="OpenWith"></a>
### func [OpenWith](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L22>)

```go
func OpenWith(path string, cfg OpenConfig) (*DB, error)
```

OpenWith opens a SQLite database with explicit configuration.

<a name="DB.ApplicationID"></a>
### func \(\*DB\) [ApplicationID](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L115>)

```go
func (d *DB) ApplicationID() (int32, error)
```



<a name="DB.Close"></a>
### func \(\*DB\) [Close](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L86>)

```go
func (d *DB) Close() error
```



<a name="DB.Driver"></a>
### func \(\*DB\) [Driver](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L94>)

```go
func (d *DB) Driver() string
```



<a name="DB.Exec"></a>
### func \(\*DB\) [Exec](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L98>)

```go
func (d *DB) Exec(query string, args ...any) (sql.Result, error)
```



<a name="DB.Path"></a>
### func \(\*DB\) [Path](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L90>)

```go
func (d *DB) Path() string
```



<a name="DB.Query"></a>
### func \(\*DB\) [Query](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L106>)

```go
func (d *DB) Query(query string, args ...any) (*sql.Rows, error)
```



<a name="DB.QueryRow"></a>
### func \(\*DB\) [QueryRow](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L102>)

```go
func (d *DB) QueryRow(query string, args ...any) *sql.Row
```



<a name="DB.SetApplicationID"></a>
### func \(\*DB\) [SetApplicationID](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L110>)

```go
func (d *DB) SetApplicationID(id int32) error
```



<a name="DB.SqlDB"></a>
### func \(\*DB\) [SqlDB](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L79>)

```go
func (d *DB) SqlDB() *sql.DB
```

SqlDB returns the underlying \*sql.DB connection.

<a name="DB.WithTx"></a>
### func \(\*DB\) [WithTx](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L137>)

```go
func (d *DB) WithTx(fn func(tx *Tx) error) error
```



<a name="DriverConfig"></a>
## type [DriverConfig](<https://github.com/danmestas/libfossil/blob/main/db/register.go#L4-L7>)

DriverConfig defines a SQLite driver's name and DSN builder.

```go
type DriverConfig struct {
    Name     string
    BuildDSN func(path string, pragmas map[string]string) string
}
```

<a name="RegisteredDriver"></a>
### func [RegisteredDriver](<https://github.com/danmestas/libfossil/blob/main/db/register.go#L31>)

```go
func RegisteredDriver() *DriverConfig
```

RegisteredDriver returns a copy of the currently registered driver config, or nil if none.

<a name="OpenConfig"></a>
## type [OpenConfig](<https://github.com/danmestas/libfossil/blob/main/db/config.go#L4-L7>)

OpenConfig allows callers to customize driver selection and pragmas.

```go
type OpenConfig struct {
    Driver  string            // override driver name (empty = use registered driver)
    Pragmas map[string]string // additional/override pragmas (merged with defaults)
}
```

<a name="Querier"></a>
## type [Querier](<https://github.com/danmestas/libfossil/blob/main/db/querier.go#L8-L12>)

Querier is the common interface satisfied by both \*DB and \*Tx. Functions that need to work inside transactions accept Querier instead of \*DB.

```go
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)
}
```

<a name="Tx"></a>
## type [Tx](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L121-L123>)



```go
type Tx struct {
    // contains filtered or unexported fields
}
```

<a name="Tx.Exec"></a>
### func \(\*Tx\) [Exec](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L125>)

```go
func (t *Tx) Exec(query string, args ...any) (sql.Result, error)
```



<a name="Tx.Query"></a>
### func \(\*Tx\) [Query](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L133>)

```go
func (t *Tx) Query(query string, args ...any) (*sql.Rows, error)
```



<a name="Tx.QueryRow"></a>
### func \(\*Tx\) [QueryRow](<https://github.com/danmestas/libfossil/blob/main/db/db.go#L129>)

```go
func (t *Tx) QueryRow(query string, args ...any) *sql.Row
```



Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)