Horde/IMP Database Installation Guide                          docs/DATABASE
=--------------------------------------------------------------------------=

$Horde: imp/docs/DATABASE,v 1.1.2.8 2000/10/02 13:28:18 bjn Exp $

Purpose of this file
~~~~~~~~~~~~~~~~~~~~
This file will hopefully ease the installation and configuration of your
database for use with IMP. The scope of the document deals primarily with
using your database with IMP and should not be considered a resource for
general database tasks.

Requirements for IMP 
~~~~~~~~~~~~~~~~~~~~
IMP Currently supports 5 databases:

    - MySQL         http://www.mysql.com/
    - PostgreSQL    http://www.postgresql.org/
    - Oracle        http://www.oracle.com/
    - Sybase        http://www.sybase.com/
    - Informix      http://www.informix.com/

MySQL was the original database supported by IMP and should at all times
(most likely) work for sure. PostgreSQL I can verify works like a champ. The
others are more recent additions or those that have less support currently.
For this reason (and the reason that I cannot verify personally that they
work or have ever configured them) they won't be mentioned much in this
file. No one using Informix has contacted us for a while, but Oracle and
Sybase are both currently used and should work.

You will need to have your database preconfigured and working on your system
before you even get to this stage. For help with this, please consult your
database specific help files.

Database Name/User/Password
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Please NOTE that the database configuration steps listed below MUST
match what is configured within Horde/IMP.

Specifically, if you change the database name, user, or password while
configuring the database (below), you will need to make the same changes
to your imp/config/defaults.php3 and phplib/local.inc files as well.

See also the horde/scripts/database/dbpasswd.sh script which can be used
to change the database password in all required locations.

Methods of Installation
~~~~~~~~~~~~~~~~~~~~~~~
There are 2 basic methods for configuring your database. The first is
manually doing it yourself. This is the method that will make sure that
things are setup as you can see step by step that things are being
configured properly.

The other method is to use one of the scripts that have been created to
automatically configure your database. These scripts should work but there
are times when things may not work the way they are supposed to. Also, when
using scripts you need to be aware that they may not be setup exactly for
your system so you need to verify them to make sure things are correct for
your particular install before using them.

Method 1: Manual Install
~~~~~~~~~~~~~~~~~~~~~~~~
For Horde 1.2.x and IMP 2.2.x you will need to set up 3 tables.  Here is a
breakdown of the tables and their elements (in MySQL format, but PostgreSQL
is similar):

    active_sessions (
      sid varchar(32) DEFAULT '' NOT NULL
      name varchar(32) DEFAULT '' NOT NULL
      val text
      changed varchar(14) DEFAULT '' NOT NULL
      PRIMARY KEY (name,sid)
      KEY changed (changed)
    )

    imp_pref (
      user varchar(120) DEFAULT '' NOT NULL
      fullname varchar(70)
      replyto varchar(70)
      lang varchar(30)
      sig text
      PRIMARY KEY (user)
    )

    imp_addr (
      user varchar(120) DEFAULT '' NOT NULL
      address varchar(120) DEFAULT '' NOT NULL
      nickname varchar(255)
      fullname varchar(255)
      PRIMARY KEY (user,address)
    )

The database name itself should be "horde".  It should already have been
created when you installed the Horde module.

Next, you'll need to create a user or give a user access to this database.
This user will need pretty much full control over this database.  The
username we use for the most part is 'hordemgr', or, in the case of
PostgreSQL, it's the name of the user who runs your web server (nobody on
most systems, www-data on stock Debian systems).  Here are a few
configuration tips for MySQL and PostgreSQL:

MySQL:

REPLACE INTO user ( host, user, password )
    VALUES (
        'localhost',
        'hordemgr',
        password('hordemgr')
    );

REPLACE INTO db ( host, db, user, select_priv, insert_priv, update_priv,
                  delete_priv, create_priv, drop_priv )
    VALUES (
        'localhost',
        'horde',
        'hordemgr',
        'Y', 'Y', 'Y', 'Y',
        'Y', 'Y'
    );

This will setup a user named 'hordemgr' with password 'hordemgr'.  The user
has been given the necessary access rights to the 'horde' database.

After setting up your tables in MySQL, you will need to run this command:

     mysqladmin -u root -p reload

--

PostgreSQL:

GRANT SELECT, INSERT, UPDATE ON imp_pref, imp_addr TO nobody;

This will give the user 'nobody' access to these tables ('imp_pref' and
'imp_addr').  Note that with PostgreSQL you do not have to add a user to the
database because PostgreSQL uses a system account (the user who runs the web
server - 'nobody', in this case) as the form of authentication for the
database.

Also, you need to make sure you allow TCP connections to your database.
PostgreSQL has a switch in one of its configuration files ('postmaster.init',
or similar) that needs to be set to 'yes':

    PGALLOWTCPIP=yes

Without this set to 'yes', IMP won't be able to connect to your database,
and you'll thus receive tons of errors.

That's about it.  You should restart your database just to make sure
everything starts up the way it should.
--

Method 2: Scripted Install
~~~~~~~~~~~~~~~~~~~~~~~~~~

Note: ALL OF THE DATABASE SCRIPTS ARE NOW DISTRIBUTED WITH HORDE. They
include the imp tables as well as the phplib active_sessions table needed
for sessions. They are in horde/scripts/database/.

The easier way of configuring your database is to use one of the scripts
that have been made available to you. Here is a breakdown of how to use each
script:

MySQL:

MySQL's script is named 'mysql_create.sql'. Use it by first logging into an
account that has full access to the database or by using a switch to
explicitly select one such user. We'll demonstrate both methods below.

Before using any of these scripts, please look over them to ensure that any
system-specific settings (or personal choices) are set to your desired
settings (eg. 'username', etc.).

MySQL: 
------
# su - root

# mysql < mysql_create.sql
  - or -
# mysql -password=rootspasswordformysql < mysql_create.sql

Or, without changing to a priveliged user such as 'root':

% mysql -user=username < mysql_create.sql
  - or -
% mysql -user=username -password=rootspasswordformysql < mysql_create.sql

That's it.  Restart MySQL, and try it out.


PostgreSQL:
-----------
# su - postgres  (or whoever your database runs as... usually postgres)
# psql template1 < pgsql_create.sql

That's it.  Restart PostgreSQL, and try it out.


Oracle:
-------
Run 'sqlplus'. Login, then run '@oracle_create.sql' (please note you may
not need the .sql at the end).

That should be it. Restart Oracle just to be sure, and try it.


Sybase:
-------
First, you'll need to create the database.  From 'isql' run:

    create database horde

Next, you should (recommended) create a login to use with this database.
The 'isql' command for this is:

    sp_addlogin <username> <password>

Next you need to change the ownership of the database to this new user.  The
'isql' command for this is:

    sp_changedbowner <username>

After that, you just need to set up your tables within the database.  To do
that, just run this command from the command line:

    isql -i sybase_create.sql -U<username> -P<password>


Informix:
---------
Log into 'dbaccess' and run 'ifmx_create.sql'.

Restart Informix, and try it out.


Additional Notes
~~~~~~~~~~~~~~~~
This is by far not a complete HOWTO. This is just a compiled list of what
people have contributed so far. If you have tips, ideas, suggestions or
anything else that you think could help others in setting up their database
for use with IMP, please let us know.
