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 24 Daniel Bernstein. CDB is optimized exclusively for read access 25 and guarantees that each record will be read in at most two disk 26 accesses. This is achieved by forgoing support for incremental 27 updates: no single-record inserts or deletes are supported. CDB 28 databases can be modified only by rebuilding them completely from 29 scratch, 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 34 under construction). CDB databases are maintained with the <a href="postmap.1.html">postmap(1)</a> 35 or <a href="postalias.1.html">postalias(1)</a> command. The <a href="DATABASE_README.html">DATABASE_README</a> document has general 36 information 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> Historically, CDB databases could not be larger than 4GB 44 on LP64 and ILP32 systems, because the CDB library API used unsigned 45 integers for file offsets. Recently, the CDB format was updated to 46 take better advantage of 64-bit processors. </p> 47 48 <li> <p> The "<b>postmap -i</b>" (individual record insertion) and 49 "<b>postmap -d</b>" (individual record deletion) command-line 50 options are not available. For the same reason the "<a href="CDB_README.html">cdb</a>:" map type 51 cannot be used to for persistent caches, such as the address 52 verification cache for the <a href="verify.8.html">verify(8)</a> service, the TLS session cache 53 for the <a href="tlsmgr.8.html">tlsmgr(8)</a> service, or the dynamic allowlist for <a href="postscreen.8.html">postscreen(8)</a>. 54 </p> 55 56 <li> <p> The "sequence" operation ("<b>postmap -s</b>" or "<b>postalias 57 -s</b>") is available only wen Postfix is built with tinycdb by 58 Michael Tokarev, not with the original cdb library by Daniel Bernstein. 59 </p> 60 61 </ul> 62 63 <p> CDB support is available with Postfix 2.2 and later releases. 64 The remainder of this document describes how to build Postfix with 65 CDB support. </p> 66 67 <h2>Building Postfix with CDB support</h2> 68 69 <p> These instructions assume that you build Postfix from source 70 code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may 71 be required if you build Postfix from a vendor-specific source 72 package. </p> 73 74 <p> Historically, Postfix has been compatible with two CDB 75 implementations: </p> 76 77 <ul> 78 79 <li> <p> The original cdb library from Daniel Bernstein, available 80 from <a href="https://cr.yp.to/cdb.html">https://cr.yp.to/cdb.html</a>, and </p> 81 82 <li> <p> tinycdb (version 0.5 and later) from Michael Tokarev, 83 available from <a href="https://www.corpit.ru/mjt/tinycdb.html">https://www.corpit.ru/mjt/tinycdb.html</a>. </p> 84 85 </ul> 86 87 <p> To build Postfix with tinycdb, install tinycdb so that the files 88 "cdb.h" and "libcdb.*" are in the appropriate locations for your 89 OS distribution. Then, use something like: </p> 90 91 <blockquote> 92 <pre> 93 % make tidy 94 % make -f Makefile.init makefiles \ 95 "CCARGS=-DHAS_CDB -I/usr/local/include ..." \ 96 "<a href="CDB_README.html">AUXLIBS_CDB</a>=L/usr/local/lib -lcdb" ... 97 % make 98 </pre> 99 </blockquote> 100 101 <p> The exact pathnames depend on where "cdb.h" and "libcdb.*" are 102 installed. The "<tt>...</tt>" may contain build information for 103 other optional features such as databases, TLS support, and so on. 104 </p> 105 106 <p> Alternatively, for the D.J.B. version of CDB:, build but do not 107 install CDB, then in the Postfix top-level directory: <p> 108 109 <blockquote> 110 <pre> 111 % make tidy 112 % CDB=<i>/some/where/</i>cdb-<i>version</i> 113 % make -f Makefile.init makefiles \ 114 "CCARGS=-DHAS_CDB -I$CDB ..." \ 115 "<a href="CDB_README.html">AUXLIBS_CDB</a>=$CDB/cdb.a $CDB/alloc.a $CDB/buffer.a $CDB/unix.a $CDB/byte.a" ... 116 % make 117 </pre> 118 </blockquote> 119 120 <p> (With cdb-20251021 and later, use 'cdb64.a' instead of 'alloc.a'.) </p> 121 122 <p> Postfix versions before 3.0 use AUXLIBS instead of <a href="CDB_README.html">AUXLIBS_CDB</a>. 123 With Postfix 3.0 and later, the old AUXLIBS variable still supports 124 building a statically-loaded CDB database client, but only the new 125 <a href="CDB_README.html">AUXLIBS_CDB</a> variable supports building a dynamically-loaded or 126 statically-loaded CDB database client. </p> 127 128 <blockquote> 129 130 <p> Failure to use the <a href="CDB_README.html">AUXLIBS_CDB</a> variable will defeat the purpose 131 of dynamic database client loading. Every Postfix executable file 132 will have CDB database library dependencies. And that was exactly 133 what dynamic database client loading was meant to avoid. </p> 134 135 </blockquote> 136
Indexes created Sat Jun 20 00:25:23 UTC 2026