Postfix CDB Howto

Introduction

CDB (Constant DataBase) is an indexed file format designed by Daniel Bernstein. CDB is optimized exclusively for read access and guarantees that each record will be read in at most two disk accesses. This is achieved by forgoing support for incremental updates: no single-record inserts or deletes are supported. CDB databases can be modified only by rebuilding them completely from scratch, hence the "constant" qualifier in the name.

Postfix CDB databases are specified as "cdb:name", where name specifies the CDB file name without the ".cdb" suffix (another suffix, ".tmp", is used temporarily while a CDB file is under construction). CDB databases are maintained with the postmap(1) or postalias(1) command. The DATABASE_README document has general information about Postfix databases.

You can use "cdb:" tables wherever you can use read-only "hash", "btree" or "lmdb" tables with the following limitations:

CDB databases cannot be larger than 4GB on LP64 and ILP32 systems, because the CDB library API uses unsigned integers for file offsets.
The "postmap -i" (incremental record insertion) and "postmap -d" (incremental record deletion) command-line options are not available. For the same reason the "cdb:" map type cannot be used to for persistent caches, such as the address verification cache for the verify(8) service, the TLS session cache for the tlsmgr(8) service, or the dynamic allowlist for postscreen(8).
The "sequence" operation ("postmap -s" or "postalias -s") is available only wen Postfix is built with tinycdb by Michael Tokarev, not with the original cdb library by Daniel Bernstein.

CDB support is available with Postfix 2.2 and later releases. The remainder of this document describes how to build Postfix with CDB support.

Building Postfix with CDB support

These instructions assume that you build Postfix from source code as described in the INSTALL document. Some modification may be required if you build Postfix from a vendor-specific source package.

Postfix is compatible with two CDB implementations:

The original cdb library from Daniel Bernstein, available from https://cr.yp.to/cdb.html, and
tinycdb (version 0.5 and later) from Michael Tokarev, available from https://www.corpit.ru/mjt/tinycdb.html.

Tinycdb is preferred, since it is a bit faster, has additional useful functionality and is much simpler to use.

To build Postfix after you have installed tinycdb, use something like:

% make tidy
% CDB=../../../tinycdb-0.5
% make -f Makefile.init makefiles "CCARGS=-DHAS_CDB -I$CDB" \
    "AUXLIBS_CDB=$CDB/libcdb.a"
% make

Alternatively, for the D.J.B. version of CDB:

% make tidy
% CDB=../../../cdb-0.75
% make -f Makefile.init makefiles "CCARGS=-DHAS_CDB -I$CDB" \
    "AUXLIBS_CDB=$CDB/cdb.a $CDB/alloc.a $CDB/buffer.a $CDB/unix.a $CDB/byte.a"
% make

Postfix versions before 3.0 use AUXLIBS instead of AUXLIBS_CDB. With Postfix 3.0 and later, the old AUXLIBS variable still supports building a statically-loaded CDB database client, but only the new AUXLIBS_CDB variable supports building a dynamically-loaded or statically-loaded CDB database client.

Failure to use the AUXLIBS_CDB variable will defeat the purpose of dynamic database client loading. Every Postfix executable file will have CDB database library dependencies. And that was exactly what dynamic database client loading was meant to avoid.