LMDB Bindings

Synopsis

(import (data lmdb))

Bindings to the LMDB database library. This module exposes a simple, hash-table-like programming interface to key value databases stored on disk.

Utility Functions

procedure: (lmdb-version-info)

Report the version of the LMDB library as a record containing the semantic version number and a descriptive string.

Error Handling

condition: &lmdb

procedure: (lmdb-error? any)

A condition used to represent errors reported by the LMDB library. The type is derived from &condition.

procedure: (make-lmdb-error errno)

Create an LMDB error from an integer error code. The returned composite condition also contains a &message.

procedure: (lmdb-errno error)

Extract the integer error code from an &lmdb condition.

Database Environments

record: database-environment-hints

procedure: (database-environment-hints? any)

procedure: (make-database-environment-hints args ...)

Database environment creation flags are represented by this record type.

Optional arguments to make-database-environment-hints can be:

• An existing hints record or database environment,
• the symbol 'mode followed by an integer,
• the symbol 'max-databases followed by an integer,
• the symbol 'max-readers followed by an integer,
• the symbol 'max-size followed by an integer,
• the symbol 'subdirectory? followed by a boolean,
• the symbol 'subdirectory or 'no-subdirectory,
• the symbol 'read-only? or 'read-write? followed by a boolean,
• the symbol 'read-only or 'read-write,
• the symbol 'meta-sync? followed by a boolean,
• the symbol 'meta-sync or 'no-meta-sync,
• the symbol 'data-sync? followed by a boolean,
• the symbol 'data-sync or 'no-data-sync,
• the symbol 'write-map? followed by a boolean,
• the symbol 'write-map or 'no-write-map,
• the symbol 'map-async? followed by a boolean,
• the symbol 'map-async or 'no-map-async,
• the symbol 'tls? followed by a boolean,
• the symbol 'tls or 'no-tls,
• the symbol 'lock? followed by a boolean,
• the symbol 'lock or 'no-lock,
• the symbol 'read-ahead? followed by a boolean,
• the symbol 'read-ahead or 'no-read-ahead.

procedure: (database-environment-mode environment)

procedure: (database-environment-max-databases environment)

procedure: (database-environment-max-readers environment)

procedure: (database-environment-max-size environment)

procedure: (database-environment-subdirectory? environment)

procedure: (database-environment-read-only? environment)

procedure: (database-environment-read-write? environment)

procedure: (database-environment-meta-sync? environment)

procedure: (database-environment-data-sync? environment)

procedure: (database-environment-write-map? environment)

procedure: (database-environment-map-async? environment)

procedure: (database-environment-tls? environment)

procedure: (database-environment-lock? environment)

procedure: (database-environment-read-ahead? environment)

Accessors for the database environment creation flags.

procedure: (database-environment? any)

Type predicate for database environments. The type of database environments is a subtype of database environment hints.

parameter: current-database-environment

A parameter holding the current database environment pointer or #f.

procedure: (open-database-environment path args ...)

Creates a database environment and configures various settings. The arguments after the path may be the same as for make-database-environment-hints.

If database-environment-subdirectory? would return #t on database environment hints constructed from the same optional arguments, the given path is created as a directory to contain the copy (unless it already exists).

The procedure sets current-database-environment to the newly created environment and returns it.

procedure: (close-database-environment environment)

procedure: (close-database-environment)

Closes a database environment and invalidates the handle. If no environment is specified explicitly, closes the current environment.

procedure: (copy-database-environment path args ...)

Copies a database environment to a new path, optionally compacting the data. If no environment is specified explicitly, the current environment is copied.

Optional arguments can be:

• A source environment to copy,
• the symbol 'mode followed by an integer,
• the symbol 'compact? followed by a boolean,
• the symbol 'compact or 'no-compact.

If database-environment-subdirectory? would return #t on the original database environment, the given path is created as a directory to contain the copy (unless it already exists).

Transactions

procedure: (with-transaction thunk args ...)

Wraps a call to the given thunk in a transaction. Returns whatever (thunk) returns. If no environment is specified explicitly, the current environment is used. The transaction is committed upon normal return from the thunk or aborted in case of a non-local exit. The transaction can optionally be configured as read-only. Read-only transactions may be nested.

All database operations below have to be executed within a transaction.

Optional arguments can be:

• A database environment to use,
• the symbol 'read-only? or 'read-write? followed by a boolean,
• the symbol 'read-only or 'read-write.

procedure: (clear-stale-transactions environment)

procedure: (clear-stale-transactions)

Removes stale read-only transactions from the database lockfile (stale read-write transactions are usually removed automatically). If no environment is specified explicitly, the current environment is used.

The procedure returns the number of stale lock file entries that were removed.

Databases

record: database-hints

procedure: (database-hints? any)

procedure: (make-database-hints args ...)

Database creation flags are represented by this record type.

Optional arguments to make-database-hints can be:

• An existing hints record or database,
• the symbol 'reverse-key? followed by a boolean,
• the symbol 'reverse-key or 'no-reverse-key,
• the symbol 'duplicate-sort? followed by a boolean,
• the symbol 'duplicate-sort or 'no-duplicate-sort,
• the symbol 'integer-key? followed by a boolean,
• the symbol 'integer-key or 'no-integer-key,
• the symbol 'duplicate-fixed? followed by a boolean,
• the symbol 'duplicate-fixed or 'no-duplicate-fixed,
• the symbol 'integer-duplicate? followed by a boolean,
• the symbol 'integer-duplicate or 'no-integer-duplicate,
• the symbol 'reverse-duplicate? followed by a boolean,
• the symbol 'reverse-duplicate or 'no-reverse-duplicate,
• the symbol 'create? followed by a boolean,
• the symbol 'create or 'no-create.

procedure: (database? any)

Type predicate for databases. The type of databases is a subtype of database hints.

procedure: (open-database name args ...)

procedure: (open-database args ...)

Opens a database and configures various flags. The name of the database can be omitted if database-environment-max-databases would return #f on the current transaction's database environment and it consists of only a single default database. The arguments after the name may be the same as for make-database-hints.

If a named database does not exist when it is first opened, database-create? must return #t on database hints created from the same optional arguments, or the operation will fail.

procedure: (close-database database)

Closes a database.

procedure: (database-ref database key default)

procedure: (database-ref database key)

Extracts a bytevector value associated with the given bytevector key from the database. If no record is found and default is given, it is invoked in case it is a procedure and returned otherwise. An error is signalled if no record is found and no default is given.

procedure: (database-set! database key value args ...)

Stores a record consisting of the given bytevector key and value in the database. For databases configured with support for multiple values per key, new values are normally added to the set of existing ones. For databases with one value per key, existing records are replaced.

The following optional arguments may be used to modify the behaviour:

• The symbol 'overwrite? followed by a boolean,
• the symbol 'overwrite or 'no-overwrite,
• the symbol 'duplicate? followed by a boolean,
• the symbol 'duplicate or 'no-duplicate,
• the symbol 'append? followed by a boolean,
• the symbol 'append or 'no-append.

procedure: (database-exists? database key)

Checks whether the given bytevector key exists in the database.

procedure: (database-delete! database key value)

procedure: (database-delete! database key)

Deletes a record with the given bytevector key (and optional value) from the database. An error is signalled if no matching record is found.

For databases configured with support for multiple values per key, the value to delete can be specified explicitly. For databases with one value per key, the given value is ignored.

procedure: (database-fold proc seed database args ...)

Folds over the records in the database. If a start value is given, only folds over the records with keys greater than or equal to that value. If a stop value is given, only folds over the records with keys less than (or equal) to that value. If a limit is given, processes at most that many records before stopping early.

The following optional arguments may be used to control the behaviour:

• The symbol 'from followed by a start value,
• the symbol 'to< or 'to<= followed by a stop value,
• the symbol 'limit followed by an integer.

procedure: (database-fold proc database args ...)

Like database-fold, but discarding the results of the given procedure.