Documentation

A session stores context that is shared by multiple tables.

Each session is associated with one session directory where the files containing table data are stored. Each session locks its session directory. There can only be one active session for each session directory at a time. If a database is must be accessed from multiple parts of a program, one session should be opened and shared between those parts of the program. Session directories cannot be shared between OS processes.

A session may contain multiple tables, which may each have a different configuration and different key, value, and BLOB types. Furthermore, sessions may contain both simple and full-featured tables.

A table is a handle to an individual LSM-tree key/value store with both in-memory and on-disk parts.

Warning: Tables are ephemeral. Once you close a table, its data is lost forever. To persist tables, use snapshots.

A blob reference is a reference to an on-disk blob.

Warning: A blob reference is not stable. Any operation that modifies the table, cursor, or session that corresponds to a blob reference may cause it to be invalidated.

The word "blob" in this type comes from the acronym Binary Large Object.

A cursor is a stable read-only iterator for a table.

A cursor iterates over the entries in a table following the order of the serialised keys. After the cursor is created, updates to the referenced table do not affect the cursor.

The name of this type references database cursors, not, e.g., text editor cursors.

An instance of ResolveValue v specifies how to merge values when using monoidal upsert.

The class has two functions. The function resolve acts on values, whereas the function resolveSerialised acts on serialised values. Each function has a default implementation in terms of the other and serialisation/deserialisation. The user is encouraged to implement resolveSerialised.

Instances should satisfy the following:

Compatibility

The functions resolve and resolveSerialised should be compatible:

serialiseValue (resolve v1 v2) == resolveSerialised (Proxy @v) (serialiseValue v1) (serialiseValue v2)

Associativity

The function resolve should be associative:

serialiseValue (v1 `resolve` (v2 `resolve` v3)) == serialiseValue ((v1 `resolve` v2) `resolve` v3)

Valid Output

The function resolveSerialised should only return deserialisable values:

deserialiseValue (resolveSerialised (Proxy @v) rb1 rb2) `deepseq` True

Test the Compatibility law for the ResolveValue class.

Test the Associativity law for the ResolveValue class.

Test the Valid Output law for the ResolveValue class.

Wrapper that provides an instance of ResolveValue via the Semigroup instance of the underlying type.

resolve (ResolveViaSemigroup v1) (ResolveViaSemigroup v2) = ResolveViaSemigroup (v1 <> v2)

Wrapper that provides an instance of ResolveValue such that upsert behaves as insert.

The name ResolveAsFirst is in reference to the wrapper First from Data.Semigroup.

resolve = const