Record method contracts

Shared argument rules

• Pass a non-nil context.Context to context-aware methods.
• Collections must contain 1–255 bytes and no NUL.
• Keys must be nonempty and fit MaxKeyBytes; they may contain arbitrary bytes.
• Values may be empty and must fit both value and encoded-batch budgets.
• Inputs must not be mutated concurrently while the call reads them. Writes copy input bytes into owned records.

These are collection/key operations, not document-field queries. No method interprets a value as JSON automatically.

Put

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

Creates or fully replaces a record through a single-mutation batch. It is not a patch, insert-if-absent, upsert with a predicate, or expected-version write.

The successful write advances one commit sequence even if the bytes equal the previous value. An empty value remains a live record.

Validation includes collection/key/value size, encoded payload, final live-data budget, and memtable fit. A write may trigger a synchronous checkpoint before its own WAL append, affecting latency and errors.

For invalid input or a quota failure before append, the mutation is not committed. A write/checkpoint I/O failure is indeterminate and poisons the handle. See error handling.

Get

func (db *DB) Get(ctx context.Context, collection string, key []byte) ([]byte, error)

Returns an owned copy of the current live value. It is implemented through GetRecord and discards the returned version/key. On a missing/deleted record it returns ErrNotFound; do not infer absence from a zero-length value.

Memory hits read the active record; table hits read and revalidate one checksummed block. MaxScanBytes does not apply to point reads, although stored values are constrained by value/data limits.

You may modify the returned slice without modifying storage. A later mutation does not change the returned copy.

GetRecord

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

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

Returns caller-owned key/value copies and the record’s commit sequence. It does not include the collection name or a tombstone field because the request supplies the collection and deleted records are absent.

All records from one batch share a version. The number is database-wide and not an automatically enforced optimistic-lock token. No PutIfVersion method exists.

Delete

func (db *DB) Delete(ctx context.Context, collection string, key []byte) error

Publishes a tombstone through a single-mutation batch. It is idempotent with respect to visible data: a missing key remains missing. Repeated deletes can still advance the commit sequence and consume WAL/memtable space until checkpointing.

There is no return value indicating whether a live record previously existed. A separate pre-read is a separate snapshot and can race with writers unless your application coordinates it.

Read failures versus write failures

A checksum/I/O error encountered while reading is returned to the caller. The current implementation does not poison the handle for every read error; poisoning is attached to write/checkpoint failures. Applications should define a deliberate policy for suspected corruption rather than assuming the engine repaired it.

Reads observe one committed state while holding a shared lock. Separate reads can see different states. For a multi-record consistent read, use one suitable scan when possible; there is no general multi-key snapshot API.

Error precedence

The implementation can check a canceled context before a closed handle, or reject one invalid argument before another. Do not build application logic around which error wins when several conditions are invalid simultaneously. Handle the returned error with errors.Is and preserve unexpected I/O details for diagnosis.