This page covers external database setup for the first use with TeamCity 8.1 and above. For earlier versions, select the documentation corresponding to your TeamCity version.

TeamCity stores build history, users, build results and some run time data in an SQL database. See also the description of what is stored where on the Manual Backup and Restore page.

If you evaluated TeamCity with the internal database which is not recommended for production, please refer to Migrating to an External Database.

On this page:

Default Internal Database

On the first TeamCity run, using an internal database based on the HSQLDB database engine is suggested by default. The internal database suits evaluation purposes only; it works out of the box and requires no additional setup.

However, we strongly recommend using an external database as a back-end TeamCity database in a production environment. An external database is usually more reliable and provides better performance: the internal database may crash and lose all your data (e.g. on the "out of disk space" condition). Also, the internal database may become extremely slow on large data sets (say, database storage files over 200Mb). Please also note that our support does not cover any performance or database data loss issues if you are using the internal database.

In short, do not EVER use internal HSQLDB database for production TeamCity instancesMigrate to an external database the moment you start to rely on the data stored in TeamCity server.

Selecting External Database Engine

As a general rule you should use the database that better suits your environment and that you can maintain/configure better in your organization.
While we strive to make sure TeamCity functions equally well under all of the supported databases, issues can surface in some of them under high TeamCity-generated load.

You may also want to estimate the required database capacity.

Supported Databases

TeamCity supports the following databases:

General Steps

  1. Configure the external database to be used by TeamCity (see the database-specific sections below).
  2. Run the TeamCity server for the first time.
  3. Select an external database to be used and specify the database connection settings.
    If required, you can later manually modify your database connection settings.
    (warning) Note that TeamCity creates its own database schema on the first start and actively modifies it during the upgrade. The schema is not changed when TeamCity is working normally.
    The user account used by TeamCity should have permissions to create new, modify and delete existing tables in its schema, in addition to usual read/write permissions on all tables.
  4. You may also need to download the JDBC driver for your database.
    Due to licensing terms, TeamCity does not bundle driver jars for external databases. You will need to download the Java JDBC driver and put the appropriate .jar files (see driver-specific sections below) from it into the <TeamCity Data Directory>/lib/jdbc directory.
    Please note that the .jar files should be compiled for the Java version not greater than the one used to run TeamCity, otherwise you might see "Unsupported major.minor version" errors related to the database driver classes.

See additional information if Amazon Aurora DB Cluster is used as the TeamCity database server.

Database-specific Steps

The section below describes the required configuration on the database server and the TeamCity server.

MySQL

Supported versions

On MySQL server side

Recommended database server settings:

The MySQL user account that will be used by TeamCity must be granted all permissions on the TeamCity database.
This can be done by executing the following SQL commands from the MySQL console:

create database <database-name> collate utf8_bin;
create user <user-name> identified by '<password>';
grant all privileges on <database-name>.* to <user-name>;
grant process on *.* to <user-name>;

On TeamCity server side (with MySQL)

JDBC driver installation:

  1. Download the MySQL JDBC driver from http://dev.mysql.com/downloads/connector/j/. If the MySQL server version is 5.5 or newer, the JDBC driver version should be 5.1.23 or newer.
  2. Place mysql-connector-java-*-bin.jar from the downloaded archive into the <TeamCity Data Directory>/lib/jdbc. Proceed with the TeamCity setup.

Some considerations on Aurora clustering setup:
https://confluence.jetbrains.com/display/TCINT/Using+AWS+Aurora+Database+Cluster
See also https://youtrack.jetbrains.com/issue/TW-46926

PostgreSQL

Supported versions

On PostgreSQL server side

  1. Create an empty database for TeamCity in PostgreSQL.
  2. See also recommendations for PostgreSQL server settings

TeamCity does not specify which schema will be used for its tables. By default, PostgreSQL creates tables in the 'public' schema ('public' is the name of the schema). TeamCity can also work with other PostgreSQL schemas. To switch to a different schema, do the following:
Create a schema named exactly as the user name: this can be done using the pgAdmin tool or with the following SQL:

create schema teamcity authorization teamcity;

The schema has to be empty (it must not contain any tables).

On TeamCity server side (with PostgreSQL)

Download the required PostgreSQL JDBC42 driver and place it into the <TeamCity Data Directory>/lib/jdbc. Proceed with the TeamCity setup.

Set the connectionProperties.autosave=conservative in the database properties file to address this issue with PostgreSQL JDBC driver.

Oracle

Supported versions

On Oracle server side

  1. Create an Oracle user account/schema for TeamCity.

    TeamCity uses the primary character set (char, varchar, clob) for storing internal text data and the national character set (nchar2, nvarchar, nclob) to store the user input and data from external systems, like VCS, NTLM, etc.

On TeamCity server side (with Oracle)

  1. Get the Oracle JDBC driver.
    Supported driver versions are 11.1 and higher.
    Place the following files:
  2. Proceed with the TeamCity setup.

Microsoft SQL Server

Supported versions

For step-by-step instructions, see the dedicated page. The current section provides key details required for the setup.

On MS SQL server side

TeamCity uses the primary character set (char, varchar, text) for storing internal text data and the national character set (nchar, nvarchar, ntext) to store the user input and data from external systems, like VCS, NTLM, etc.

  1. Create a new database. As the primary collation, use the case-sensitive collation (collation name ending with '_CS_AS') corresponding to your locale.
  2. Create a TeamCity user and ensure that this user is the owner of the database (grant the user dbo rights), which will give the user the ability to modify the database schema.
    For SSL connections, ensure that the version of MS SQL server and the TeamCity version of java are compatible. We recommend using the latest update of SQL server.
  3. Allocate sufficient transaction log space depending on how intensively the server will be used. The recommended setup is not less then 1Gb.
  4. Make sure SQL Server Browser is running.
  5. Make sure TCP/IP protocol is enabled for SQL Server instance.
  6. Make sure that the "no count"  setting is disabled: the enabled "no count" setting prevents TeamCity from starting queued builds. 

On TeamCity server side (with MS SQL)

  1. Download the Microsoft JDBC driver v6.0+ (sqljdbc_6.0.x package, .exe or .tar.gz depending on your TeamCity server platform) from the Microsoft Download Center.
  2. Unpack the downloaded package into a temporary directory.
  3. Copy the sqljdbc42.jar corresponding to jre8 from the just downloaded package into the TeamCity Data Directory/lib/jdbc directory. For driver version 6.2 use mssql-jdbc-*.jre8.jar file instead. MS SQL integrated security (Windows authentication) requires installing sqljdbc_auth.dll from the driver package as per instructions.
  4. Proceed with the TeamCity setup.

On MS SQL server side
TeamCity uses the primary character set (char, varchar, text) for storing internal text data and the national character set (nchar, nvarchar, ntext) to store the user input and data from external systems, like VCS, NTLM, etc.




Create a new database. As the primary collation, it is recommended to use the collation corresponding to your locale. We also suggest using the case-sensitive collation (collation name ending with '_CS_AS'), which is mandatory for the certain functionality (like using non-Windows build agents).
Create TeamCity user and ensure that this user is the owner of the database (grant the user dbo rights). This requirement is necessary because the user needs to have ability to modify the database schema.


Allocate sufficient transaction log space. The requirements vary depending on how intensively the server will be used. It's recommended to set up not less than 1Gb.
Make sure TCP/IP protocol is enabled for SQL Server instance and that SQL Server Browser is running
Make sure that the "no count"  setting is disabled: the enabled "no count" setting prevents TeamCity from starting queued builds. Since TeamCity 10, TeamCity detects the presence of this unsupported option on the server startup and tries to unset it for the current connection, but it is strongly recommended to disable the setting in the database defaults as follows: In MS SQL Server Management Studio, connect to your database server.
Right-click the server instance in Object Explorer.
Choose Properties.
Select the Connections tab.
In the Default Connection Options frame, "no count" must be unchecked.

It is recommended to monitor the database performance regularly. For example, perform reindexing once every several months.

On TeamCity server side (with MS SQL)
{show-if}
You can use either [MS native JDBC driver|#native] (recommended) or [JTDS JDBC driver|#jtds] one.

h5. Native driver
{show-if}
Download the MS sqljdbc_6.0.x package (.exe or .tar.gz depending on your TeamCity server platform) from the Microsoft Download Center.
Unpack the downloaded package into a temporary directory.
Copy the sqljdbc42.jar from the just downloaded package into the TeamCity Data Directory/lib/jdbc directory. The Integrated security setup will need additional steps, see below.
Proceed with the TeamCity setup.

Additional connection settings
To specify additional settings, change <TeamCity Data Directory>\config\database.properties file while TeamCity server is not running:
If you use a named instance, you need to manually modify the <TeamCity Data Directory>\config\database.properties file and specify the instance name in the connection URL as follows:
connectionUrl=jdbc:sqlserver://<host>\\<instance_name>:1433;databaseName=<database_name>

If you prefer to use MS SQL integrated security (Windows authentication), it is required to install sqljdbc_auth.dll from the driver package. Incorrect installation of the dlls often results in the "This driver is not configured for integrated authentication" error
Determine the bitness of TeamCity server Java/JVM in use. You might want to use JVM with the same bitness as Windows. Note that you will need to perform manual switch to 64-bit JVM as by default the 32-bit JVM is bundled.
Copy the <sql_jdbc_home>/enu/auth/x86/sqljdbc_auth.dll (in case of 32-bit Java) or <sql_jdbc_home>/enu/auth/x64/sqljdbc_auth.dll (in case of 64-bit Java) file into a directory and specify the directory in the "-Djava.library.path=DIRECTORY_WITH_DLL" TeamCity server JVM option. Reportedly, as alternative to adding the JVM option, you can also copy the .dll into Windows/System32 directory and ensure that there are no other sqljdbc_auth.dll files in your system (in the PATH-listed directories).
In the <TeamCity Data Directory>\config\database.properties file, specify the connection URL (with no user names or passwords) as follows:
connectionUrl=jdbc:sqlserver://<host>:1433;databaseName=<database name>;integratedSecurity=true

More details about setting up integrated security for MS SQL JDBC driver can be found in the Microsoft documentation.
{show-if}
h5. JTDS driver

{note}The JTDS driver does not support Unicode operations. Using the Microsoft native JDBC driver is recommended.{note}

# Download the latest 1.2.x [jTDS driver|http://jtds.sourceforge.net/] distribution file ({{zip}} file), unpack the {{jtds-*.jar}} driver jar and place it to {{<}}{{[TeamCity Data Directory]}}{{>/lib/jdbc}}. (TeamCity is not tested with the driver version 1.3\+. It also requires that TeamCity server is run under JDK 1.7+).
# In the {{<}}{{[TeamCity Data Directory]}}{{>/config}} folder rename {{database.mssql.properties.dist}} file to {{database.properties}} and specify the required settings in this file:
{code}
connectionUrl=jdbc:jtds:sqlserver://<host>:1433/<database name>
connectionProperties.user=<user>
connectionProperties.password=<password>
connectionProperties.instance=<instance_name>
{code}

To use Windows authentication (SSPI) to connect to your SQL Server database, make sure there are no {{connectionProperties.user}} and {{connectionProperties.password}} properties specified in the {{database.properties}} file and also copy the {{jtds-XXX-dist\x86\SSO\ntlmauth.dll}} file from the JTDS driver package to {{<[TeamCity Home|TeamCity Home Directory]>\bin}} (when TeamCity is run under x86 JVM); for [x64 JVM|Installing and Configuring the TeamCity Server#Using 64 bit Java to Run TeamCity Server], use the {{jtds-XXX-dist\x64\SSO\ntlmauth.dll}} file. Also setup the TeamCity server (service or process) to be run under the  user account that has access to the database.

{note} The {{jtds}} driver is not aware of the "default" port value, so the port number in the {{connectionUrl}} is a mandatory parameter.{note}

{note}
Make sure your SQL Server is configured to enable TCP connections on the port used in the {{connectionUrl}}.
{note}

If you use named instance you can specify the instance name by following means:
* Add the "instance" property  into the connection URL, like the following:
{{connectionUrl=jdbc:jtds:sqlserver://<host>:1433/<database name>;instance=sqlexpress}}
* Or, specify corresponding property in the {{database.properties}} file:
{{connectionProperties.instance=<instance_name>}}

{show-if}

jTDS driver

It is not recommended to use jTDS JDBC driver. There are at least known issues with using Unicode characters when the driver is in use.

If you use the driver ("jtds" text appears in the connectionUrl of database.properties), it is highly recommended to switch the native driver.

The due procedure for the switch is to:

 

Database Configuration Properties

The database connection settings are stored in <TeamCity Data Directory>\config\database.properties file. The file is a Java properties file. You can modify it to specify required properties for your database connections.

TeamCity uses Apache DBCP for database connection pooling. Please refer to http://commons.apache.org/dbcp/configuration.html for detailed description of configuration properties.

(warning) For all supported databases there are template files with database-specific properties located in the <TeamCity Data Directory>/config directory. The files have the following naming format: database.<database_type>.properties.dist and can be used as a reference on the required settings.

See also:

 

Installation and Upgrade: Common database-related problems | Migrating to an External Database
Concepts: TeamCity Data Directory
Administrator's Guide: TeamCity Data Backup