Artifact [146e923ea8]

Artifact 146e923ea84ae0990632a88a0a9843c0b87bee46ba0eb6e24063e5f089cedd6d:

• File docs/site/content/docs/reference/sdk/db/api.md — part of check-in [d1016bd2ef] at 2026-04-26 08:12:25 on branch trunk — site(landing): SVG architecture diagram + SDK refresh (#7)

  * site(landing): SVG architecture diagram + SDK regen

  - Replace §04 ASCII diagram with an SVG mirroring the dagnats style: three columns (callers / core / plugins), ember flow arrows with CALLS / DELEGATE / EVENTS / PERSIST labels, bottom box for .fossil (SQLite). Picks up the layout's existing .diagram CSS with no new styles. - Refresh gomarkdoc-generated SDK pages — they had drifted from current Go doc comments since the original generation.

  * docs(site): drop redundant body H1s from frontmatter pages

  Each of the four moved docs (architecture, extension-points, migration-from-fossil, testing) and the two hand-written driver _index pages had a body '# Title' that duplicated their frontmatter 'title:'. Hextra renders both, producing the visible doubled headline. Removing the body H1 leaves Hextra's frontmatter-driven page heading as the single source.

  SDK api.md pages from gomarkdoc are unaffected — they have no frontmatter, so Hextra promotes their body H1 to the page title without duplication.

  * site(landing): bump version refs to v0.4.2 (user: [email protected], size: 9882) [annotate] [blame] [check-ins using]

<!-- 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>)