Moving "doc/db-backend.txt" to the administrator's manual (again).

doc/db-backend.txt

@@ -1,146 +0,0 @@
-$Id$
-
-
-Storing private addressbooks and preferences in a database
-==========================================================
-
-
-On sites with many users you might want to store your user data in a
-database instead of in files. This document describes how to configure
-SquirrelMail to do this.
-
-Methods for storing both personal addressbooks and user preferences in
-a database is included as a part of the distribution.
-
-
-
-Configuring PEAR DB
--------------------
-
-For this to work you must have the PEAR classes installed, these are
-part of PHP. Once these are installed you must have sure the directory
-containg them is a part of your PHP include path. See the PHP
-documentation for information on how to do that.
-Under Mandrake Linux the PEAR classes are installed as part of the
-php-devel package and under FreeBSD they are installed as part of
-the mod_php4 or php4 port/package. In Debian, you can install the
-php4-pear package. I'm afraid I have no information on
-other systems at the present time.
-
-
-Configuring addressbooks in database
-------------------------------------
-
-First you need to create a database and a table to store the data in.
-Create a database user with access to read and write in that table.
-
-For MySQL you would normally do something like:
-
- (from the command line)
- # mysqladmin create squirrelmail
-
- (from the mysql client)
- mysql> GRANT select,insert,update,delete ON squirrelmail.*
-              TO squirreluser@localhost IDENTIFIED BY 'sqpassword';
-
-The table structure should be similar to this (for MySQL):
-
-   CREATE TABLE address (
-     owner varchar(128) DEFAULT '' NOT NULL,
-     nickname varchar(16) DEFAULT '' NOT NULL,
-     firstname varchar(128) DEFAULT '' NOT NULL,
-     lastname varchar(128) DEFAULT '' NOT NULL,
-     email varchar(128) DEFAULT '' NOT NULL,
-     label varchar(255),
-     PRIMARY KEY (owner,nickname),
-     KEY firstname (firstname,lastname)
-   );
-
-and similar to this for PostgreSQL:
-CREATE TABLE "address" (
-   "owner" varchar(128) NOT NULL,
-   "nickname" varchar(16) NOT NULL,
-   "firstname" varchar(128) NOT NULL,
-   "lastname" varchar(128) NOT NULL,
-   "email" varchar(128) NOT NULL,
-   "label" varchar(255) NOT NULL,
-   CONSTRAINT "address_pkey" PRIMARY KEY ("nickname", "owner")
-);
-CREATE  UNIQUE INDEX "address_firstname_key" ON "address"
-   ("firstname", "lastname");
-
-
-Next, edit your configuration so that the address book DSN (Data Source
-Name) is specified, this can be done using either conf.pl or via the
-administration plugin. The DSN should look something like:
-
- mysql://squirreluser:sqpassword@localhost/squirrelmail or
- pgsql://squirreluser:sqpassword@localhost/squirrelmail
-
-From now on all users' personal addressbooks will be stored in a
-database.
-
-Global address book uses same table format as the one used for personal
-address book. You can even use same table, if you don't have user named
-'global'.
-
-Configuring preferences in database
------------------------------------
-
-This is done in much the same way as it is for storing your address
-books in a database.
-
-The table structure should be similar to this (for MySQL):
-
-  CREATE TABLE userprefs (
-    user varchar(128) DEFAULT '' NOT NULL,
-    prefkey varchar(64) DEFAULT '' NOT NULL,
-    prefval BLOB DEFAULT '' NOT NULL,
-    PRIMARY KEY (user,prefkey)
-  );
-
-and for PostgreSQL:
-CREATE TABLE "userprefs" (
-   "username" varchar(128) NOT NULL,
-   "prefkey" varchar(64) NOT NULL,
-   "prefval" text,
-   CONSTRAINT "userprefs_pkey" PRIMARY KEY ("prefkey", "username")
-);
-
-Next, edit your configuration so that the preferences DSN (Data Source
-Name) is specified, this can be done using either conf.pl or via the
-administration plugin. The DSN should look something like:
-
- mysql://squirreluser:sqpassword@localhost/squirrelmail or
- pgsql://squirreluser:sqpassword@localhost/squirrelmail
-
-Note that when using the above PostgreSQL schema, you also need to change
-the prefs_user_field variable in config.php from the default 'user' to
-'username'.
-
-From now on all users' personal preferences will be stored in a
-database.
-
-Default preferences can be set by altering the $default array in
-db_prefs.php.
-
-Troubleshooting
----------------
-1. Oversized field values. Preferences are not/can't be saved
-
-Database fields have size limits. Preference table example sets 128 
-character limit to owner field, 64 character limit to preference key 
-field and 64KB (database BLOB field size) limit to value field.
-
-If interface tries to insert data without checking field limits, it
-can cause data loss or database errors. Table information functions
-provided by Pear DB libraries are not accurate and some database
-backends don't support them. Since 1.5.1 SquirrelMail provides
-configuration options that set allowed field sizes.
-
-If you see oversized field errors in your error logs - check your
-database structure. Issue can be solved by increasing database field
-sizes.
-
-If you want to get more debugging information - check setKey() function 
-in dbPrefs class. Class is stored in functions/db_prefs.php