One can only "prepend" something before some other thing, not "append".

[squirrelmail.git] / doc / db-backend.txt

diff --git a/doc/db-backend.txt b/doc/db-backend.txt
index 3712c3765889afcf8a1b0f11f43a7b06366d4c2b..76f423aa82dc896c4cddb1bc7ebb9da3466a9542 100644 (file)
--- a/doc/db-backend.txt
+++ b/doc/db-backend.txt
@@ -23,7 +23,8 @@ 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. I'm afraid I have no information on
+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.
 
 
@@ -39,7 +40,7 @@ For MySQL you would normally do something like:
  # mysqladmin create squirrelmail
 
  (from the mysql client)
- mysql> GRANT select,insert,update,delete ON squirrelmail.* 
+ mysql> GRANT select,insert,update,delete ON squirrelmail.*
               TO squirreluser@localhost IDENTIFIED BY 'sqpassword';
 
 The table structure should be similar to this (for MySQL):
@@ -55,17 +56,33 @@ The table structure should be similar to this (for MySQL):
      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
+ 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
 -----------------------------------
@@ -82,11 +99,20 @@ The table structure should be similar to this (for MySQL):
     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
+ mysql://squirreluser:sqpassword@localhost/squirrelmail or
+ pgsql://squirreluser:sqpassword@localhost/squirrelmail
 
 From now on all users' personal preferences will be stored in a
 database.
@@ -94,3 +120,23 @@ 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