summaryrefslogtreecommitdiffstats
path: root/proto/CDB_README.html
blob: 352c6adeb9e86ca7faacc312fbe5189981406c78 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix CDB Howto</title>

<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">

</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 "cdb:<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 postmap(1)
or postalias(1) command. The DATABASE_README document has general
information about Postfix databases.  </p>

<p> CDB support is available with Postfix 2.2 and later releases.
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 INSTALL document. Some modification may
be required if you build Postfix from a vendor-specific source
package.  </p>

<p> Postfix is compatible with two CDB implementations: </p>

<ul>

<li> <p> The original cdb library from Daniel Bernstein, available
from http://cr.yp.to/cdb.html, and </p>

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

</ul>

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

<p>To build Postfix after you have installed tinycdb, use something
like: </p>

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

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

<blockquote>
<pre>
% 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
</pre>
</blockquote>

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

<blockquote>

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

</blockquote>

<p> After Postfix has been built with cdb support, you can use
"cdb" tables wherever you can use read-only "hash", "btree" or
"dbm" tables. However, the "<b>postmap -i</b>" (incremental record
insertion) and "<b>postmap -d</b>" (incremental record deletion)
command-line options are not available. For the same reason the
"cdb" map type cannot be used to store the persistent address
verification cache for the verify(8) service, or to store
TLS session information for the tlsmgr(8) service. </p>