dist/html/CDB_README.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "https://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix CDB Howto</title>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix CDB Howto</h1>

<hr>

<h2>Introduction</h2>

<p> 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.  </p>

<p> Postfix CDB databases are specified as "<a href="CDB_README.html">cdb</a>:<i>name</i>", where
<i>name</i> 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 <a href="postmap.1.html">postmap(1)</a>
or <a href="postalias.1.html">postalias(1)</a> command. The <a href="DATABASE_README.html">DATABASE_README</a> document has general
information about Postfix databases.  </p>

<p> You can use "<a href="CDB_README.html">cdb</a>:" tables wherever you can use read-only "hash",
"btree" or "lmdb" tables with the following limitations: </p>

<ul>

<li> <p> 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. </p>

<li> <p> The "<b>postmap -i</b>" (individual record insertion) and
"<b>postmap -d</b>" (individual record deletion) command-line
options are not available. For the same reason the "<a href="CDB_README.html">cdb</a>:" map type
cannot be used to for persistent caches, such as the address
verification cache for the <a href="verify.8.html">verify(8)</a> service, the TLS session cache
for the <a href="tlsmgr.8.html">tlsmgr(8)</a> service, or the dynamic allowlist for <a href="postscreen.8.html">postscreen(8)</a>.
</p>

<li> <p> The "sequence" operation ("<b>postmap -s</b>" or "<b>postalias
-s</b>") is available only wen Postfix is built with tinycdb by
Michael Tokarev, not with the original cdb library by Daniel Bernstein.
</p>

</ul>

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

<h2>Building Postfix with CDB support</h2>

<p> These instructions assume that you build Postfix from source
code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
be required if you build Postfix from a vendor-specific source
package.  </p>

<p> Historically, Postfix has been compatible with two CDB
implementations: </p>

<ul>

<li> <p> The original cdb library from Daniel Bernstein, available
from <a href="https://cr.yp.to/cdb.html">https://cr.yp.to/cdb.html</a>, and </p>

<li> <p> tinycdb (version 0.5 and later) from Michael Tokarev,
available from <a href="https://www.corpit.ru/mjt/tinycdb.html">https://www.corpit.ru/mjt/tinycdb.html</a>. </p>

</ul>

<p> 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: </p>

<blockquote>
<pre>
% make tidy
% make -f Makefile.init makefiles \
    "CCARGS=-DHAS_CDB -I/usr/local/include ..." \
    "<a href="CDB_README.html">AUXLIBS_CDB</a>=L/usr/local/lib -lcdb" ...
% make
</pre>
</blockquote>

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

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

<blockquote>
<pre>
% make tidy
% CDB=<i>/some/where/</i>cdb-<i>version</i>
% make -f Makefile.init makefiles \
    "CCARGS=-DHAS_CDB -I$CDB ..." \
    "<a href="CDB_README.html">AUXLIBS_CDB</a>=$CDB/cdb.a $CDB/alloc.a $CDB/buffer.a $CDB/unix.a $CDB/byte.a" ...
% make
</pre>
</blockquote>

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

<p> Postfix versions before 3.0 use AUXLIBS instead of <a href="CDB_README.html">AUXLIBS_CDB</a>.
With Postfix 3.0 and later, the old AUXLIBS variable still supports
building a statically-loaded CDB database client, but only the new
<a href="CDB_README.html">AUXLIBS_CDB</a> variable supports building a dynamically-loaded or
statically-loaded CDB database client.  </p>

<blockquote>

<p> Failure to use the <a href="CDB_README.html">AUXLIBS_CDB</a> 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. </p>

</blockquote>