Introduction

I started recently setting up a TeamCity 6.5 server on a Windows 2008 R2 machine. The install was straight forward, but unfortunately TeamCity doesn’t use a mainstream database server out of the box. The good news is that you can configure TeamCity to use a different database server to run the TeamCity repository. I decided to use MySQL. This blog post has detailed steps for switching TeamCity to MySQL.

Why would someone want to switch to MySQL?

Performance

The most important reason is performance. Moving to a database server that is enterprise grade and located on a separate machine is boosting TeamCity response times significantly.

Integration

The second reason is integration. I am working on a prototype of a WordPress plug-in called LabPress that needs to be able to access TeamCity tables directly.

Step by step

Before we start here is a link to the TeamCity Documentation for switching the database engine.

Important Note: The following steps assume that you start from a clean TeamCity 6.5 system or you don’t need to migrate existing build configurations and projects to the new database.

Step 0

Install TeamCity 6.5 and MySQL, and optionally phpMyAdmin to administer MySQL via a web browser. The TeamCity install is straight forward. MySQL can be installed conveniently via the Microsoft Web Platform Installer.

Step 1

Prepare MySQL by creating a new database called e.g. teamcity. Make sure that the following database requirements are met:

• Supported versions: (5.0.40+)
• InnoDB storage engine
• UTF-8 character set
• Case-sensitive collation

Figure 1: Create teamcity database using phpMyAdmin

Step 2

Stop the the TeamCity Build Agent Service and the TeamCity Web Server.

Figure 2: Shutting down TeamCity services

Step 3

Delete the contents of the .BuildServer folder that is located in your current user’s user directory. E.g. in my case, I am logged in as Administrator, it is C:\Users\Administrator\.BuildServer.

Figure 4: Delete contents of the .BuildServer folder.

Step 4

Next start the TeamCity services that you stopped in step 2. Open a browser and navigate to your TeamCity portal. This will re-create the content of the .BuildServer folder.

Figure 5: Re-creating the content of the .BuildServer folder.

Step 5

Repeat Step 2 and shutdown the TeamCity services again.

Step 6

Still in the .BuildServer folder go to the config subfolder and create a copy of the database.mysql.properties.dist file. Rename the copy to database.properties.

Figure 6: Create a copy of database.mysql.properties.dist and rename it to database.properties

Step 7

Edit the connection string and user account settings in the database.properties file. In the connectionurl specify the servername and the database name. In my case it is jdbc:mysql://localhost:3306/teamcity (server name is localhost and database name is teamcity). Use a valid MySQL user and password. In my case it is batman for the user and catwoman for the password.

Figure 7: Configure the database.properties settings

Step 8

Download the MySQL JDBC driver from this location: http://dev.mysql.com/downloads/connector/j/ and extract the mysql-connector-java-5.1.16.zip file.  Then copy the mysql-connector-java-5.1.16-bin.jar file into the lib\jdbc subfoder of the .BuildServer folder.

Figure 8: Deploy the mysql-connector-java-5.1.16-bin.jar driver file

Step 9

Next start the TeamCity services that you stopped in step 2. Open a browser and navigate to your TeamCity portal. This time you get a warning message saying that the TeamCity requires technical maintenance.

Figure 9: Technical maintenance warning page

Step 10

When you click on the “!’m a server administrator, show me details” link you will be get instructions about what to do to get the server started again. First you need to open the teamcity-server.log file that is located in a folder similar to this one: C:\Program Files\TeamCity6.5\TeamCity\logs.

Figure 10: TeamCity server logs location

Open the teamcity-server.log file in notepad. Then you need to copy the authentication token which you will find near the end of the log. (See screenshot below)

Figure 11: Copy the authentication token from the teamcity-server.log file

Paste the token in to the “Enter the Maintenance Authentication Token” form field of the TeamCity Server Startup page. (See screenshot below) Then press the confirm button.

Figure 12: Confirm the Maintenance Authentication token

Step 11

Once successfully authenticated you get to a page that lets you create the new TeamCity database in the MySQL database server. Press the Create a new database button.

Figure 13: Create a new database

Step 12

Now you are exactly at the same point you were, when you started TeamCity for the first time after a fresh installation. You need to accept the license terms, create an Administrator account and start creating projects and build configurations.

Figure 14: Confirm license terms

Figure 15: Create Administrator account

Figure 16: Start configuring projects and build configurations

TeamCity database on MySQL

Here is the proof. My TeamCity 6.5 repository database is now running successfully on MySQL.

Figure 17: My TeamCity database is now running on MySQL

Ausblick

Since I really like to automate a lot of things, I was looking into using a PowerShell script to do the configuration changes. Stay tuned for a follow up blog post.