bitcask

Documentation

Index

• Constants
• type DB
  • func Open(opts Options) (*DB, error)
  • func (db *DB) All(opts kvtypes.IterOptions) iter.Seq2[[]byte, []byte]
  • func (db *DB) Close() error
  • func (db *DB) Compact() error
  • func (db *DB) DecodeValue(raw []byte) ([]byte, bool)
  • func (db *DB) Delete(key []byte) error
  • func (db *DB) Get(key []byte) ([]byte, error)
  • func (db *DB) Has(key []byte) (bool, error)
  • func (db *DB) Iterator(opts kvtypes.IterOptions) *kvtypes.Iterator
  • func (db *DB) Put(key, value []byte) error
  • func (db *DB) Stats() Stats
  • func (db *DB) Sync() error
• type Options
  • func DefaultOptions(dir string) Options
• type Stats

Constants

const DefaultCompactionRatio = 0.5

DefaultCompactionRatio is the dead-byte fraction of a segment that triggers compaction.

const DefaultSegmentSize int64 = 64 << 20

DefaultSegmentSize is the rotation threshold for a new active segment file. 64MB keeps a single segment's mmap footprint, and a compaction pass over it, small relative to a constrained (e.g. 1GB RAM, 1 CPU) host, while keeping the number of segment files/mmap regions reasonable at multi-GB total data sizes.

const MaxKeyLen = math.MaxUint16

MaxKeyLen is the largest key size Put accepts, in bytes (the index stores key lengths as uint16).

Types

type DB

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

DB is an embedded, single-process key-value store: an append-only, memory-mapped segment log on disk plus a compact in-memory index (see index.go). See README for the full design rationale.

func Open

func Open(opts Options) (*DB, error)

Open opens (creating if necessary) a DB rooted at opts.Dir. See DefaultOptions for the recommended configuration.

func (*DB) All

func (db *DB) All(opts kvtypes.IterOptions) iter.Seq2[[]byte, []byte]

All returns an iterator over key/value pairs matching opts, for use with range-over-func. A read error silently ends the iteration early; use Iterator directly when errors must be distinguished from exhaustion.

func (*DB) Close

func (db *DB) Close() error

Close stops background compaction, optionally snapshots the index, and syncs/closes every segment. Safe to call once; a second call returns ErrClosed.

func (*DB) Compact

func (db *DB) Compact() error

Compact synchronously runs compaction passes until no segment remains above CompactionRatio, without waiting for the background ticker.

func (*DB) DecodeValue

func (db *DB) DecodeValue(raw []byte) ([]byte, bool)

DecodeValue satisfies kv.Store at the root: DB's Get/Iterator already yield bare values with no envelope, so this is the identity. Defined here (not as an alias-attached method at root, which Go doesn't allow on a type alias to another package's type) so *DB structurally satisfies kv.Store without kv needing any DB-specific adapter.

func (*DB) Delete

func (db *DB) Delete(key []byte) error

Delete removes key. Deleting an absent key is not an error.

func (*DB) Get

func (db *DB) Get(key []byte) ([]byte, error)

Get returns a copy of key's current value, or kvtypes.ErrNotFound.

func (*DB) Has

func (db *DB) Has(key []byte) (bool, error)

Has reports whether key currently has a live value.

func (*DB) Iterator

func (db *DB) Iterator(opts kvtypes.IterOptions) *kvtypes.Iterator

Iterator returns a new kvtypes.Iterator over keys matching opts.

func (*DB) Put

func (db *DB) Put(key, value []byte) error

Put inserts or overwrites key's value.

func (*DB) Stats

func (db *DB) Stats() Stats

Stats returns current size counters. Cheap: one read lock, no I/O.

func (*DB) Sync

func (db *DB) Sync() error

Sync fsyncs the active segment, making every previously written record durable. Only useful when SyncOnWrite is off (with it on, every Put/Delete already syncs).

type Options

type Options struct {
	// Dir is the directory holding segment files and the index snapshot.
	// Required.
	Dir string
	// SegmentSize is the byte size a segment is preallocated to before
	// rotating to a new one. Defaults to DefaultSegmentSize.
	SegmentSize int64
	// SyncOnWrite fsyncs the active segment after every Put/Delete.
	// Durable but slower; off by default (periodic/close-time sync only).
	SyncOnWrite bool
	// SnapshotOnClose writes an index checkpoint on a clean Close so the
	// next Open can skip re-scanning already-checkpointed segments.
	SnapshotOnClose bool
	// CompactionRatio is the dead-byte fraction (0-1) of an immutable
	// segment that marks it eligible for compaction. Defaults to
	// DefaultCompactionRatio.
	CompactionRatio float64
}

Options configures a DB. Zero-value numeric fields are replaced with defaults by Open; the two bool fields have no implicit default (a plain Options{Dir: "..."} literal leaves them false) — use DefaultOptions to get the recommended durability/maintenance posture instead of assuming a bare struct literal is fully configured.

func DefaultOptions

func DefaultOptions(dir string) Options

DefaultOptions returns the recommended configuration for dir: default segment size and compaction ratio, buffered (non-fsync-per-write) durability, and a snapshot written on clean Close.

type Stats

type Stats struct {
	// Keys is the number of live keys.
	Keys int
	// Segments is the number of open segment files, including the active
	// write segment and any compaction output segment.
	Segments int
	// DeadBytes is the total bytes superseded by later overwrites or
	// deletes, reclaimable by compaction.
	DeadBytes int64
	// LastCompactionErr is the error from the most recent compaction
	// pass (background or explicit Compact), nil if it succeeded. The
	// background compactor retries every tick, so a persistent non-nil
	// value here means dead bytes are accumulating unreclaimed.
	LastCompactionErr error
}

Stats is a point-in-time snapshot of the DB's size counters.