UPGRADING

Upgrading from DBMail 3.0 to DBMail 3.2
=======================================

Dependencies
------------

* Database: MySQL 5.0 or better, PostgreSQL 8.3+, Sqlite3, Oracle
* Glib: (>= 2.16.0)
* GMime: (>= 2.6.20)
* OpenSSL
* libmhash
* libzdb
* libevent: (>= 2.0.21)

Schema Changes
--------------

* As of dbmail-3.2 auto-migrations are supported, so no manual migrations
  are required.


Upgrading from DBMail 2.2 to DBMail 3.0
=======================================

Dependencies
------------

* Database: MySQL 5.0, PostgreSQL 8.3+, or SQLite3
* Glib: (>= 2.16.0)
* GMime: (>= 2.4.0)
* Optional: libSieve (>= 2.2.1)
* Optional: LDAP such as OpenLDAP or ActiveDirectory.
* openssl
* libmhash
* libzdb (http://www.tildeslash.com/libzdb/)
* libevent

Config Changes
--------------

* MySQL: notice!

 A special note to MySQL users: since DBMail 3.0 stores attachments in
 single rows, you need to set 'max_allowed_packet' in /etc/mysql/my.cnf
 to a value that is larger than the largest email attachment you expect
 to support. So if you accept emails upto say 20MB, you should set a 
 value for 'max_allowed_packet' of no less than 21MB, leaving some room
 for network overhead. If you want to be safe: use 1.5 times the max
 message size.

* PostgreSQL: notice!

 Also a special note to PostgreSQL users: since pg9 has changed the 
 default for bytea_output in postgresql.conf you must make sure this
 config parameter is set to 'escape'. Failing to do so will make it
 impossible for DBMail to parse any query results involving bytea 
 fields. This in turn will break the migration procedure and make
 your email inaccessible.


* [DBMAIL] section 

 Dbmail allows you to select the database backend and authentication
 module in the config file.

dburi=sqlite:///home/johndoe/dbmail.sqlite
authdriver=sql/ldap

 The old database connection parameter fields (driver, host, user, password,
 sqlport, sqlsocket, db) are now deprecated.
 
 The old TRACE_LEVEL is now not used anymore, and
 TRACE_SYSLOG/TRACE_STDERR are now deprecated.
 
 Logging has been broken up into 8 logging levels and each level can
 be individually turned on or off. The Stderr/log file logs all
 entries to stderr or the log file. Syslog logging uses the facility
 mail and the logging level of the event for logging. Syslog can then
 be configured to log data according to the levels.

 Set the log level to the sum of the values next to the levels you
 want to record.
 
   1 = Emergency 
   2 = Alert
   4 = Critical
   8 = Error
  16 = Warning
  32 = Notice
  64 = Info
 128 = Debug
 255 = database queries (very verbose)

 Examples:   0 = Nothing
            31 = Emergency + Alert + Critical + Error + Warning
           511 = Everything

FILE_LOGGING_LEVELS       = 7
SYSLOG_LOGGING_LEVELS     = 31

Schema Changes
--------------

Migration scripts from the previous stable releases are provided in
sql/mysql, sql/postgresql and sql/sqlite. Please test them first
before applying them to your live database. Especially people who have
modified their tables, and users using databases that go back to 2.0
or earlier should take special care.

The schema for 3.0 adds new tables for single-instance storage of
mimeparts, and for supporting user labels on messages in IMAP.
Migration of old data is supported through dbmail-util, but until 
you migrate the old data will remain accessible. New messages will
be stored in the new schema.

Also, the header caching tables have been revised. This means they
will have to be dropped, re-created, and re-filled using:
dbmail-util -by

Server Changes
--------------

Dbmail until 2.2 used a pre-forking server design with a dedicated
connection to the database backend for each forked process. Even with
a hundred or so concurrently connected clients this stretched the
scalability of the database backends. 

Starting with version 2.3.3 dbmail has switched to a single process
that uses a event-driven architecture to handle many many concurrent
clients. Where needed a pool of worker threads is used to process
database transactions. Currently, only the IMAP server is multi-
threaded. Database transactions are handled by a single shared 
dynamic database connection pool to minimize the number
of overall database connections.  

All this means that a number of configuration options are now
redundant. You can remove the following items from dbmail.conf:

NCHILDREN
MAXCHILDREN
MINSPARECHILDREN
MAXSPARECHILDREN
MAXCONNECTS

---
EOF