1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
2        "https://www.w3.org/TR/html4/loose.dtd">
3
4<html>
5
6<head>
7
8<title>Postfix CDB Howto</title>
9
10<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
11<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
12
13</head>
14
15<body>
16
17<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix CDB Howto</h1>
18
19<hr>
20
21<h2>Introduction</h2>
22
23<p> CDB (Constant DataBase) is an indexed file format designed by
24Daniel Bernstein. CDB is optimized exclusively for read access
25and guarantees that each record will be read in at most two disk
26accesses. This is achieved by forgoing support for incremental
27updates: no single-record inserts or deletes are supported.  CDB
28databases can be modified only by rebuilding them completely from
29scratch, hence the "constant" qualifier in the name.  </p>
30
31<p> Postfix CDB databases are specified as "<a href="CDB_README.html">cdb</a>:<i>name</i>", where
32<i>name</i> specifies the CDB file name without the ".cdb" suffix
33(another suffix, ".tmp", is used temporarily while a CDB file is
34under construction).  CDB databases are maintained with the <a href="postmap.1.html">postmap(1)</a>
35or <a href="postalias.1.html">postalias(1)</a> command. The <a href="DATABASE_README.html">DATABASE_README</a> document has general
36information about Postfix databases.  </p>
37
38<p> You can use "<a href="CDB_README.html">cdb</a>:" tables wherever you can use read-only "hash",
39"btree" or "lmdb" tables with the following limitations: </p>
40
41<ul>
42
43<li> <p> CDB databases cannot be larger than 4GB on LP64 and ILP32
44systems, because the CDB library API uses unsigned integers for
45file offsets.  </p>
46
47<li> <p> The "<b>postmap -i</b>" (incremental record insertion) and
48"<b>postmap -d</b>" (incremental record deletion) command-line
49options are not available. For the same reason the "<a href="CDB_README.html">cdb</a>:" map type
50cannot be used to for persistent caches, such as the address
51verification cache for the <a href="verify.8.html">verify(8)</a> service, the TLS session cache
52for the <a href="tlsmgr.8.html">tlsmgr(8)</a> service, or the dynamic allowlist for <a href="postscreen.8.html">postscreen(8)</a>.
53</p>
54
55<li> <p> The "sequence" operation ("<b>postmap -s</b>" or "<b>postalias
56-s</b>") is available only wen Postfix is built with tinycdb by
57Michael Tokarev, not with the original cdb library by Daniel Bernstein.
58</p>
59
60</ul>
61
62<p> CDB support is available with Postfix 2.2 and later releases.
63The remainder of this document describes how to build Postfix with
64CDB support. </p>
65
66<h2>Building Postfix with CDB support</h2>
67
68<p> These instructions assume that you build Postfix from source
69code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
70be required if you build Postfix from a vendor-specific source
71package.  </p>
72
73<p> Postfix is compatible with two CDB implementations: </p>
74
75<ul>
76
77<li> <p> The original cdb library from Daniel Bernstein, available
78from <a href="https://cr.yp.to/cdb.html">https://cr.yp.to/cdb.html</a>, and </p>
79
80<li> <p> tinycdb (version 0.5 and later) from Michael Tokarev,
81available from <a href="https://www.corpit.ru/mjt/tinycdb.html">https://www.corpit.ru/mjt/tinycdb.html</a>. </p>
82
83</ul>
84
85<p>  Tinycdb is preferred, since it is a bit faster, has additional
86useful functionality and is much simpler to use. </p>
87
88<p>To build Postfix after you have installed tinycdb, use something
89like: </p>
90
91<blockquote>
92<pre>
93% make tidy
94% CDB=../../../tinycdb-0.5
95% make -f Makefile.init makefiles "CCARGS=-DHAS_CDB -I$CDB" \
96    "<a href="CDB_README.html">AUXLIBS_CDB</a>=$CDB/libcdb.a"
97% make
98</pre>
99</blockquote>
100
101<p> Alternatively, for the D.J.B. version of CDB:<p>
102
103<blockquote>
104<pre>
105% make tidy
106% CDB=../../../cdb-0.75
107% make -f Makefile.init makefiles "CCARGS=-DHAS_CDB -I$CDB" \
108    "<a href="CDB_README.html">AUXLIBS_CDB</a>=$CDB/cdb.a $CDB/alloc.a $CDB/buffer.a $CDB/unix.a $CDB/byte.a"
109% make
110</pre>
111</blockquote>
112
113<p> Postfix versions before 3.0 use AUXLIBS instead of <a href="CDB_README.html">AUXLIBS_CDB</a>.
114With Postfix 3.0 and later, the old AUXLIBS variable still supports
115building a statically-loaded CDB database client, but only the new
116<a href="CDB_README.html">AUXLIBS_CDB</a> variable supports building a dynamically-loaded or
117statically-loaded CDB database client.  </p>
118
119<blockquote>
120
121<p> Failure to use the <a href="CDB_README.html">AUXLIBS_CDB</a> variable will defeat the purpose
122of dynamic database client loading. Every Postfix executable file
123will have CDB database library dependencies. And that was exactly
124what dynamic database client loading was meant to avoid. </p>
125
126</blockquote>
127