5.26 Database Functions

The functions described below provide a user interface to DBM databases.

Each DBM database is a separate disk file that keeps key/value pairs. The interface allows to retrieve the value corresponding to a given key. Both ‘key’ and ‘value’ are null-terminated character strings. To lookup a key, it is important to know whether its length includes the terminating null byte. By default, it is assumed that it does not.

Another important database property is the file mode of the database file. The default file mode is ‘640’ (i.e. ‘rw-r----’, in symbolic notation).

These and other properties can be configured using the dbprop pragma:

#pragma dbprop pattern prop [prop]

The pattern is the database name or shell-style globbing pattern. Properties defined by that pragma apply to each database whose name matches this pattern. If several dbprop pragmas match the database name, the one that matches exactly is preferred.

The rest of arguments define properties for that database. The valid values for prop are:

1. The word ‘null’, meaning that the terminating null byte is included in the key length.

   Setting ‘null’ property is necessary, for databases created with makemap -N hash command.

2. File mode for the disk file. It can be either an octal number, or a symbolic mode specification in ls-like format. E.g., the following two formats are equivalent:

   640
   rw-r----
   

3. DBM scheme, which specifies the type of the DBM (see Database Formats) to use for this database. The scheme consists of DBM type name followed by a colon and two slashes. E.g. ‘gdbm://’ means a GDBM database. See DBM scheme, for a detailed discussion.

For example, consider the following pragmas:

#pragma dbprop /etc/mail/whitelist.db 640

It tells that the database file whitelist.db has privileges ‘640’ and do not include null in the key length.

Similarly, the following pragma:

#pragma dbprop `/etc/mail/*.db' null 600 bdb://

declares that all database files in directory /etc/mail are Berkeley DB files, have privileges ‘640’, and include null terminator in the key length. Notice, the use of m4 quoting characters in the example below. Without them, the sequence ‘/*’ would have been taken as the beginning of a comment.

Additionally, for compatibility with previous versions (up to 5.0), the terminating null property can be requested via an optional argument to the database functions (in description below, marked as null).

Built-in Function: boolean dbmap (string db, string key, [boolean null])

Looks up key in the DBM file db and returns true if it is found.

See above for the meaning of null.

See whitelisting, for an example of using this function.

Built-in Function: string dbget (string db, string key [, string default, boolean null])

Looks up key in the database db and returns the value associated with it. If the key is not found returns default, if specified, or empty string otherwise.

See above for the meaning of null.

Built-in Function: void dbput (string db, string key, string value [, boolean null, number mode ])

Inserts in the database a record with the given key and value. If a record with the given key already exists, its value is replaced with the supplied one.

See above for the meaning of null. Optional mode allows to explicitly specify the file mode for this database. See also #pragma dbprop, described above.

Built-in Function: void dbinsert (string db, string key, string value [, boolean replace, boolean null, number mode ])

This is an improved variant of dbput, which provides a better control on the actions to take if the key already exists in the database. Namely, if replace is ‘True’, the old value is replaced with the new one. Otherwise, the ‘e_exists’ exception is thrown.

Built-in Function: void dbdel (string db, string key [, boolean null, number mode])

Delete from the database the record with the given key. If there are no such record, return without signalling error.

If the optional null argument is given and is not zero, the terminating null character will be included in key length.

Optional mode allows to explicitly specify the file mode for this database. See also #pragma dbprop, described above.

The functions above have also the corresponding exception-safe interfaces, which return cleanly if the ‘e_dbfailure’ exception occurs. To use these interfaces, request the safedb module:

require safedb

The exception-safe interfaces are:

Library Function: number safedbmap (string db, string key [, number default, boolean null])

This is an exception-safe interface to dbmap. If a database error occurs while attempting to retrieve the record, safedbmap returns default or ‘0’, if it is not defined.

Library Function: string safedbget (string db, string key [, string default, boolean null])

This is an exception-safe interface to dbget. If a database error occurs while attempting to retrieve the record, safedbget returns default or empty string, if it is not defined.

Library Function: void safedbput (string db, string key, string value [, boolean null])

This is an exception-safe interface to dbput. If a database error occurs while attempting to retrieve the record, the function returns without raising exception.

Library Function: void safedbdel (string db, string key [, boolean null])

This is an exception-safe interface to dbdel. If a database error occurs while attempting to delete the record, the function returns without raising exception.

The verbosity of ‘safedb’ interfaces in case of database error is controlled by the value of safedb_verbose variable. If it is ‘0’, these functions return silently. This is the default behavior. Otherwise, if safedb_verbose is not ‘0’, these functions log the detailed diagnostics about the database error and return.

The following functions provide a sequential access to the contents of a DBM database:

Built-in Function: number dbfirst (string name)

Start sequential access to the database name. The return value is an opaque identifier, which is used by the remaining sequential access functions. This number is ‘0’ if the database is empty.

Built-in Function: number dbnext (number dn)

Select next record form the database. The argument dn is the access identifier, returned by a previous call to dbfirst or dbnext.

Returns new access identifier. This number is ‘0’ if all records in the database have been visited.

The usual approach for iterating over all records in a database dbname is:

  loop for number dbn dbfirst(dbname)
  do
    …
  done while dbnext(dbn)

The following two functions can be used to access values of the currently selected database record. Their argument, dn, is the access identifier, returned by a previous call to dbfirst or dbnext.

Built-in Function: string dbkey (number dn)

Return the key from the selected database record.

Built-in Function: string dbvalue (number dn)

Return the value from the selected database record.

Built-in Function: void dbbreak (number dn)

Stop sequential access to the database and deallocate all associated resources. Use this function if you need to break from the sequential access loop, as in the example below:

  loop for number dbn dbfirst(dbname)
  do
    if some_condition
      dbbreak(dbn)
      break
    fi
  done while dbnext(dbn)

Built-in Function: number db_expire_interval (string fmt)

The fmt argument is a database format identifier (see Database Formats). If it is valid, the function returns the expiration interval for that format. Otherwise, db_expire_interval raises the e_not_found exception.

Built-in Function: string db_name (string fmtid)

The fmtid argument is a database format identifier (see Database Formats). The function returns the file name for that format. If fmtid does not match any known format, db_name raises the e_not_found exception.

Built-in Function: number db_get_active (string fmtid)

Returns the flag indicating whether the cache database fmtid is currently enabled. If fmtid does not match any known format, db_name raises the e_not_found exception.

Built-in Function: void db_set_active (string fmtid, boolean enable)

Enables the cache database fmtid if enable is ‘True’, or disables it otherwise. For example, to disable DNS caching, do:

db_set_active("dns", 0)

Built-in Function: boolean relayed (string domain)

Returns true if the string domain is found in one of relayed domain files (see relayed-domain-file). The usual construct is:

if relayed(hostname(${client_addr}))
  …

which yields true if the IP address from Sendmail variable ‘client_addr’ is relayed by the local machine.