Open, Close, Flush & Stats

Open

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

Open resolves the path to an absolute filesystem directory, creates it if necessary, obtains the process lock, validates persisted metadata/tables, and recovers the WAL. It can checkpoint recovered memory state and reclaim obsolete files before returning.

Pass an explicit, dedicated directory. The implementation resolves paths with filepath.Abs; an empty path can resolve to the working directory. Validate your configuration rather than using an empty fallback. A database directory should not contain unrelated application JSON/log files.

Zero option fields select defaults. Existing records and WAL must fit the configured limits. The options are not persisted as application configuration: retain and reuse the values your deployment needs.

Do not infer that every open-time budget failure is returned as ErrLimit. In particular, an SSTable exceeding MaxDataBytes is wrapped by the current engine as ErrCorrupt; first compare the original configuration before deciding files are physically damaged.

There is no context parameter, read-only mode, lock-wait timeout, recovery bypass, or automatic file-format migration.

Close

func (db *DB) Close() error

The first call marks the handle closed while holding its exclusive mutex, syncs the WAL, closes files, and releases the OS lock. It attempts the remaining closes even if an earlier close/sync fails and joins errors.

A second call returns nil. Preserve the first close error; a later successful idempotent call does not mean the earlier sync succeeded. Reads/writes on a closed handle return ErrClosed subject to earlier argument/context checks.

Close does not force an SSTable flush. It syncs both durable and relaxed WAL writes. Stop and drain workers before closing; there is no shutdown coordinator inside the database.

func useDatabase() (err error) {
    db, err := zeedb.Open("./data", zeedb.Options{})
    if err != nil { return err }
    defer func() { err = errors.Join(err, db.Close()) }()
    // Use db here, and return application errors normally.
    return nil
}

Flush

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

Flush merges the memtable and existing SSTable into a new consolidated table, publishes a checkpoint, truncates the covered WAL, and reclaims obsolete generated files. Tombstones can be dropped because all older state is included.

It does not advance the commit sequence, create a backup, stop later writers, or establish a multi-call snapshot. A call with no new memtable state can reclaim a fully checkpointed old WAL left after a crash.

Readers and writers wait during flush. Context checks happen before entering persistent checkpoint work, not at every filesystem operation. A checkpoint I/O failure poisons the handle and can leave a new checkpoint published despite the error; reopen to reconcile.

Stats

func (db *DB) Stats() (Stats, error)

SSTable records may be shadowed or deleted by the memtable. After checkpointing, MemtableBytes is zero and the reclaimed WAL is normally 8 bytes.

Stats uses a shared lock and returns an error on closed/poisoned handles. It has no context parameter and reports no cache hit rate, disk-free space, latency histogram, or exact heap/RSS. See observability.