=============
MySQL Backend
=============

:version: $Revision: 1.8 $

This notes detail the MySQL backend for the Roundup issue tracker.


Prerequisites
=============

To use MySQL as the backend for storing roundup data, you also need 
to install:

1. MySQL RDBMS 4.0.16 or higher - http://www.mysql.com. Your MySQL
   installation MUST support InnoDB tables (or Berkeley DB (BDB) tables
   if you have no other choice). If you're running < 4.0.16 (but not <4.0)
   then you'll need to use BDB to pass all unit tests. Edit the
   ``roundup/backends/back_mysql.py`` file to enable DBD instead of InnoDB.
2. Python MySQL interface - http://sourceforge.net/projects/mysql-python

:Note: the InnoDB implementation has a bug that Roundup tickles. See
       http://bugs.mysql.com/bug.php?id=1810

Running the MySQL tests
=======================

Roundup tests expect an empty MySQL database. Two alternate ways to provide 
this:

1. If you have root permissions on the MySQL server, you can create 
   the necessary database entries using the follwing SQL sequence. Use
   ``mysql`` on the command line to enter::

       CREATE DATABASE rounduptest;
       USE rounduptest;
       GRANT ALL PRIVILEGES ON rounduptest.* TO rounduptest@localhost
            IDENTIFIED BY 'rounduptest';
       FLUSH PRIVILEGES;

2. If your administrator has provided you with database connection info, 
   you can modify MYSQL_* constants in the file test/test_db.py with 
   the correct values.

Note that the MySQL database should not contain any tables. Tests will not 
drop the database with existing data.


Additional configuration
========================

To initialise and use the MySQL database backend, roundup's configuration 
file (config.py in the tracker's home directory) should have the following
entries::

    MYSQL_DBHOST = 'localhost'
    MYSQL_DBUSER = 'rounduptest'
    MYSQL_DBPASSWORD = 'rounduptest'
    MYSQL_DBNAME = 'rounduptest'
    MYSQL_DATABASE = ( MYSQL_DBHOST, MYSQL_DBUSER, MYSQL_DBPASSWORD,
        MYSQL_DBNAME )

Fill in the first four entries with values for your local MySQL installation 
before running "roundup-admin initialise".  Use the commands in the `Running the
MySQL tests` to set up a database if you have privilege, or ask your local
administrator if not.


Showing MySQL who's boss
========================

If things ever get to the point where that test database is totally hosed,
just::

  $ su -
  # /etc/init.d/mysql stop
  # rm -rf /var/lib/mysql/rounduptest
  # /etc/init.d/mysql start

and all will be better (note that on some systems, ``mysql`` is spelt
``mysqld``).