= Database Backend =

Initially, Trac only supported SQLite for its database backend (see PySqlite).

Postgresql support has been added as of Trac [milestone:0.9].

Mysql support will be added for Trac [milestone:0.10]
(see this [http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/342/focus=348 status report]).

More generally, since milestone:0.10, Trac offers an easily extensible layer for
Database support (see [source:trunk/trac/db/api.py trac.db.api]).

The existing backends have been refactored and integrated in this
layer. There's currently bundled support for:
 * '''[http://www.sqlite.org SQLite]''', using '''PySqlite'''
 * '''[http://www.postgresql.org PostgreSQL]''', using the
   '''[http://initd.org/projects/psycopg2 psycopg2]''' bindings. [[br]]
   ''Note that ''[http://initd.org/projects/psycopg1 psycopg1] 
   is not supported anymore and that [http://pypgsql.sourceforge.net/ pyPgSQL]
   also present issues for some users, see #5096).'' [[br]]
   Finally, see #126 for historical notes.
 * [http://www.mysql.org MySQL], using MySqlDb (see #986 for historical notes)

There's some work in progress for the following:
 * Ingres (see #6235)
 * Oracle (see #1874)


== Backend Specific Installation Instructions ==

=== SQLite === 

Should be installed out-of-the-box, provided you have installed the PySqlite bindings.

Known issues: see [query:keywords=~sqlite&status=!closed pysqlite-related tickets]


=== Postgresql ===

 * Have a working copy of Postgresql
 * Get the proper database driver for Python (see above)
 * Install [http://www.egenix.com/files/python/eGenix-mx-Extensions.html#Download-mxBASE mxBase], which is required for Postgresql support.
 * Create a database for your Trac environment
{{{
% createdb dbname
}}}
 * Run trac-admin to create a new Trac environment.  When prompted for a Database connection string, use:
{{{
postgres://user:pass@localhost:5432/dbname
}}}

Alternatively on UNIX, if the database is a local one, you can use UNIX sockets instead of TCP/IP:
{{{
postgres://user:pass@/dbname
}}}

See #4546 for more details.



See also #2441, which discusses the process of migration from SQLite to Postgresql.

For a postgresql recipe tested on CentOS4 (Red Hat -EL4) see [wiki:PostgresqlRecipe].

Note: Since Trac [milestone:0.10 0.10] the psycopg1 postgresql driver is no longer supported due to lack of unicode support.

Known issues: see [query:keywords=~postgres&status=!closed postgres-related tickets]


=== MySQL ===

It is somewhat supported by Trac since [milestone:0.10], but there are some limitations,
documented in more details in the MySqlDb page. Use this only if you don't have other choice, and be warned that there can be many issues, in particular related to the unicode support and the repository cache support. Some users are nevertheless using MySQL successfully, so it ''might'' work for you. The primary supported backends though are PostgreSQL and SQLite.


 * Have a working copy of MySQL version 4.1.12 or greater.
 * [http://sourceforge.net/projects/mysql-python MySQLdb] - Python database driver for MySQL
 * Create a database and user for your Trac environment
{{{
% mysqladmin create dbname
% mysql
> grant all privileges on dbname.* to dbuser@dbhost identified by 'dbpass';
> use dbname;
> ALTER DATABASE DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;
> quit

NB - it may be necessary to use a different collation. In some cases, where there is a 
case-sensitive collision between 2 files in svn (/myrepos/path/my.txt and /myrepos/path/MY.txt) 
utf8_general_ci is case-*in*sensitive, so utf8_bin will allow case-sensitive keys. For example 
> ALTER DATABASE DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
If during index of respository you get 1062 - Duplicate Entry this may be a cause
see ticket 3676 

}}}


 * Run trac-admin to create a new Trac environment.  When prompted for a database connection string, use:
{{{
mysql://dbuser:dbpass@host:port/dbname
}}}
 * or
{{{
mysql://dbuser:dbpass@host/dbname
}}}

Known issues: see [query:keywords=~mysql&status=!closed mysql-related tickets]

Users have reported success in [wiki:SqLiteToMySql Conversion from SQLite].

== Alternative Ideas for Database Independence ==

=== Object-Relational Mapper ===

An ORM could be used to provide a unified object interface to different RDBMS:
 * some people have been talking about using [http://sqlobject.org SQLObject] 
   to accomplish this goal of database independence.
 * [http://modeling.sourceforge.net/ Modeling]
   Another, more advanced (and more complex) OR-Mapper.
 * [http://www.sqlalchemy.org/ SQLAlchemy] seems to be also quite advanced 

Comparisons between both and more info on Python ORMs:
 * http://euc.cx/toulouse/archives/2003/04/21/evaluating_objectrelational_migration.html
 * http://google.com/search?q=SQLObject+modeling

=== Store Tickets and Wiki pages directly in the Subversion repository ===

A compelling idea with many advantages. A page advocating this plan is TighterSubversionIntegration. There has also been a discussion on the Trac mailing list. All arguments from this discussion are summarized on the page [wiki:WhySQLite WhySQLite].

=== Other Alternatives ===

 * http://wiki.w4py.org/databaseintegration.html
 * http://adodb.sourceforge.net - the fast ADODB db abstraction layer (version available for python)