Home on Copia

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Requirements#

Install the Go version declared in go.mod.

Run Copia#

From the repository root, start an in-memory session:

go run ./cmd/copia

To append changes to a WAL file and replay them next time, pass -file:

go run ./cmd/copia -file copia.wal

The interactive prompt accepts one command per line. For example:

set language Go
get language
Go

Use quit (or exit) to leave the session. An in-memory store starts empty on each run; a file-backed store loads its recorded operations when opened.

Open and close

Mon, 01 Jan 0001 00:00:00 +0000

Use Open() for a fresh in-memory store. Use OpenFile(path) to replay existing WAL records and append new operations to that file.

var db copia.KV
if err := db.OpenFile("copia.wal"); err != nil { return err }
defer db.Close()

Close() syncs and closes the WAL. Methods called before opening or after closing return copia.ErrNotOpen.

Command line reference

Mon, 01 Jan 0001 00:00:00 +0000

Start the program with go run ./cmd/copia. Add -file path to persist operations to a WAL file.

Command	Behavior
`set <key> <value>`	Store a value. The value is the remainder of the input line.
`get <key>`	Print the value, or `not found`.
`del <key>`	Delete a key, or print `not found`.
`rename <source> <target>`	Move a value to another key.
`copy <source> <target>`	Copy a value to another key.
`exists <key>`	Print `true` or `false`.
`keys [prefix]`	Print keys with the prefix, in bytewise sorted order.
`count`	Print the number of keys.
`clear`	Remove all keys.
`help`	Print the command list.
`quit` / `exit`	End the session.

Keys and values in the CLI are whitespace-delimited text. The Go API accepts arbitrary byte slices.

Set

Mon, 01 Jan 0001 00:00:00 +0000

Set(key, value) writes or replaces a value. It returns whether it updated the store and an error.

updated, err := db.Set([]byte("language"), []byte("Go"))

The store copies both byte slices. In file-backed mode, the WAL record is synced before the in-memory value changes.

Get

Mon, 01 Jan 0001 00:00:00 +0000

Get(key) returns a copy of the value, whether the key exists, and an error.

value, found, err := db.Get([]byte("language"))

The returned bytes do not alias the store’s internal value.

Delete

Mon, 01 Jan 0001 00:00:00 +0000

Del(key) deletes the key. It returns whether a key was deleted and an error. A missing key returns false without an error.

deleted, err := db.Del([]byte("language"))

Storage and WAL format

Mon, 01 Jan 0001 00:00:00 +0000

OpenFile(path) opens or creates a WAL, replays its valid records into memory, then positions the file for appending. Each successful mutation is recorded and synced before the in-memory map is changed.

Record framing#

Each record has a 12-byte header followed by a payload:

Header bytes	Meaning
0–3	`CPWL` magic bytes
4–7	Payload length as a little-endian `uint32`
8–11	IEEE CRC-32 checksum of the payload

The payload begins with an operation byte. For set, del, rename, and copy, the remaining bytes encode an entry: two little-endian uint32 lengths, then key bytes and value bytes. clear has only its operation byte. Entries are limited to 64 MiB.

Rename

Mon, 01 Jan 0001 00:00:00 +0000

Rename(oldKey, newKey) moves a value to another key. It returns whether the source key existed and an error.

renamed, err := db.Rename([]byte("old"), []byte("new"))

Copy

Mon, 01 Jan 0001 00:00:00 +0000

Copy(sourceKey, targetKey) copies a value to another key. It returns whether the source key existed and an error.

copied, err := db.Copy([]byte("source"), []byte("backup"))

Exists

Mon, 01 Jan 0001 00:00:00 +0000

Exists(key) reports whether the key exists and returns an error.

found, err := db.Exists([]byte("language"))

List keys

Mon, 01 Jan 0001 00:00:00 +0000

Keys(prefix) returns keys that begin with the prefix, sorted in bytewise order.

keys, err := db.Keys([]byte("user:"))

Count entries

Mon, 01 Jan 0001 00:00:00 +0000

Len() returns the number of keys in the store and an error.

count, err := db.Len()

Clear

Mon, 01 Jan 0001 00:00:00 +0000

Clear() removes every key. In file-backed mode, it appends and syncs a clear record before resetting the in-memory map.

if err := db.Clear(); err != nil { return err }