Database Backend

Trac offers an easily extensible layer for database support, see trac.db.api​. The following databases have been integrated in this layer:

• ​SQLite, using PySqlite, the default database
• ​PostgreSQL, using the ​psycopg2 bindings, support added as of Trac 0.9.
  • Note that psycopg1 is no longer supported and that ​pyPgSQL also presents issues for some users, see #5096.
  • Finally, see #126 for historical notes.
• ​MySQL, using MySqlDb, support added for Trac 0.10; see ​status report and #986 for historical notes.

There is work in progress for the following databases:

• ​Ingres, see #6235.
• ​Oracle, see #1874 and ​#5487.
• ​Microsoft SQL Server, see ​th:MsSqlBackendPlugin and #329.

Database Installation Instructions

SQLite

Installed out-of-the-box. The default connection string is sqlite:db/trac.db.

More parameters can be added with sqlite:db/trac.db?param1=value&param2=value. The following parameters are supported:

• extensions: Load the extensions, see also TracIni.
• timeout: Set timeout to connect the database, 10.0 is used by default.
• cursor: eager cursor pre-fetching all the rows is used by default. It can be turned off by specifying cursor= (#3446).
• journal_mode: Set the ​journal mode to the database (since 1.0.5).
• synchronous: Set the ​synchronous flag (since 1.0.5).

Known issues: see SQLite-related tickets.

Postgresql

Prerequisites:

• Have a working copy of Postgresql.
• Get the proper database driver for Python, see above.
• 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?schema=schemaname
  

Notice that the port number might be different in your Postgresql installation, eg 5433. See postgresql.conf.

Alternatively on UNIX, if the database is a local one, you can use UNIX sockets instead of TCP/IP:

postgres://user:pass@/dbname?host=/path/to/unix/socket/dir&schema=schemaname

If you are using user Trac without a password to connect through UNIX sockets to database trac and have only one project (hence no need for different schemas), your connections string would be postgres://trac:@/trac

• Note: '?host=…' is optional. Check your postgresql.conf' unix_socket_directory option if you have connection problems.

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 PostgresqlRecipe.

Note: Since Trac 0.10 the psycopg1 Postgresql driver is no longer supported due to lack of Unicode support.

Known issues: see postgres-related tickets

MySQL

MySQL is supported by Trac since 0.10, but there are some caveats, documented in more details in the MySqlDb page.

• Run trac-admin to create a new Trac environment. When prompted for a database connection string, use:

  mysql://dbuser:dbpass@host:port/dbname
  

• or when you need more options:

  mysql://dbuser[:dbpass]@host[:port]/dbname[?param1=value&param2=value]
  

The following parameters are supported since Trac 1.0:

• compress: Enable compression (0 or 1)
• init_command: Command to run once the connection is created
• named_pipe: Use a named pipe to connect on Windows (0 or 1)
• read_default_file: Read default client values from the given file (also used for SSL configuration)
• read_default_group: Configuration group to use from the default file
• unix_socket: Use a Unix socket at the given path to connect

Known issues: see mysql-related tickets.

Database Conversion

For Trac ≥ 1.3.2, the TracAdmin convert_db command allows an environment to be converted between the supported database backends. For Trac < 1.3.2, ​TracMigratePlugin provides equivalent functionality.