-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathdatabase.htm
124 lines (115 loc) · 5.95 KB
/
database.htm
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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>cmail: Master database documentation</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="icon" href="static/cmail_logo.png" type="image/x-icon" />
<link rel="shortcut icon" href="static/cmail_logo.png" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="static/cmail.css" />
<meta name="description" content="cmail master database documentation" />
<meta name="keywords" content="cmail, smtp, email, messaging, database schema, sqlite" />
<meta name="robots" content="index,follow" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<div>
<a href="index.htm">Back</a> to the main page
</div>
<div>
<h1>The master database</h1>
Discussion and details of the central interface between cmail modules:
The master database. This is where most of the run-time configuration,
such as user information (names, password hashes, user database locations),
addresses and mail routing information as well as outbound mail is stored.
</div>
<div class="section">
<h2>Why SQLite</h2>
<p>
SQLite has a long track record as a stable file format (which qualifies it over
most other binary (and especially homebrew) storage formats. It also presents a
nice C API (which sets it apart from most other Mail storage formats), the database
is present as a single file on the disk (which may become rather large, but makes
it easy to switch between databases) and using a database leaves open the option
of implementing other database backends later, which (potentially) allows for great
scalability.
</p>
<p>
Using a database also allows us to maintain a single storage backend both for
configuration and mail storage, though whether that is a good thing is of course
a matter of opinion.
</p>
</div>
<div class="section">
<h2>Creating an empty database</h2>
To create an empty database, the cmail repository provides a schema file, consisting
of all SQL statements necessary to create an empty master database.
<p>
To interact with SQLite databases, you can either install the <code>sqlite3</code> command-line
interface or use a database management tool of your choice which supports it.
</p>
To create a new, empty master database in your current working directory, run
<p>
<code>
~# sqlite3 empty.db ".read <em>/path/to/cmail-repo/</em>sql-update/install_master.sql"
</code>
</p>
or load the respective file into your database editor and run the commands in <code>sql-update/install_master.sql</code>.
<p>
Note that for a master database to be used by cmail, the file must be passed as the <code>database</code> parameter
in the daemon configuration, and the file itself as well as the directory containing it must be read- and writable by
the user running the cmail daemons.
</p>
</div>
<div class="section">
<h2>User databases</h2>
Since SQLite databases are file-based and cmail needs to access the same file from multiple daemons, locking
may become a problem on high-volume installations. cmail counters this by allowing users to have their own
<em>user databases</em>, which will only contain mail stored to their accounts. User databases do not contain
system configuration data as the master database does. User databases can also be used to allow users direct SQL
access to their mail. Note that, should a user database become unwritable for cmail, incoming mail will be stored
to the master database even if a user database is configured. This helps prevent lost mail.
<p>
To create a user database, follow the steps above, substituting <code>sql-update/install_master.sql</code> with
<code>sql-update/install_user.sql</code>.
</p>
<p>
Note that some daemons and protocols (namely, the IMAP implementations), may have notes and restrictions on the use
of user databases, at least as far as inter-system portability of database files goes.
</p>
To activate a user database, pass the path to the newly installed user database to <code><a href="admin/user.htm">cmail-admin-user</a>
userdb</code> and take care that the file itself as well as the directory containing it must be read- and writable
by the user running the cmail daemons.
</div>
<div class="section">
<h2>Populating the database</h2>
To interact with a master database, for example to configure users and mail addresses, use the cmail-admin set
of tools: <a href="admin/user.htm">cmail-admin-user</a>, <a href="admin/address.htm">cmail-admin-address</a>,
<a href="admin/smtpd.htm">cmail-admin-smtpd</a> and <a href="admin/popd.htm">cmail-admin-popd</a>
or, if you prefer, install and use the web interface.
<p>
To learn more about the internal structure of the master database, skip to the "Schema reference" section of this
document or refer to the comments in <code>sql-update/install_master.sql</code>.
</p>
</div>
<div class="section">
<h2>Upgrading the database</h2>
As development progresses, the internal structure of master and user databases evolves. To prevent problems when using
incompatible code and database versions, all databases track their "schema version" internally.
When a newer software version encounters a database version it does not recognize as compatible, it will exit with a
warning. When you notice this warning, you will need to upgrade your database as described in the <a href="upgrading.htm">upgrade guide</a>.
</div>
<div class="section">
<h2>Interfacing the database</h2>
If you're considering writing a tool that interfaces with the cmail database, please take the following into account
<ul>
<li></li>
</ul>
</div>
<div class="section">
<h2>Caveats</h2>
</div>
<div class="section">
<h2>Schema reference</h2>
</div>
</body>
</html>