Setting up your Computer - Windows

MySQL and MySQL for Python

Transana uses a database called MySQL to store all of the analytic data. MySQL is a very powerful, very popular, open-source database program. It is available at http://www.mysql.com, as are a number of tools for working with MySQL databases. MySQL is documented extensively at that site. Due to circumstances beyond our control, we MUST use version 4.0.25 for single-user Transana, while version 4.1 or higher appears to work for multi-user Transana.

Transana uses MySQL for Python to connect to MySQL from within Python. MySQL for Python is available at http://sourceforge.net/projects/mysql-python. Documentation of this component is uneven, and the author states flatly that he "(doesn't) do Windows." Therefore, we will attempt to describe what we have gotten to work here. We currently use version 1.2.0 of MySQL for Python for the single-user version and version 1.2.2 of MySQL for Python for the multi-user version.

We deal with the installation of these two components together because they must be installed together as a pair. Furthermore, the procedure is different depending on whether you intend to work on the single-user version of Transana or the multi-user version. Both procedures are given below; be sure to use the correct one.

Setting up MySQL for Python and Embedded MySQL for single-user Transana

Please note that the procedures described here work only with MySQL 4.0.25 and MySQL for Python 1.2.0. If you are able to build a version of MySQL for Python with newer components, please please please send me the build instructions.

Unfortunately, version 4.0.25 of MySQL is difficult to find these days. Last time I looked (in November, 2008), I was able to find a source-code version, but no binary copies of that release for Windows. It may now be essentially impossible for new developers to follow these instructions. Sorry about that.

1. Make sure your Python's "Lib\site-packages" folder does not have a MySQLdb folder, and that there are not files called "_mysql.pyd", "_mysql_exceptions.py", and "_mysql_exceptions.pyc". Depending on how the previous installation was done, you need to either uninstall MySQL for Python or delete these files manually.

2. Download and install MySQL 4.0.25. [MySQL 4.0.25 is necessary, and it would be great if it were available.] For the sake of these instructions, we will assume you installed it to "C:\MySQL Server 4.0.25", though you are free to install it whereever you would like. Please note that although you need to download and install the server-based version of MySQL, you don't actually need to set it up to run.

3. Copy "C:\MySQL Server 4.0.25\Embedded\DLL\release\libmysqld.dll" to your program's source code folder. This is the embedded MySQL engine, and this file must be distributed with your program.

4. Copy the folder "C:\MySQL Server 4.0.25\share" to your program's source code folder. This folder contains the internationalization prompts for MySQL, and the prompt files must match the MySQL version being used.

5. Download and install MySQL-python.exe-embedded-1.2.0.win32-py2.4.zip. [MySQL-python.exe-embedded-1.2.0.win32-py2.5.zip is necessary, and it would be great if it were available.] (If you want to know how I built this file, click here.)

6. Finally, when you start working on Transana, you will need to edit the TransanaConstants.py file. At approximately line 33 of this file, the "singleUserVersion" variable is declared. To work with this configuration of Embedded MySQL and MySQL for Python, the singleUserVersion variable must be set to True.

singleUserVersion = True

The next step is to set up Transana's Internationalization files.

Setting up MySQL for Python and Server-based MySQL for multi-user Transana-MU

1. Make sure your Python's "Lib\site-packages" folder does not have a MySQLdb folder, and that there are not files called "_mysql.pyd", "_mysql_exceptions.py", and "_mysql_exceptions.pyc". Depending on how the previous installation was done, you need to either uninstall MySQL for Python or delete these files manually.

2. Download and install MySQL 4.1 or later. It doesn't need to be running on your development computer, but you need it running somewhere.

We would not recommend using a production MySQL server while you are developing Transana-MU, as it is possible to crash the database server during program development and testing.

Follow the installation instructions on the MySQL site. Be sure to set up at least one user account. If you are upgrading from a version 4.0.x version, please see the MySQL Web Site for instructions on migrating data.

3. Download and install MySQL-python-1.2.2.win32-py2.5.zip (If you want to know how to build this file for yourself, click here.)

4. If you haven't already done so, you will need to set things up for the multi-user version of Transana. This process is described in the Transana Multi-user Installation Guide 2.30.

5. Finally, when you start working on Transana, you will need to edit the TransanaConstants.py file. At approximately line 33 of this file, the "singleUserVersion" variable is declared. To work with this configuration of server-based MySQL and MySQL for Python, the singleUserVersion variable must be set to False.

singleUserVersion = False

We generally prefer using the multi-user version when we're working on code that affects the database, as there are a number of tools available for exploring a MySQL database, which we can use to confirm that the database is changing in the ways we expect.

The next step is to set up Transana's Internationalization files.