MySQL and its MySQLdb Python bindings
The recommended versions of MySQL are those from 5.0.x series. The MariaDB variant of MySQL works as well, tested MariaDB 5.3.3, MySQLdb 1.2.3 and Trac 0.12.3.
In order to avoid Unicode and international characters problems in Trac, eg international characters turning into question marks with mysterious "Incorrect string value" errors logged, the Trac database MUST be configured with the
utf8 character set and the
utf8_bin collation type.
Also, all tables MUST be created as InnoDB type tables, because Trac uses a transaction mechanism that is not supported by MyISAM tables, see ticket:8067:5 and MySQL docs. Be aware that the cluster storage engine NDB introduces some limits for Trac (#8567).
A proper database can be created with any MySQL client, like this:
CREATE DATABASE trac DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
With MySQL version 5.5.3 and up, you can also select the mb4 variant of utf8, which enables you to store any Unicode character, not only those in the Basic Multilingual Plane. Note that you'll need at least Trac 0.12.3 for this (#9766).
CREATE DATABASE trac DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
To check character set settings for your database, issue the following commands:
mysql> USE trac; Database changed mysql> SHOW VARIABLES WHERE variable_name IN ('character_set_database', 'collation_database'); +------------------------+----------+ | Variable_name | Value | +------------------------+----------+ | character_set_database | utf8 | | collation_database | utf8_bin | +------------------------+----------+ 2 rows in set (0.01 sec) mysql>
If you have for example
utf8_ci collation, then read on to the #Conversion section below on how to change it.
If you are setting a new collation on an existing database, make sure that column collations are converted too:
mysql> SHOW FULL COLUMNS FROM `node_change`; +-------------+-------------+-----------+- | Field | Type | Collation | +-------------+-------------+-----------+- | rev | varchar(64) | utf8_bin | | path | text | utf8_bin | | node_type | varchar(32) | utf8_bin | | change_type | varchar(32) | utf8_bin | | base_path | text | utf8_bin | | base_rev | varchar(64) | utf8_bin | +-------------+-------------+-----------+- 6 rows in set (0.00 sec)
See #3884 for info about collations.
Usually, you also want to create a user and give this user access to the database created above:
GRANT ALL ON trac.* TO tracuser@localhost IDENTIFIED BY 'password';
The connection string will then be:
The recommended version is MySQL-python 1.2.2+, which must be compiled in thread-safe client mode. Earlier versions are known to be problematic.
See http://cheeseshop.python.org/pypi/MySQL-python/1.2.2, which contains links to the .tar.gz source distribution as well as pre-built Windows eggs, but for Python 2.5 only as of this writing. Python 2.6 binaries for windows can be found here, unofficial site.
Older versions can be found at the mysql-python Sourceforge project:
| ||This was the previously recommended version — unsupported|
| ||Reported to have issues (see #3645) — unsupported|
| || Was reported to solve an |
On FreeBSD this package is called
py-MySQLdb in the ports collection.
If you are using ActiveState Python 2.6 on Windows, you can install with
pypm install mysql-python.
Thread-safety is important
You should make sure that you're using a thread-safe version of the bindings.
To verify this, you can check the System Information section in the About Trac page, when you are logged with a user having the
CONFIG_VIEW or the
You should see a line reading: MySQL
server: "...", client: "...", thread-safe: 1.
If you're seeing
thread-safe: 0 instead, the MySQL-python version you're using was not correctly built. Check the following resources to see what you should do:
- MySQLdb-1.2.3/MySQLdb/README, see the Building and installing section,
Note that even if you build MySQLdb to use the thread-safe libraries, About Trac may still report that it is not thread-safe. If that happens, verify that it is thread-safe by calling
MySQLdb.thread_safe() from a standalone Python script, ie not under Apache. If the stand-alone test reports that MySQLdb is indeed thread-safe, then the problem may lie with the PHP module. For example, the Red Hat rpm for PHP is built to use the non-thread-safe MySQL libraries, and the Apache PHP module apparently gets loaded first. So when Python and MySQLdb load, they end up using the already loaded MySQL libraries, which are not thread-safe. The circumvention for this problem is to replace the non-thread-safe libs in
/usr/lib/mysql with soft links, so as to have the non-thread-safe lib names point to the thread-safe libs; restart Apache, and now Trac should be running in thread-safe mode.
Convert from MyISAM to InnoDB storage engine
InnoDB is the default storage engine for MySQL since v5.5, but older databases may be defined using MyISAM. Check which tables are not already converted:
SELECT table_name, engine FROM information_schema.tables WHERE table_schema = DATABASE();
For every table in the Trac database which is not InnoDB run the following:
ALTER TABLE `table_name` ENGINE = InnoDB;
Convert to "utf8_bin" collation
First modify the DB collation to ensure new tables will be created properly:
ALTER DATABASE `trac_database` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
Then modify the collation for tables. The command below changes the default collation for new columns and converts old columns as well. Run the following for every table:
ALTER TABLE `table_name` CONVERT TO CHARACTER SET utf8 COLLATE utf8_bin;
Convert from SQLite to MySQL
To convert from the default database SQLite to MySQL, please follow this comprehensive guide.
1.1.4 milestone tickets:
- MySQL: Primary keys are not well designed
- [Database schema] Ticket description field might be too short.
next-major-releases milestone tickets:
- trac crashing under mysql, w/ fix
- MySQL schema changes for performance
- Reduce join in query process
- trac-admin repository sync fails with very long svn commit message
not applicable milestone tickets:
- Stopped sync in 0.11.2.1
unscheduled milestone tickets:
- BLOB column can't be used in PRIMARY KEY and maximum ROW size is 8052 on NDB engine
If you have an issue, such as
OperationalError: (2006, 'MySQL server has gone away'), as in #3645, and your web frontend is Apache, you may have conflicting MySQL libraries. Read ApplicationIssues#MySQL_Shared_Library_Conflicts. Another possibility is that you've hit MySQL bug 36639, as explained in ticket:3645#comment:48.
Changing collation to utf8 may fail in MySQL 5.0.x on the MyISAM table type and display the "too big" indexes in some Trac tables. Upgrade to a higher version of MySQL and use InnoDB tables, see ticket:3659:5.
- Error when adding or viewing a ticket using MySQL
- Problems with database encoding
- Encoding problem with mysql
- initenv problem with MySQL - Access Denied
- install error (mysql)
- TypeError: unhashable type when installing trac-0.10.3 with mysql
- 'module' object has no attribute 'connect'
- InterfaceError: (0, '') after idle period with mod_wsgi 1.1/Apache 2.2.3
- trac-admin allows to init environment with mysql errors
- Trac 0.10.4 - ticket module provider fails in background
- IntegrityError when not logged in
- Formatted time via SQL command FROM_UNIXTIME fails to replace %*
- OperationalError: (2002, "Can't connect to local MySQL server through socket '/var/lib/mysql/mysql.sock' (13)")
- TypeError: int() argument must be a string or a number
- TypeError: unsupported type for timedelta microseconds component: unicode
- OperationalError: (1030, 'Got error 28 from storage engine')
- Problem with synchronizing svn commits to MySQL database
- MySQL structure case insensitive causes collision with file names
If you get an error from Python when using
trac-admin like this:
OperationalError: (1045, "Access denied for user 'tracuser'@'localhost' (using password: YES)")
There are a few possibilities:
- Try first to login on the command-line using the user
mysql -p -h localhost -u tracuser
- Created user is not yet used by MySQL. Login to the MySQL server as root with
mysql -pand type:
- The user is added but the host does not match in the MySQL user table (occurred on a FreeBSD setup). Correct this with:
mysql -p; use mysql; UPDATE user SET Host="localhost" WHERE User="tracuser"; FLUSH PRIVILEGES;