SQLITE3 DATABASE DRIVER FOR BOGOFILTER

======================================

This document only applies if you want to use bogofilter with SQLite3

databases.

1. Overview -----------------------------------------------------------

Bogofilter 0.93.3 and newer can use recent SQLite3 versions to store

their tokens; see section 2.1 below for supported versions.

SQLite is a database that handles a large SQL subset and stores all

tables in one permanent file, and the journal for changes in one

temporary file that gets automatically removed when no longer needed.

SQLite3 ships with a command-line client for the shell, named sqlite3.

2. Prerequisites ------------------------------------------------------

2.1 Compatibility - supported SQLite versions

At this time, only SQLite v3.6.13, and v3.6.22 and newer are supported.

Please check the SQLite website <http://sqlite.org/> for upgrade

recommendations.

  Older versions back to 3.0.8 may work, but you are advised to

carefully review the sqlite3 ChangeLog, because there have been several

important bug fixes since 3.0.8, including fixes for bugs that can

corrupt the database.  Note that sqlite v3.3.9 and newer sometimes

generate error messages that are clearer when executing SQL statements

(that bogofilter generates internally).

Bogofilter prints a warning (but continues to run) when used with SQLite

versions older than v3.6.12. This warning can be suppressed by defining

the environment variable BF_USE_OLD_SQLITE to any value, including the

empty value.

The Oracle Berkeley DB SQLite3 API that is available since Berkeley DB

5.0.21 is unsupported.  Use Berkeley DB's native API instead, see

README.db for details.

2.2 Installation

To use bogofilter with the SQLite3 back-end driver, you must install a

sufficiently recent SQLite3 version before configuring bogofilter. You

can download SQLite 3 and find installation instructions for SQLite 3 at

<http://sqlite.org/>, the SQLite installation is pretty straightforward.

After that, you can configure bogofilter, add --with-database=sqlite

to the ./configure command.

3. Use ----------------------------------------------------------------

3.1 Care and feeding

SQLite is pretty self-maintaining.  After larger maintenance operations

to remove older tokens you may want to run this command:

    sqlite3 ~/.bogofilter/wordlist.db 'VACUUM;'

to remove unused pages from the database file and reduce the file size.

A. Miscellaneous ------------------------------------------------------

A.1 Why does bogofilter use BLOB for both columns?

bogofilter has traditionally managed its own data structure inside key

and value, BLOB allows the verbatim retrieval of such data without

stumbling across embedded NUL characters and without adding even more

translations between data formats.

END--------------------------------------------------------------------