vmbolt

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 22, 2026 License: MIT Imports: 15 Imported by: 0

README

vmbolt

vmbolt is a pure-memory key/value store — a fork of bbolt rebuilt around an in-memory node graph instead of an mmap'd file.

  • Module: github.com/13eholder/vmbolt · package: vmbolt
  • Top-level buckets stay flat and keep their own B+tree structure, but the database publishes one globally consistent view per transaction commit.
  • No on-disk persistence by default: the whole database lives in process memory. A snapshot can be written/read back on demand (BMSP format), but there is no per-commit fsync, no WAL, and no file lock.
  • The bbolt transaction/bucket/cursor API shape is preserved (Update, View, Batch, Bucket, Cursor, …), so existing call sites port with minimal changes.

vmbolt is for workloads that want bbolt's ACID transaction semantics and ordered B+tree access without a disk — caches, transient indexes, session stores, test doubles, or a non-durable etcd-like store. If you need durability across restarts, use upstream bbolt.


Table of contents


Install

go get github.com/13eholder/vmbolt@latest
import "github.com/13eholder/vmbolt"

db, err := vmbolt.Open("", 0600, nil) // path is ignored for storage
if err != nil {
	return err
}
defer db.Close()

Open(path, …) does not create or read a regular bbolt file. The path is kept only so that, if it happens to hold a BMSP snapshot, the database rehydrates from it on open; otherwise the DB starts empty.


Quick start

db, err := vmbolt.Open("", 0600, nil)
if err != nil { log.Fatal(err) }
defer db.Close()

// Write
err = db.Update(func(tx *vmbolt.Tx) error {
	bucket, err := tx.CreateBucketIfNotExists([]byte("MyBucket"))
	if err != nil { return err }
	return bucket.Put([]byte("answer"), []byte("42"))
})

// Read
_ = db.View(func(tx *vmbolt.Tx) error {
	v := tx.Bucket([]byte("MyBucket")).Get([]byte("answer"))
	fmt.Printf("The answer is: %s\n", v) // 42
	return nil
})

// Range scan
_ = db.View(func(tx *vmbolt.Tx) error {
	c := tx.Bucket([]byte("MyBucket")).Cursor()
	for k, v := c.Seek([]byte("a")); k != nil; k, v = c.Next() {
		fmt.Printf("%s = %s\n", k, v)
	}
	return nil
})

The model

Flat top-level buckets

The database is a directory of named top-level buckets held inside one published database state:

DB.state -> dbState{
  buckets map[string]*bucketState
  nextNid
  freeNid
}
  • Each top-level bucket remains its own B+tree.
  • A commit still rebuilds only the buckets it touched internally, but readers observe them through one globally published dbState, so a transaction sees one consistent database view across all buckets.
  • Writes use copy-on-write: a write transaction materializes mutable workNodes from the immutable snapNodes, mutates them, and on commit freezes them back into new immutable snapNodes (zero-copy inode transfer).
Global Nid allocator
  • Nid is a plain globally unique node id.
  • Nid allocation is database-wide, not bucket-scoped.
  • Freed node ids are recycled via a global LIFO freelist carried in dbState.
Read snapshot isolation

A read transaction pins the current dbState at Begin time and holds that global view for the transaction's lifetime. Reads are therefore consistent both within a bucket and across buckets.

Single writer

There is one global write lock (db.Update/Begin(true)). Commit is build-all-then-publish: touched buckets are rebuilt first, then one new dbState is atomically published, so a failed commit publishes nothing.


Snapshots & restore (BMSP)

vmbolt is non-durable, but it can serialize the whole database to a BMSP stream on demand and read it back:

// Save
_ = db.View(func(tx *vmbolt.Tx) error {
	return tx.CopyFile("/tmp/snap.bmsp", 0600) // or tx.WriteTo(w)
})

// Restore into a fresh DB
db2, _ := vmbolt.Open("/tmp/snap.bmsp", 0600, nil) // Open auto-restores a BMSP file
// or explicitly: db2.Restore(file)

BMSP is a compact, fully-ordered, streaming format (buckets in sorted name order via Tx.Cursor, keys sorted within each bucket), so a snapshot is deterministic — saving and restoring produces a byte-identical tree. Snapshots are written only when you ask (WriteTo/CopyFile); there is no background persistence. Between snapshots, data is volatile.


API reference

Database:

Method Notes
Open(path, mode, opts) Open (empty) or rehydrate from a BMSP file at path
Close() Release resources
Update(fn) / View(fn) / Batch(fn) Managed read-write / read-only / batched tx
Begin(writable) Manual transaction (remember to Commit/Rollback)
Restore(r) Rehydrate from a BMSP reader
Stats(), Info(), Logger() Diagnostics

Transaction:

Method Notes
Bucket(name) Open a top-level bucket (nil if absent)
CreateBucket / CreateBucketIfNotExists / DeleteBucket Bucket lifecycle
ForEach(fn) Iterate top-level buckets (unordered — map iteration)
Cursor() Sorted cursor over top-level bucket names (deterministic)
Size() Whole-DB logical size estimate
WriteTo(w) / Copy(w) / CopyFile(path, mode) Emit a BMSP snapshot
OnCommit(fn) Post-commit hook

Bucket:

Method Notes
Put / Get / Delete Key/value ops
ForEach(fn) / Cursor() Sorted iteration / point lookup
Stats() Per-bucket statistics

Differences from bbolt

Removed (disk-era machinery the pure-memory engine does not need):

  • mmap'd file, fdatasync/msync, WAL, file lock, Mlock, grow.
  • The on-disk freelist package; allocation is a global monotonic counter + LIFO recycle.
  • The cmd/bbolt CLI and the internal/{surgeon,guts_cli,freelist,tests} + tests/* disk tooling.
  • Nested buckets — only flat top-level buckets are supported.
  • Disk-oriented Options fields (NoSync, MmapFlags, InitialMmapSize, FreelistType, Mlock, Timeout, …) and DB.Sync/grow/loadFreelist.
  • Tx.Page (removed); Tx.Check is retained as a no-op stub that returns no errors.

Added:

  • Global in-memory publication via dbState, global Nid recycling.
  • BMSP snapshot format + Open auto-restore.
  • Tx.Cursor() over sorted top-level bucket names.

Caveats & limitations

  • Volatile by design. A process crash/exit loses everything not captured in a snapshot. vmbolt is not a replacement for a durable store.
  • Single writer. One write transaction at a time (global lock). Reads are concurrent with the writer.
  • Flat top-level buckets only. Nested bucket APIs were removed.
  • Byte slices from Get/Cursor are valid only for the transaction's lifetime (they reference shared immutable storage). Copy them if you need them beyond the tx.
  • Tx.Check is a no-op stub (returns no errors).

etcd backend notes

vmbolt's API was shaped with etcd's backend package in mind (etcd uses only flat top-level buckets, never nested). The pieces etcd depends on are present:

  • sorted Tx.Cursor() (deterministic Hash/snapshot),
  • Tx.WriteTo/snapshot streaming (BMSP),
  • Tx.Size(),
  • one globally consistent transaction view, so meta + key advance together.

The fundamental gap is durability: etcd requires a durable, recoverable backend, while vmbolt is memory-only (snapshot-on-demand, volatile between snapshots). vmbolt can serve as a non-durable / in-memory etcd (testing, caching, ephemeral sidecars), not as a drop-in for production etcd storage.

Documentation

Index

Examples

Constants

View Source
const (
	// MaxKeySize is the maximum length of a key, in bytes.
	MaxKeySize = 32768

	// MaxValueSize is the maximum length of a value, in bytes.
	MaxValueSize = (1 << 31) - 2
)
View Source
const DefaultFillPercent = 0.5

DefaultFillPercent is the percentage that split nodes are filled.

Variables

View Source
var (
	// ErrDatabaseNotOpen is returned when a DB instance is accessed before it
	// is opened or after it is closed.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrDatabaseNotOpen = errors.ErrDatabaseNotOpen

	// ErrInvalid is returned when both meta pages on a database are invalid.
	// This typically occurs when a file is not a bolt database.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrInvalid = errors.ErrInvalid

	// ErrInvalidMapping is returned when the database file fails to get mapped.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrInvalidMapping = errors.ErrInvalidMapping

	// ErrVersionMismatch is returned when the data file was created with a
	// different version of Bolt.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrVersionMismatch = errors.ErrVersionMismatch

	// ErrChecksum is returned when a checksum mismatch occurs on either of the two meta pages.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrChecksum = errors.ErrChecksum

	// ErrTimeout is returned when a database cannot obtain an exclusive lock
	// on the data file after the timeout passed to Open().
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrTimeout = errors.ErrTimeout
)

These errors can be returned when opening or calling methods on a DB.

View Source
var (
	// ErrTxNotWritable is returned when performing a write operation on a
	// read-only transaction.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrTxNotWritable = errors.ErrTxNotWritable

	// ErrTxClosed is returned when committing or rolling back a transaction
	// that has already been committed or rolled back.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrTxClosed = errors.ErrTxClosed

	// ErrDatabaseReadOnly is returned when a mutating transaction is started on a
	// read-only database.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrDatabaseReadOnly = errors.ErrDatabaseReadOnly
)

These errors can occur when beginning or committing a Tx.

View Source
var (
	// ErrBucketNotFound is returned when trying to access a bucket that has
	// not been created yet.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrBucketNotFound = errors.ErrBucketNotFound

	// ErrBucketExists is returned when creating a bucket that already exists.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrBucketExists = errors.ErrBucketExists

	// ErrBucketNameRequired is returned when creating a bucket with a blank name.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrBucketNameRequired = errors.ErrBucketNameRequired

	// ErrKeyRequired is returned when inserting a zero-length key.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrKeyRequired = errors.ErrKeyRequired

	// ErrKeyTooLarge is returned when inserting a key that is larger than MaxKeySize.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrKeyTooLarge = errors.ErrKeyTooLarge

	// ErrValueTooLarge is returned when inserting a value that is larger than MaxValueSize.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrValueTooLarge = errors.ErrValueTooLarge

	// ErrIncompatibleValue is returned when trying create or delete a bucket
	// on an existing non-bucket key or when trying to create or delete a
	// non-bucket key on an existing bucket key.
	//
	// Deprecated: Use the error variables defined in the vmbolt/errors package.
	ErrIncompatibleValue = errors.ErrIncompatibleValue
)

These errors can occur when putting or deleting a value or a bucket.

View Source
var DefaultOptions = &Options{}

DefaultOptions represent the options used if nil options are passed into Open().

Functions

This section is empty.

Types

type Bucket

type Bucket struct {

	// FillPercent sets the threshold for filling nodes when they split. It is
	// non-persisted and must be set per tx.
	FillPercent float64
	// contains filtered or unexported fields
}

Bucket is a tx-local handle to one top-level B+tree. A Bucket is never shared across transactions.

func (*Bucket) Cursor

func (b *Bucket) Cursor() *Cursor

Cursor creates a cursor associated with the bucket.

func (*Bucket) Delete

func (b *Bucket) Delete(key []byte) (err error)

Delete removes a key from the bucket.

Example
// Open the database.
db, err := bolt.Open(tempfile(), 0600, nil)
if err != nil {
	log.Fatal(err)
}

// Start a write transaction.
if err := db.Update(func(tx *bolt.Tx) error {
	// Create a bucket.
	b, err := tx.CreateBucket([]byte("widgets"))
	if err != nil {
		return err
	}

	// Set the value "bar" for the key "foo".
	if err := b.Put([]byte("foo"), []byte("bar")); err != nil {
		return err
	}

	// Retrieve the key back from the database and verify it.
	value := b.Get([]byte("foo"))
	fmt.Printf("The value of 'foo' was: %s\n", value)

	return nil
}); err != nil {
	log.Fatal(err)
}

// Delete the key in a different write transaction.
if err := db.Update(func(tx *bolt.Tx) error {
	return tx.Bucket([]byte("widgets")).Delete([]byte("foo"))
}); err != nil {
	log.Fatal(err)
}

// Retrieve the key again.
if err := db.View(func(tx *bolt.Tx) error {
	value := tx.Bucket([]byte("widgets")).Get([]byte("foo"))
	if value == nil {
		fmt.Printf("The value of 'foo' is now: nil\n")
	}
	return nil
}); err != nil {
	log.Fatal(err)
}

// Close database to release file lock.
if err := db.Close(); err != nil {
	log.Fatal(err)
}
Output:
The value of 'foo' was: bar
The value of 'foo' is now: nil

func (*Bucket) ForEach

func (b *Bucket) ForEach(fn func(k, v []byte) error) error

ForEach executes a function for each key/value pair in a bucket.

Example
// Open the database.
db, err := bolt.Open(tempfile(), 0600, nil)
if err != nil {
	log.Fatal(err)
}

// Insert data into a bucket.
if err := db.Update(func(tx *bolt.Tx) error {
	b, err := tx.CreateBucket([]byte("animals"))
	if err != nil {
		return err
	}

	if err := b.Put([]byte("dog"), []byte("fun")); err != nil {
		return err
	}
	if err := b.Put([]byte("cat"), []byte("lame")); err != nil {
		return err
	}
	if err := b.Put([]byte("liger"), []byte("awesome")); err != nil {
		return err
	}

	// Iterate over items in sorted key order.
	if err := b.ForEach(func(k, v []byte) error {
		fmt.Printf("A %s is %s.\n", k, v)
		return nil
	}); err != nil {
		return err
	}

	return nil
}); err != nil {
	log.Fatal(err)
}

// Close database to release file lock.
if err := db.Close(); err != nil {
	log.Fatal(err)
}
Output:
A cat is lame.
A dog is fun.
A liger is awesome.

func (*Bucket) Get

func (b *Bucket) Get(key []byte) []byte

Get retrieves the value for a key in the bucket.

func (*Bucket) Inspect

func (b *Bucket) Inspect() BucketStructure

Inspect returns the structure of the bucket.

func (*Bucket) Name

func (b *Bucket) Name() string

Name returns the bucket's name.

func (*Bucket) Put

func (b *Bucket) Put(key []byte, value []byte) (err error)

Put sets the value for a key in the bucket.

Example
// Open the database.
db, err := bolt.Open(tempfile(), 0600, nil)
if err != nil {
	log.Fatal(err)
}

// Start a write transaction.
if err := db.Update(func(tx *bolt.Tx) error {
	// Create a bucket.
	b, err := tx.CreateBucket([]byte("widgets"))
	if err != nil {
		return err
	}

	// Set the value "bar" for the key "foo".
	if err := b.Put([]byte("foo"), []byte("bar")); err != nil {
		return err
	}
	return nil
}); err != nil {
	log.Fatal(err)
}

// Read value back in a different read-only transaction.
if err := db.View(func(tx *bolt.Tx) error {
	value := tx.Bucket([]byte("widgets")).Get([]byte("foo"))
	fmt.Printf("The value of 'foo' is: %s\n", value)
	return nil
}); err != nil {
	log.Fatal(err)
}

// Close database to release file lock.
if err := db.Close(); err != nil {
	log.Fatal(err)
}
Output:
The value of 'foo' is: bar

func (*Bucket) Root

func (b *Bucket) Root() common.Nid

Root returns the Nid of the bucket's root node. Returns 0 if the bucket has no committed root and none has been materialized yet.

func (*Bucket) Stats

func (b *Bucket) Stats() BucketStats

Stats returns stats on a bucket.

func (*Bucket) Tx

func (b *Bucket) Tx() *Tx

Tx returns the tx of the bucket.

func (*Bucket) Writable

func (b *Bucket) Writable() bool

Writable returns whether the bucket is writable.

type BucketStats

type BucketStats struct {
	// Tree statistics.
	KeyN  int // number of keys/value pairs
	Depth int // number of levels in B+tree

	// Page size utilization.
	BranchInuse int // bytes actually used for branch data
	LeafInuse   int // bytes actually used for leaf data
}

BucketStats records statistics about resources used by a bucket.

func (*BucketStats) Add

func (s *BucketStats) Add(other BucketStats)

type BucketStructure

type BucketStructure struct {
	Name     string            `json:"name"`
	KeyN     int               `json:"keyN"`
	Children []BucketStructure `json:"buckets,omitempty"`
}

BucketStructure records the structure of a bucket.

type CheckOption

type CheckOption func(options *checkConfig)

CheckOption configures Tx.Check.

func WithKVStringer

func WithKVStringer(kvStringer KVStringer) CheckOption

WithKVStringer sets a human-readable renderer for keys/values in error messages.

func WithPageId

func WithPageId(pageId uint64) CheckOption

WithPageId is retained for API compatibility; it is a no-op in the page-less engine.

type Cursor

type Cursor struct {
	// contains filtered or unexported fields
}

Cursor represents an iterator that can traverse over all key/value pairs in a bucket in lexicographical order.

It has two modes:

  • tree mode (bucket != nil): walks a single bucket's B+tree (via Bucket.Cursor());
  • directory mode (bucket == nil, dir set): enumerates the top-level bucket NAMES in sorted order. Produced by Tx.Cursor(); used by snapshot/Hash/defrag-style callers that iterate all top-level buckets deterministically.
Example
// Open the database.
db, err := bolt.Open(tempfile(), 0600, nil)
if err != nil {
	log.Fatal(err)
}

// Start a read-write transaction.
if err := db.Update(func(tx *bolt.Tx) error {
	// Create a new bucket.
	b, err := tx.CreateBucket([]byte("animals"))
	if err != nil {
		return err
	}

	// Insert data into a bucket.
	if err := b.Put([]byte("dog"), []byte("fun")); err != nil {
		log.Fatal(err)
	}
	if err := b.Put([]byte("cat"), []byte("lame")); err != nil {
		log.Fatal(err)
	}
	if err := b.Put([]byte("liger"), []byte("awesome")); err != nil {
		log.Fatal(err)
	}

	// Create a cursor for iteration.
	c := b.Cursor()

	// Iterate over items in sorted key order. This starts from the
	// first key/value pair and updates the k/v variables to the
	// next key/value on each iteration.
	//
	// The loop finishes at the end of the cursor when a nil key is returned.
	for k, v := c.First(); k != nil; k, v = c.Next() {
		fmt.Printf("A %s is %s.\n", k, v)
	}

	return nil
}); err != nil {
	log.Fatal(err)
}

if err := db.Close(); err != nil {
	log.Fatal(err)
}
Output:
A cat is lame.
A dog is fun.
A liger is awesome.
Example (Reverse)
// Open the database.
db, err := bolt.Open(tempfile(), 0600, nil)
if err != nil {
	log.Fatal(err)
}

// Start a read-write transaction.
if err := db.Update(func(tx *bolt.Tx) error {
	// Create a new bucket.
	b, err := tx.CreateBucket([]byte("animals"))
	if err != nil {
		return err
	}

	// Insert data into a bucket.
	if err := b.Put([]byte("dog"), []byte("fun")); err != nil {
		log.Fatal(err)
	}
	if err := b.Put([]byte("cat"), []byte("lame")); err != nil {
		log.Fatal(err)
	}
	if err := b.Put([]byte("liger"), []byte("awesome")); err != nil {
		log.Fatal(err)
	}

	// Create a cursor for iteration.
	c := b.Cursor()

	// Iterate over items in reverse sorted key order. This starts
	// from the last key/value pair and updates the k/v variables to
	// the previous key/value on each iteration.
	//
	// The loop finishes at the beginning of the cursor when a nil key
	// is returned.
	for k, v := c.Last(); k != nil; k, v = c.Prev() {
		fmt.Printf("A %s is %s.\n", k, v)
	}

	return nil
}); err != nil {
	log.Fatal(err)
}

// Close the database to release the file lock.
if err := db.Close(); err != nil {
	log.Fatal(err)
}
Output:
A liger is awesome.
A dog is fun.
A cat is lame.

func (*Cursor) Bucket

func (c *Cursor) Bucket() *Bucket

Bucket returns the bucket that this cursor was created from. Returns nil for a directory cursor (Tx.Cursor()).

func (*Cursor) Delete

func (c *Cursor) Delete() error

Delete removes the current key/value under the cursor from the bucket.

func (*Cursor) First

func (c *Cursor) First() (key []byte, value []byte)

First moves the cursor to the first item in the bucket and returns its key and value.

func (*Cursor) Last

func (c *Cursor) Last() (key []byte, value []byte)

Last moves the cursor to the last item in the bucket and returns its key and value.

func (*Cursor) Next

func (c *Cursor) Next() (key []byte, value []byte)

Next moves the cursor to the next item in the bucket and returns its key and value.

func (*Cursor) Prev

func (c *Cursor) Prev() (key []byte, value []byte)

Prev moves the cursor to the previous item in the bucket and returns its key and value.

func (*Cursor) Seek

func (c *Cursor) Seek(seek []byte) (key []byte, value []byte)

Seek moves the cursor to a given key using a b-tree search and returns it.

type DB

type DB struct {
	// MaxBatchSize is the maximum size of a batch. Default value is
	// copied from DefaultMaxBatchSize in Open.
	//
	// If <=0, disables batching.
	//
	// Do not change concurrently with calls to Batch.
	MaxBatchSize int

	// MaxBatchDelay is the maximum delay before a batch starts.
	// Default value is copied from DefaultMaxBatchDelay in Open.
	//
	// If <=0, effectively disables batching.
	//
	// Do not change concurrently with calls to Batch.
	MaxBatchDelay time.Duration
	// contains filtered or unexported fields
}

DB represents a collection of top-level buckets held in memory. All data access is performed through transactions which can be obtained through the DB. All the functions on DB will return a ErrDatabaseNotOpen if accessed before Open() is called.

func Open

func Open(path string, mode os.FileMode, options *Options) (db *DB, err error)

Open creates and opens a database at the given path with a given file mode. If the file does not exist then it will be created automatically with a given file mode. Passing in nil options will cause Bolt to open the database with the default options.

func (*DB) Batch

func (db *DB) Batch(fn func(*Tx) error) error

Batch calls fn as part of a batch. It behaves similar to Update, except concurrent Batch calls can be combined into a single Bolt transaction.

func (*DB) Begin

func (db *DB) Begin(writable bool) (t *Tx, err error)

Begin starts a new transaction.

func (*DB) Close

func (db *DB) Close() error

Close releases all database resources.

func (*DB) GoString

func (db *DB) GoString() string

GoString returns the Go string representation of the database.

func (*DB) Info

func (db *DB) Info() *Info

Info returns information about the database.

func (*DB) IsReadOnly

func (db *DB) IsReadOnly() bool

func (*DB) Logger

func (db *DB) Logger() Logger

func (*DB) Restore

func (db *DB) Restore(r io.Reader) error

Restore reads a BMSP snapshot from r and rebuilds the database in memory. It must be called on a fresh/empty DB (e.g. right after Open). No durability is added: the snapshot is a bulk rehydration, not incremental persistence.

func (*DB) Stats

func (db *DB) Stats() Stats

Stats retrieves ongoing performance stats for the database.

func (*DB) String

func (db *DB) String() string

String returns the string representation of the database.

func (*DB) Update

func (db *DB) Update(fn func(*Tx) error) error

Update executes a function within the context of a read-write managed transaction.

func (*DB) View

func (db *DB) View(fn func(*Tx) error) error

View executes a function within the context of a managed read-only transaction.

type DefaultLogger

type DefaultLogger struct {
	*log.Logger
	// contains filtered or unexported fields
}

DefaultLogger is a default implementation of the Logger interface.

func (*DefaultLogger) Debug

func (l *DefaultLogger) Debug(v ...interface{})

func (*DefaultLogger) Debugf

func (l *DefaultLogger) Debugf(format string, v ...interface{})

func (*DefaultLogger) EnableDebug

func (l *DefaultLogger) EnableDebug()

func (*DefaultLogger) EnableTimestamps

func (l *DefaultLogger) EnableTimestamps()

func (*DefaultLogger) Error

func (l *DefaultLogger) Error(v ...interface{})

func (*DefaultLogger) Errorf

func (l *DefaultLogger) Errorf(format string, v ...interface{})

func (*DefaultLogger) Fatal

func (l *DefaultLogger) Fatal(v ...interface{})

func (*DefaultLogger) Fatalf

func (l *DefaultLogger) Fatalf(format string, v ...interface{})

func (*DefaultLogger) Info

func (l *DefaultLogger) Info(v ...interface{})

func (*DefaultLogger) Infof

func (l *DefaultLogger) Infof(format string, v ...interface{})

func (*DefaultLogger) Panic

func (l *DefaultLogger) Panic(v ...interface{})

func (*DefaultLogger) Panicf

func (l *DefaultLogger) Panicf(format string, v ...interface{})

func (*DefaultLogger) Warning

func (l *DefaultLogger) Warning(v ...interface{})

func (*DefaultLogger) Warningf

func (l *DefaultLogger) Warningf(format string, v ...interface{})

type Info

type Info struct {
	Data uintptr
}

type KVStringer

type KVStringer interface {
	KeyToString([]byte) string
	ValueToString([]byte) string
}

KVStringer renders keys/values for human-readable diagnostic messages.

func HexKVStringer

func HexKVStringer() KVStringer

HexKVStringer serializes both key & value to hex representation.

type Logger

type Logger interface {
	Debug(v ...interface{})
	Debugf(format string, v ...interface{})

	Error(v ...interface{})
	Errorf(format string, v ...interface{})

	Info(v ...interface{})
	Infof(format string, v ...interface{})

	Warning(v ...interface{})
	Warningf(format string, v ...interface{})

	Fatal(v ...interface{})
	Fatalf(format string, v ...interface{})

	Panic(v ...interface{})
	Panicf(format string, v ...interface{})
}

type Options

type Options struct {
	// ReadOnly opens the database in read-only mode.
	ReadOnly bool

	// Logger is the logger used for vmbolt.
	Logger Logger

	// NoStatistics turns off statistics collection.
	NoStatistics bool
}

Options represents the options that can be set when opening a database.

func (*Options) String

func (o *Options) String() string

type Stats

type Stats struct {
	// Put `TxStats` at the first field to ensure it's 64-bit aligned.
	TxStats TxStats // global, ongoing stats.

	// Transaction stats
	TxN     int // total number of started read transactions
	OpenTxN int // number of currently open read transactions
}

Stats represents statistics about the database.

func (*Stats) Sub

func (s *Stats) Sub(other *Stats) Stats

Sub calculates and returns the difference between two sets of database stats.

type Tx

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

Tx represents a read-only or read/write transaction on the database.

Every transaction pins one globally consistent dbState at Begin time. A write tx mutates tx-local buckets and publishes one new dbState atomically at commit.

func (*Tx) Bucket

func (tx *Tx) Bucket(name []byte) *Bucket

Bucket retrieves a top-level bucket by name, opening a tx-local context for it.

func (*Tx) Check

func (tx *Tx) Check(options ...CheckOption) <-chan error

Check performs structural consistency validation of the committed database snapshot pinned by this transaction (tx.base). It is the page-less analogue of bbolt's tx.Check: instead of validating physical pages it validates the immutable in-memory node graph.

Every detected inconsistency is streamed on the returned channel; the channel is closed when validation completes. A well-formed database yields no errors.

Concurrent calls on the same transaction are safe: the published snapshot is immutable, so each Check call walks it independently without locks.

Options: WithKVStringer customizes key/value rendering in error messages; WithPageId is accepted for API compatibility but is a no-op (the engine is page-less).

Scope: only the committed snapshot the transaction pinned is validated. Uncommitted, in-flight write-transaction mutations are NOT validated.

func (*Tx) Commit

func (tx *Tx) Commit() (err error)

Commit publishes one new globally consistent state.

func (*Tx) Copy

func (tx *Tx) Copy(w errorWriter) error

Copy writes the entire database to a writer as a BMSP snapshot (see snapshot.go).

func (*Tx) CopyFile

func (tx *Tx) CopyFile(path string, mode os.FileMode) error

CopyFile writes the entire database to a file at path as a BMSP snapshot.

func (*Tx) CreateBucket

func (tx *Tx) CreateBucket(name []byte) (*Bucket, error)

CreateBucket creates a new top-level bucket and returns a tx-local handle to it.

func (*Tx) CreateBucketIfNotExists

func (tx *Tx) CreateBucketIfNotExists(name []byte) (*Bucket, error)

CreateBucketIfNotExists creates a new bucket if it doesn't already exist.

func (*Tx) Cursor

func (tx *Tx) Cursor() *Cursor

Cursor returns a directory cursor over the top-level bucket names in sorted order.

func (*Tx) DB

func (tx *Tx) DB() *DB

DB returns a reference to the database that created the transaction.

func (*Tx) DeleteBucket

func (tx *Tx) DeleteBucket(name []byte) error

DeleteBucket deletes a top-level bucket.

func (*Tx) ForEach

func (tx *Tx) ForEach(fn func(name []byte, b *Bucket) error) error

ForEach executes a function for each top-level bucket.

func (*Tx) Inspect

func (tx *Tx) Inspect() BucketStructure

Inspect returns the structure of the database: a synthetic "root" whose children are the top-level buckets.

func (*Tx) OnCommit

func (tx *Tx) OnCommit(fn func())

OnCommit adds a handler function to be executed after the transaction successfully commits.

func (*Tx) Rollback

func (tx *Tx) Rollback() error

Rollback closes the transaction and ignores all previous updates.

func (*Tx) Size

func (tx *Tx) Size() int64

Size returns the logical payload size of the whole database view in bytes.

func (*Tx) Stats

func (tx *Tx) Stats() TxStats

Stats retrieves a copy of the current transaction statistics.

func (*Tx) Writable

func (tx *Tx) Writable() bool

Writable returns whether the transaction can perform write operations.

func (*Tx) WriteTo

func (tx *Tx) WriteTo(w errorWriter) (n int64, err error)

WriteTo writes the entire database to a writer as a BMSP snapshot.

type TxStats

type TxStats struct {
	CursorCount   int64
	NodeCount     int64
	NodeDeref     int64
	Rebalance     int64
	RebalanceTime time.Duration
	Split         int64
	Spill         int64
	SpillTime     time.Duration
	Write         int64
	WriteTime     time.Duration
}

TxStats represents statistics about the actions performed by the transaction.

func (*TxStats) GetCursorCount

func (s *TxStats) GetCursorCount() int64

func (*TxStats) GetNodeCount

func (s *TxStats) GetNodeCount() int64

func (*TxStats) GetNodeDeref

func (s *TxStats) GetNodeDeref() int64

func (*TxStats) GetRebalance

func (s *TxStats) GetRebalance() int64

func (*TxStats) GetRebalanceTime

func (s *TxStats) GetRebalanceTime() time.Duration

func (*TxStats) GetSpill

func (s *TxStats) GetSpill() int64

func (*TxStats) GetSpillTime

func (s *TxStats) GetSpillTime() time.Duration

func (*TxStats) GetSplit

func (s *TxStats) GetSplit() int64

func (*TxStats) GetWrite

func (s *TxStats) GetWrite() int64

func (*TxStats) GetWriteTime

func (s *TxStats) GetWriteTime() time.Duration

func (*TxStats) IncCursorCount

func (s *TxStats) IncCursorCount(delta int64) int64

func (*TxStats) IncNodeCount

func (s *TxStats) IncNodeCount(delta int64) int64

func (*TxStats) IncNodeDeref

func (s *TxStats) IncNodeDeref(delta int64) int64

func (*TxStats) IncRebalance

func (s *TxStats) IncRebalance(delta int64) int64

func (*TxStats) IncRebalanceTime

func (s *TxStats) IncRebalanceTime(delta time.Duration) time.Duration

func (*TxStats) IncSpill

func (s *TxStats) IncSpill(delta int64) int64

func (*TxStats) IncSpillTime

func (s *TxStats) IncSpillTime(delta time.Duration) time.Duration

func (*TxStats) IncSplit

func (s *TxStats) IncSplit(delta int64) int64

func (*TxStats) IncWrite

func (s *TxStats) IncWrite(delta int64) int64

func (*TxStats) IncWriteTime

func (s *TxStats) IncWriteTime(delta time.Duration) time.Duration

func (*TxStats) Sub

func (s *TxStats) Sub(other *TxStats) TxStats

Sub calculates and returns the difference between two sets of transaction stats.

Directories

Path Synopsis
Package errors defines the error variables that may be returned during vmbolt operations.
Package errors defines the error variables that may be returned during vmbolt operations.
internal
common
Copied from https://github.com/etcd-io/etcd/blob/main/client/pkg/verify/verify.go
Copied from https://github.com/etcd-io/etcd/blob/main/client/pkg/verify/verify.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL