BerkeleyDB

Documentation
Login

BerkeleyDB API

This CHICKEN binding for BerkeleyDB consists of a single module in a shared library of the same name. You can load the library and require the module using

  (require-extension berkeley-db)

Database Environments

  current-database-environment

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

  (open-database-environment
   HOME
   [#:mode MODE] [#:password PASSWORD]
   [#:locking] [#:logging] [#:memory-pool] [#:replication] [#:transactions]
   [#:recover] [#:recover/fatal] [#:use-environment] [#:use-environment/root]
   [#:create] [#:lockdown] [#:failure-check] [#:private]
   [#:auto-commit] [#:direct-i/o] [#:synchronous-i/o] [#:multiversion]
   [#:no-mmap] [#:overwrite] [#:initialize-region] [#:timeout->not-granted]
   [#:asynchronous] [#:no-wait] [#:snapshot] [#:asynchronous-write]
   [#:encrypt/aes])
  =>
  ENVIRONMENT

Creates a database environment and configures various settings through setup methods and the open method.

Sets current-database-environment to the newly created environment.

  (close-database-environment [ENVIRONMENT] [#:synchronous]) => (void)

Closes a database environment and destroys the handle. If no ENVIRONMENT is specified explicitly, closes the current environment and sets current-database-environment to #f.

Transactions

  (with-transaction
   THUNK
   [#:read-committed] [#:read-uncommitted] [#:bulk]
   [#:asynchronous] [#:no-wait] [#:snapshot] [#:synchronous] [#:wait]
   [#:asynchronous-write])
  =>
  (values ...)

Wraps a call to THUNK in a transaction setup with the optional flags. Returns whatever (THUNK) returns.

The transaction is committed upon normal return from (THUNK) and aborted if (THUNK) throws an exception.

Database Files

  (copy-database FILE TARGET [#:password PASSWORD] [#:auto-commit]) => (void)

Copies a database from FILE to the TARGET directory.

  (rename-database FILE TARGET [DATABASE] [#:auto-commit]) => (void)

Renames a database or database file.

  (delete-database FILE [DATABASE] [#:auto-commit]) => (void)

Deletes a database or database file.

Databases

  (open-database
   FILE [TYPE [DATABASE]]
   [#:mode MODE] [#:byte-order BYTE-ORDER] [#:page-size SIZE/BYTES]
   [#:heap-max-size SIZE/BYTES] [#:queue-extent-size SIZE/PAGES]
   [#:record-size SIZE/BYTES] [#:record-delimiter CHAR] [#:record-padding CHAR]
   [#:record-source FILE] [#:password PASSWORD]
   [#:auto-commit] [#:create] [#:exclusive] [#:multiversion] [#:no-mmap]
   [#:read-only] [#:read-uncommitted] [#:free-threaded] [#:truncate]
   [#:checksum] [#:encrypt] [#:transactions-not-durable] [#:duplicates]
   [#:duplicates/sorted] [#:no-reverse-splitting] [#:in-order] [#:renumber]
   [#:snapshot] [#:encrypt/aes] [#:serialize+deserialize WRITE+READ])
  =>
  DATABASE

Creates a database and configures various settings through setup methods and the open method.

The TYPE can be b-tree, hash-table, heap, queue, records or #f. If it is false, the database must exist and its type is detected automatically.

If you want to store something else than blobs or strings in the database, use the WRITE+READ argument to pass a pair of write- and read-like procedures for serialization and deserialization of arbitrary values.

  (database-type DATABASE) => TYPE

Determines the type of a database.

  (database-serializer DATABASE) => PROC

Retrieves the serialization procedure associated with the database or #f in case the database just handles strings or blobs.

  (database-deserializer DATABASE) => PROC

Retrieves the deserialization procedure associated with the database or #f in case the database just handles strings or blobs.

  (close-database DATABASE [#:asynchronous]) => (void)

Closes a database and destroys the handle.

  (database-associate
   DATABASE PROC SECONDARY [FOREIGN]
   [#:create] [#:immutable] [#:abort] [#:cascade])
  =>
  (void)

Associates a database with a secondary index and optionally associates the secondary index with a foreign key constraint.

The serializers and deserializers of SECONDARY and FOREIGN, if configured, must be compatible.

  (database-primary DATABASE) => DATABASE

Retrieves the primary database associated with a secondary index. Returns #f for a normal database.

  (database-mapper DATABASE) => PROC

Retrieves the mapping from primary keys and values to secondary keys associated with a secondary index. Returns #f for a normal database.

  (database-ref
   DATABASE KEY [DEFAULT]
   [#:consume] [#:consume/wait] [#:ignore-lease]
   [#:read-committed] [#:read-uncommitted] [#:read-modify-write])
  =>
  VALUE

Extracts a record from the database. If no record is found and DEFAULT is given, it is invoked in case it is a procedure and returned otherwise.

  (database-set!
   DATABASE KEY VALUE
   [#:append] [#:no-duplicate] [#:no-overwrite] [#:overwrite-duplicate]
  =>
  RECNO | (void)

  (set! (database-ref DATABASE KEY) VALUE) => (void)

Stores a record in the database. If the #:append mode of operation is selected, the key of the appended record is returned.

  (database-exists?
   DATABASE KEY
   [#:read-committed] [#:read-uncommitted] [#:read-modify-write])
  =>
  BOOLEAN

Checks whether a key exists in the database.

  (database-delete! DATABASE KEY [#:consume])

Deletes a record from the database.

  (database-fold
   DATABASE PROC SEED [KEY]
   [#:range] [#:primary] [#:read-committed] [#:read-uncommitted] [#:snapshot])
  =>
  (PROC KEY VALUE (... (PROC KEY VALUE SEED)))

Folds over the records in the database. If KEY is given, only fold over the records with matching key, unless #:range is also specified to start walking from the first index greater than or equal to KEY in a b-tree database.

If #:primary is specified and the database is a secondary index, PROC will be invoked with the primary keys and values instead of the secondary keys and primary values.

  (database-walk
   DATABASE PROC [KEY]
   [#:range] [#:primary] [#:read-committed] [#:read-uncommitted] [#:snapshot])
  =>
  (void)

Like database-fold, but discarding the result.