PPoossttffiixx CCDDBB HHoowwttoo

-------------------------------------------------------------------------------

IInnttrroodduuccttiioonn

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:

  * Historically, CDB databases could not be larger than 4GB on LP64 and ILP32
    systems, because the CDB library API used unsigned integers for file
    offsets. Recently, the CDB format was updated to take better advantage of
    64-bit processors.

  * The "ppoossttmmaapp --ii" (individual record insertion) and "ppoossttmmaapp --dd" (individual
    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 ("ppoossttmmaapp --ss" or "ppoossttaalliiaass --ss") 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.

BBuuiillddiinngg PPoossttffiixx wwiitthh CCDDBB ssuuppppoorrtt

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.

Historically, Postfix has been 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.

To build Postfix with tinycdb, install tinycdb so that the files "cdb.h" and
"libcdb.*" are in the appropriate locations for your OS distribution. Then, use
something like:

    % make tidy
    % make -f Makefile.init makefiles \
        "CCARGS=-DHAS_CDB -I/usr/local/include ..." \
        "AUXLIBS_CDB=L/usr/local/lib -lcdb" ...
    % make

The exact pathnames depend on where "cdb.h" and "libcdb.*" are installed. The
"..." may contain build information for other optional features such as
databases, TLS support, and so on.

Alternatively, for the D.J.B. version of CDB:, build but do not install CDB,
then in the Postfix top-level directory:

    % make tidy
    % CDB=/some/where/cdb-version
    % 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

(With cdb-20251021 and later, use 'cdb64.a' instead of 'alloc.a'.)

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.

