42.4 database gnudbm

The (database gnudbm) module allows access to the functionality of GNU dbm for string keys/values (to store arbitrary data, convert each datum to a string, first), excluding support for the DBM/NDBM compatibility functions provided by GNU dbm. For details not documented in this section, See Top.

Dealing with GNU dbm files consists of several actions. As with regular files, you first open the file. Then you can store data into the file, fetch and/or delete data from the file, enumerate the available keys in the file, and so on. Finally, you close the file. Occasionally, you may also wish to maintain the database file by compacting it.

42.4.1 Quick Start

Here is an overview of a typical session using the (database gnudbm) module.

The first thing we want to do is create a new GNU dbm file.

     (define db (gnudbm-open "foo.db" 'create))

The symbol create tells gnudbm-open to create a new GNU dbm file. Next, we'll store a value into the database and retrieve it. The keys under which the data is stored, as well as the values, must be strings.

     (gnudbm-store! db "foo" "bar" 'insert)
     (define v (gnudbm-fetch db "foo"))
     v
     ⇒ "bar"

When we have stored a little more data,

     (gnudbm-store! db "fumble" "braz" 'insert)

we can iterate over all the keys with the procedures gnudbm-first-key and gnudbm-next-key.

     (define k (gnudbm-first-key db))
     k
     ⇒ "foo"
     
     (set! k (gnudbm-next-key db k))
     k
     ⇒ "fumble"

Finally, when we are done with the database file, we can close it.

     (gnudbm-close! db)

42.4.2 Opening GNU dbm files

Before using any of the other procedures, you must open a GNU dbm file with the procedure gnudbm-open.

When a new database file is created (using mode create or new), it has a file mode of 0622 modulo umask (see Processes).

There are two points where gnudbm-open is more restricted than its counterpart from the underlying GNU dbm library (please contact ttn if you require these features from Scheme programs):

• no support for GDBM_FAST
• block size (for new GNU dbm files) defaults to a value that depends on the file system where the file is located

The object returned by gnudbm-open is a database handle, which can be used with the other procedures in this module. Database handles are of a special data type (a smob) which can be tested with the predicate gnudbm?.

The underlying file descriptor (useful for, say, customized file-locking schemes) is available via gnudbm-fdesc.

42.4.3 Data Manipulation

Use gnudbm-store!, gnudbm-fetch and gnudbm-delete! to manipulate data in a database.

Please note that the unused space in the GNU dbm file made available by gnudbm-delete! is not automatically compacted; use gnudbm-reorganize! to do that.

42.4.4 Querying the database

The procedure gnudbm-exists? tests whether or not a given key exists in the file, while gnudbm-first-key and gnudbm-next-key are useful for iterating over all keys.

Use the following idiom to list all available keys – db should be a valid database handle.

     (let loop ((key (gnudbm-first-key db)))
       (cond (key (write-line key)
                  (loop (gnudbm-next-key db key)))
             (else (write-line "no more keys"))))

42.4.5 Closing the file

When you have finished manipulating a GNU dbm file, you should close it. If you do not close the file manually, it will be closed as soon as the last reference to the handle is gone (this is handled by Guile's garbage collector).

After closing, the handle is invalidated and must no longer be passed to any of the other procedures.

Normally, the cached contents of a GNU dbm file are written to disk when the file is closed (either implicitly by the garbage collector or explicitly by gnudbm-close!). If you need to make sure that the cached data is written to a file, but don't want to close it, you can use the following procedure.

42.4.6 Misc

For performance reasons, the GNU dbm library does normally not compact the free space in a database file when data is deleted. This compaction can be triggered by calling gnudbm-reorganize!.

GNU dbm provides two options for open connections, the cache size and the so-called fast mode. You can use gnudbm-setopt! to set these from Scheme code. Note that attempting to set the cache size after any db accesses occur will result in an error.