Go API

Package

import zeedb "github.com/Berlindraft/ZeeDB"

The root package is the embedded API. Method signatures below omit the zeedb qualifier for types declared in the same package.

For parameter/error/side-effect contracts, use the detailed references:

• Open, Close, Flush, and Stats.
• Put, Get, GetRecord, and Delete.
• WriteBatch encoding and commit contract.
• Scan ranges and limits, with pagination helpers.
• All CLI flags and output shapes.

Open and lifecycle

func Open(path string, options Options) (*DB, error)
func (db *DB) Close() error

Open creates or recovers the database and holds an exclusive process lock for its lifetime. Files must fit the configured budgets. Zero-valued options select defaults.

Close syncs the WAL in either durability mode, closes files, and releases the lock. It is idempotent and does not force an SSTable flush.

Record operations

func (db *DB) Put(ctx context.Context, collection string, key, value []byte) error
func (db *DB) Get(ctx context.Context, collection string, key []byte) ([]byte, error)
func (db *DB) GetRecord(ctx context.Context, collection string, key []byte) (Record, error)
func (db *DB) Delete(ctx context.Context, collection string, key []byte) error

Collections contain 1–255 bytes and no NUL. Keys are nonempty arbitrary bytes with lexicographic ordering. Values may be empty. Get and GetRecord return ErrNotFound for missing/deleted records. Delete is idempotent.

Atomic mutations

type Mutation struct {
    Collection string
    Key, Value []byte
    Delete     bool
}

func (db *DB) WriteBatch(ctx context.Context, mutations []Mutation) error

For Delete: true, Value must be empty. Repeated keys are allowed; the final mutation wins. A nonempty batch receives one version and one atomic visibility boundary.

Bounded scans

type Record struct {
    Key, Value []byte
    Version    uint64
}

type ScanOptions struct {
    Start, End []byte
    Limit      int
}

func (db *DB) Scan(ctx context.Context, collection string, options ScanOptions) ([]Record, error)

The range is [Start, End). Nil End is unbounded. Limit: 0 uses the configured maximum. Byte-budget overflow returns an error without partial results. See range scans.

Checkpoints and counters

func (db *DB) Flush(ctx context.Context) error
func (db *DB) Stats() (Stats, error)

type Stats struct {
    Sequence       uint64
    Records        int
    DataBytes      int64
    MemtableBytes  int64
    WALBytes       int64
    SSTableRecords int
}

Flush synchronously merges the memtable with the single existing SSTable. Readers and writers wait while checkpointing. A flush with no new records may reclaim an old WAL left after a checkpoint crash.

Stats returns current accounting counters under a shared lock. They do not report exact heap usage, RSS, or filesystem consumption. SSTableRecords can include records shadowed by the memtable until the next compaction.

Durability

type Durability uint8

const (
    Durable Durability = iota
    Relaxed
)

Durable is the zero value and default. Acknowledgement follows WAL sync. Relaxed skips per-commit sync and may lose acknowledged changes after a crash. Close syncs both modes.

There is no SQL API, read/write transaction callback, compare-and-swap, persistent snapshot handle, secondary-index API, or FastPath registration in this release.