Documentation
¶
Overview ¶
Package bolttable provides typed tables over a bbolt file: namespaces of tables with declared indexes, counters and cascades, a revision counter with a change feed, a per-namespace format digest with reset, and verification, statistics, online backup and offline compaction.
A Schema is declared once, usually through Must, and sealed by Open. Keys go through a KeyCodec, so their byte layout, and with it the scan order, is the caller's; values through a Codec, JSON by default. Every declaration that shapes stored bytes enters its namespace's digest, and Open refuses a file whose stored digests differ with a *FormatError.
A transaction that writes a non-silent table, Touches a subject or sets a Mark reserves the next revision and records one Change, which Since returns and OnCommit receives in revision order. Every slice the package returns or keeps is a copy.
Example ¶
package main
import (
"context"
"fmt"
"log"
"os"
"path/filepath"
"github.com/cplieger/bolttable"
)
type user struct {
Email string `json:"email"`
Admin bool `json:"admin"`
}
var (
schema = bolttable.NewSchema("app")
accounts = bolttable.Must(schema.Namespace("accounts"))
users = bolttable.Must(bolttable.Define(accounts, 0x01, "users",
bolttable.Uint64Key{}, bolttable.JSON[user](1), bolttable.TableOptions{}))
byEmail = bolttable.Must(bolttable.DefineIndex(users, "by_email",
bolttable.IndexOptions{Unique: true, Version: 1},
func(_ uint64, u *user) []bolttable.Entry { return []bolttable.Entry{{Key: []byte(u.Email)}} }))
admins = bolttable.Must(bolttable.DefineCounter(users, "admins", 1,
func(_ uint64, u *user) int64 {
if u.Admin {
return 1
}
return 0
}))
)
func main() {
dir, err := os.MkdirTemp("", "bolttable-example")
if err != nil {
log.Fatal(err)
}
defer func() { _ = os.RemoveAll(dir) }()
db, err := bolttable.Open(filepath.Join(dir, "app.bolt"), schema, bolttable.Options{
Retention: 1000,
OnCommit: func(c bolttable.Change) { fmt.Println("revision", c.Rev, "subjects", len(c.Subjects)) },
})
if err != nil {
log.Fatal(err)
}
defer func() { _ = db.Close() }()
ctx := context.Background()
err = db.Update(ctx, func(tx *bolttable.Tx) error {
id, err := users.NextID(tx)
if err != nil {
return err
}
return users.Put(tx, id, &user{Email: "ada@example.com", Admin: true})
})
if err != nil {
log.Fatal(err)
}
err = db.View(ctx, func(r *bolttable.ReadTx) error {
id, _, found, err := byEmail.Lookup(r, []byte("ada@example.com"))
if err != nil || !found {
return err
}
n, err := admins.Value(r)
fmt.Println("user", id, "admins", n)
return err
})
if err != nil {
log.Fatal(err)
}
}
Output: revision 1 subjects 1 user 1 admins 1
Index ¶
- Variables
- func CascadeIndex[PK, PV, CK, CV any](parent *Table[PK, PV], via *Index[CK, CV], version uint32, ...) error
- func CascadePrefix[PK, PV, CK, CV any](parent *Table[PK, PV], child *Table[CK, CV], version uint32, ...) error
- func CompactIfFree(path string, minFreeRatio float64, minFreeBytes int64) (bool, error)
- func Must[T any](v T, err error) T
- func ResetNamespaces(path string, s *Schema, names []string) error
- type BytesKey
- type Change
- type Codec
- type ConflictError
- type Counter
- type DB
- func (db *DB) Backup(ctx context.Context, path string) error
- func (db *DB) Batch(ctx context.Context, fn func(*Tx) error) error
- func (db *DB) Close() error
- func (db *DB) Epoch() [16]byte
- func (db *DB) Stats(ctx context.Context) (Stats, error)
- func (db *DB) Update(ctx context.Context, fn func(*Tx) error) error
- func (db *DB) Verify(ctx context.Context, repair bool) (VerifyReport, error)
- func (db *DB) View(ctx context.Context, fn func(*ReadTx) error) error
- type Entry
- type FormatError
- type Index
- type IndexOptions
- type KeyCodec
- type Mismatch
- type Namespace
- type NamespaceDigest
- type NamespaceStats
- type Options
- type Pending
- type Range
- type ReadTx
- type Schema
- type Stats
- type Subject
- type Table
- func (t *Table[K, V]) Delete(tx *Tx, k K) (bool, error)
- func (t *Table[K, V]) Get(r *ReadTx, k K) (v V, found bool, err error)
- func (t *Table[K, V]) NextID(tx *Tx) (uint64, error)
- func (t *Table[K, V]) Put(tx *Tx, k K, v *V) error
- func (t *Table[K, V]) Scan(r *ReadTx, rg Range, fn func(K, *V) (bool, error)) error
- func (t *Table[K, V]) Subject(k K) Subject
- type TableOptions
- type TableStats
- type Tx
- type Uint64Key
- type VerifyReport
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrFormat matches a *FormatError: the file's stored format differs from // the schema. ErrFormat = errors.New("bolttable: stored format differs from the schema") // ErrConflict matches a *ConflictError: a Put would give a unique index // key a second row. ErrConflict = errors.New("bolttable: unique index conflict") // ErrCorrupt reports stored bytes that do not decode. Its message names // the table or index and a fingerprint of the stored key, never key or // row bytes, and it drops the codec's own error, whose text may hold // them. ErrCorrupt = errors.New("bolttable: row does not decode") // ErrCommit wraps a failure of bbolt itself to begin or commit a // transaction, so a caller tells a storage fault from its own refusal. ErrCommit = errors.New("bolttable: commit failed") // ErrPublished reports that Backup linked a complete copy at its path, // then failed to remove its temporary name or to fsync the directory. ErrPublished = errors.New("bolttable: backup published, not made durable") )
Functions ¶
func CascadeIndex ¶
func CascadeIndex[PK, PV, CK, CV any](parent *Table[PK, PV], via *Index[CK, CV], version uint32, prefix func(PK) []byte) error
CascadeIndex makes deleting a parent row delete, in the same transaction, every row of via's table holding an entry of via whose index key starts with prefix(parent key), and recursively their own cascades. Parent and index share one namespace.
func CascadePrefix ¶
func CascadePrefix[PK, PV, CK, CV any](parent *Table[PK, PV], child *Table[CK, CV], version uint32, prefix func(PK) []byte) error
CascadePrefix makes deleting a parent row delete, in the same transaction, every child row whose encoded key starts with prefix(parent key), and recursively their own cascades. Parent and child share one namespace.
func CompactIfFree ¶
CompactIfFree rewrites the file at path without its free pages when they reach both minFreeRatio of the file and minFreeBytes, and reports whether it did. An absent path answers (false, nil). It runs before Open and needs the caller's exclusive access: bbolt's lock is a flock on the open file's inode (https://github.com/etcd-io/bbolt/blob/v1.5.0/bolt_unix.go#L32), so a process waiting in Open across the rename would acquire the old one. The copy is written to <path>.compact-tmp (a stale one is removed first), synced, and renamed over path, so a crash at any point leaves path whole.
func ResetNamespaces ¶
ResetNamespaces empties the named namespaces of the existing file at path, sealing s; pass it every name a *FormatError lists. It runs before Open and needs the caller's exclusive access. Each name must be stored or declared, or be "bolttable", which recreates the library's bucket (revision head and change log) at the current layout number. One bbolt transaction deletes the stored named buckets and recreates the declared ones, every table starting at the highest sequence its namespace stored, so NextID never reissues an id across a prefix move, a rename or a removed table.
Types ¶
type BytesKey ¶
type BytesKey struct{}
BytesKey stores a []byte key as is; Put refuses an empty one.
type Change ¶
Change is one committed revision: the subjects BeforeCommit returned (or the touched ones) and every mark.
type Codec ¶
type Codec[V any] interface { Version() uint32 Append(dst []byte, v *V) ([]byte, error) Decode(b []byte, v *V) error }
Codec encodes a table's values. Version enters the namespace's format digest, so an encoding change bumps it. Append must be deterministic: a Put whose encoding equals the stored bytes writes nothing. Decode receives a copy it may keep.
type ConflictError ¶
type ConflictError struct {
Index string
}
ConflictError names the unique index a Put collided on; errors.Is(err, ErrConflict) matches it. The transaction stays usable: the refused Put wrote nothing.
func (*ConflictError) Error ¶
func (e *ConflictError) Error() string
func (*ConflictError) Is ¶
func (*ConflictError) Is(target error) bool
Is reports whether target is ErrConflict.
type Counter ¶
type Counter[K, V any] struct { // contains filtered or unexported fields }
Counter keeps the sum of a weight over every row of its table, updated in the same transaction as the row.
func DefineCounter ¶
func DefineCounter[K, V any](t *Table[K, V], name string, version uint32, weight func(k K, v *V) int64) (*Counter[K, V], error)
DefineCounter declares a counter summing weight over the table's rows. It fails for a nil table or function, a zero version, a name already used in the namespace, and after Open.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is an open bolttable file.
func Open ¶
Open opens or creates the file at path, mode 0600, under s, sealing s. A file whose stored format differs from s fails with a *FormatError and is left byte-for-byte unchanged; only when nothing mismatches does Open create the namespaces the file lacks. Open fails when another process holds the file for 5 s.
func (*DB) Backup ¶
Backup writes a compacted copy of the file to path, mode 0600, from one read transaction while the database stays open. It walks into an exclusively created .<base>.bolttable-tmp beside path and publishes it with a hard link, which fails for any existing path, one created during the walk included. A failure before the link leaves no path and removes the temporary file, never one Backup did not create. After the link path is complete, and a failed removal of the temporary name or directory fsync wraps ErrPublished.
func (*DB) Batch ¶
Batch is Update through bbolt's grouped commit: concurrent calls share one transaction and fsync. fn may run more than once (bbolt reruns a group after one call fails, and the failed call alone: https://github.com/etcd-io/bbolt/blob/v1.5.0/db.go#L1024); only its last run's writes, change and AfterCommit functions survive. Each call keeps its own subjects, marks and revision.
func (*DB) Epoch ¶
Epoch returns the random identity of this open: a reader holding a revision from another epoch must resync.
func (*DB) Stats ¶
Stats reads the file's statistics in one read transaction, walking every table's pages.
func (*DB) Update ¶
Update runs fn in one bbolt read-write transaction. fn's error, or one from BeforeCommit, rolls it back and is returned as is; a failure of bbolt itself wraps ErrCommit. A context already done runs nothing.
func (*DB) Verify ¶
Verify rescans every table in one transaction and recomputes every index entry and counter. With repair it rewrites index entries and counters, and only those: it never rewrites or deletes a row, so an undecodable row stays reported with Repaired false, and its remedy is a restore. A repair writes no revision.
type Entry ¶
type Entry struct {
Key, Value []byte
}
Entry is one index entry a row produces. Key is the index key; Value is the projection a lookup or scan returns without reading the row.
type FormatError ¶
type FormatError struct {
Namespaces []NamespaceDigest
}
FormatError names every namespace whose stored format differs from the schema; errors.Is(err, ErrFormat) matches it. Every name it lists is one ResetNamespaces accepts.
func (*FormatError) Error ¶
func (e *FormatError) Error() string
func (*FormatError) Is ¶
func (*FormatError) Is(target error) bool
Is reports whether target is ErrFormat.
type Index ¶
type Index[K, V any] struct { // contains filtered or unexported fields }
Index is a declared index over a table. Each row maps to any number of entries: none makes the index sparse, several make it per-element.
func DefineIndex ¶
func DefineIndex[K, V any](t *Table[K, V], name string, o IndexOptions, entries func(k K, v *V) []Entry) (*Index[K, V], error)
DefineIndex declares an index whose entries entries computes from a row. It fails for a nil table or function, a zero version, a name already used in the namespace, and after Open.
func (*Index[K, V]) Lookup ¶
Lookup returns the row key and projection under a unique index key; found is false when no row has it. It fails on a non-unique index.
func (*Index[K, V]) Scan ¶
func (ix *Index[K, V]) Scan(r *ReadTx, rg Range, fn func(ikey []byte, k K, proj []byte) (bool, error)) error
Scan calls fn for each entry whose index key falls in rg, in index-key order, until fn returns false or an error. Range compares index keys, so a resumable scan needs an index key unique per row.
type IndexOptions ¶
IndexOptions configures an index. A Unique index gives each key at most one row. Version enters the namespace's format digest and must not be zero.
type KeyCodec ¶
type KeyCodec[K any] interface { Version() uint32 AppendKey(dst []byte, k K) []byte ParseKey(b []byte) (K, error) }
KeyCodec lays a table's keys out as bytes; the byte order is the order Scan visits. Version enters the namespace's format digest, so a layout change bumps it. ParseKey receives a copy it may keep.
type Mismatch ¶
Mismatch is one table, index or counter, named namespace.name, whose stored state differs from a rescan of its rows. For a table, Undecodable counts rows that do not decode; their index entries count as neither missing nor extra. For an index, Missing and Extra count entries. For a counter, a stored total differing from the exact sum of its rows' weights, or a sum outside int64, is one Missing and one Extra, and Undecodable counts rows its sum could not include, which leaves it unchecked.
type Namespace ¶
type Namespace struct {
// contains filtered or unexported fields
}
Namespace is one top-level bucket holding its tables, with its own format digest, so one namespace's format change never resets another's rows. Prefixes are unique across the schema, so a Subject stays prefix plus key.
type NamespaceDigest ¶
NamespaceDigest is one mismatched top-level bucket. A zero Want is a stored bucket the schema does not declare, or the library's own bucket; a zero Stored is a bucket holding no digest, or any bucket of a file whose layout is not this library's.
type NamespaceStats ¶
type NamespaceStats struct {
Name string
Tables []TableStats
Format [32]byte
}
NamespaceStats is one namespace's stored format digest and its tables.
type Options ¶
type Options struct {
// BeforeCommit runs once per revision-reserving transaction, before bbolt
// commits, and returns the subjects to record. It may write silent tables
// and add marks; a non-silent write or Touch fails the transaction, and
// its error rolls everything back.
BeforeCommit func(*Tx, *Pending) ([]Subject, error)
// OnCommit receives each committed change in revision order. It must not
// block: it runs under the lock that orders deliveries.
OnCommit func(Change)
// Retention is how many of the newest changes Since can return; it must
// not be negative.
Retention int
}
Options configures an open DB. The zero value records Touched as each change's subjects, delivers nothing and retains no change, so every Since below the head answers full.
type Pending ¶
Pending is the revision a transaction is about to commit, handed to BeforeCommit. Its slices are copies.
type Range ¶
Range selects the keys a Scan visits: those starting with Prefix, from From onward (inclusive; when Reverse, From is the inclusive upper bound), in byte order or, when Reverse, its reverse. Nil Prefix and From select every key.
type ReadTx ¶
type ReadTx struct {
// contains filtered or unexported fields
}
ReadTx reads one consistent snapshot. It is valid only inside the function View passed it to, or while its Tx is.
type Schema ¶
type Schema struct {
// contains filtered or unexported fields
}
Schema is the set of namespaces a file holds. Declarations build it before the first Open or ResetNamespaces; either seals it, and a declaration after that fails.
type Stats ¶
type Stats struct {
Namespaces []NamespaceStats
Rev uint64
Oldest uint64
Commits uint64
FileBytes int64
FreeBytes int64
}
Stats describes an open file. Rev and Oldest bound what Since returns. Commits counts every successful bbolt commit since Open: one per Batch group, and silent-only, byte-equal and empty writes too, since bbolt commits a meta page for each; failed and rolled-back transactions do not count (https://github.com/etcd-io/bbolt/blob/v1.5.0/tx.go#L267).
type Subject ¶
type Subject []byte
Subject names one row in the change feed: a table's prefix byte plus the encoded key.
type Table ¶
type Table[K, V any] struct { // contains filtered or unexported fields }
Table is a typed table declared in a namespace.
func Define ¶
func Define[K, V any](ns *Namespace, prefix byte, name string, k KeyCodec[K], v Codec[V], o TableOptions) (*Table[K, V], error)
Define declares a table under a prefix byte unique across the schema and a name unique in its namespace. It fails for a nil namespace or codec, a zero codec version, a duplicate prefix or name, and after Open.
func (*Table[K, V]) Delete ¶
Delete removes the row under k, its index entries and counter weights, and runs the table's cascades; it reports whether a row was there.
func (*Table[K, V]) Get ¶
Get returns the row under k; found is false for an absent row. A stored value that does not decode is ErrCorrupt.
func (*Table[K, V]) NextID ¶
NextID returns the table's next sequence number, starting at 1. It records no subject; on a non-silent table it fails the transaction inside BeforeCommit, as a write does. After ResetNamespaces it stays above every id the namespace issued before.
func (*Table[K, V]) Put ¶
Put stores v under k, updating every index and counter of the table in the same transaction. A value whose encoding equals the stored bytes writes nothing and records no subject. It fails with a *ConflictError when a unique index key belongs to another row, writing nothing; a counter leaving int64 fails it and the whole transaction.
type TableOptions ¶
type TableOptions struct {
Silent bool
}
TableOptions configures a table. A Silent table's writes reserve no revision, record no subject and never reach Since; a non-silent write inside BeforeCommit fails the transaction.
type TableStats ¶
TableStats is one table's row count and the bytes its pages use.
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx is a read-write transaction. It is valid only inside the function Update or Batch passed it to.
func (*Tx) AfterCommit ¶
func (tx *Tx) AfterCommit(fn func())
AfterCommit registers fn to run once after this transaction commits, never after a rollback or a discarded Batch run; for signals about silent writes.
func (*Tx) Mark ¶
Mark records a mark in this transaction's change; a transaction with a mark reserves a revision even when it wrote nothing.
type Uint64Key ¶
type Uint64Key struct{}
Uint64Key encodes a uint64 big-endian, so byte order is numeric order.
type VerifyReport ¶
type VerifyReport struct {
Mismatches []Mismatch
}
VerifyReport lists every mismatch Verify found.