Setting up an External Database
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.
The current database in use is shown on the Administration | Global Settings page in the Database field and also is mentioned in
teamcity-server.log on the server startup.
HSQL* means that the internal database is in use.
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). 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 instances. Migrate 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.
TeamCity supports the following databases:
Configure the external database to be used by TeamCity (see the database-specific sections below).
Configure connection to the database via the form on the first TeamCity server start or by configuring database connection settings manually.
Note that TeamCity assumes ownership over the database schema. The database structure is created on the first start and actively modified during the upgrade to the new TeamCity version. 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.
You may also need to download the JDBC driver for your database.
Due to licensing terms, TeamCity does not bundle driver
.jarfiles for external databases. You will need to download the Java JDBC driver and put the appropriate
.jarfiles (see driver-specific sections below) from it into the < TeamCity Data Directory >/lib/jdbc directory.
Note that the
.jarfiles should be compiled for the Java version not greater than the one used to run TeamCity, otherwise you might see
Unsupported major.minor versionerrors related to the database driver classes.
The section below describes the required configuration on the database server and the TeamCity server.
On MySQL server side
Recommended database server settings:
use InnoDB storage engine
use utf8mb4 character set (or utf8 if MySQL version is 5.5.2 or earlier)
use case-sensitive collation
make sure that the time zone of the JVM running TeamCity and that of MySQL instance are the same using the
my.cnffile or by configuring time zones at the OS level
- see also recommendations for MySQL 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:
On TeamCity server side (with MySQL)
JDBC driver installation:
Download the MySQL JDBC driver from http://dev.mysql.com/downloads/connector/j/. Make sure you use a version compatible with your server. If the MySQL server version is 5.5 or newer, the JDBC driver version should be at least 5.1.23. For versions above 8, driver version 8 should be used.
mysql-connector-java-*-bin.jarfrom the downloaded archive into the
<TeamCity Data Directory>/lib/jdbcdirectory (remove the existing files there, if any). Proceed with the TeamCity setup.
On PostgreSQL server side
- Create an empty database for TeamCity in PostgreSQL.
Make sure to set up the database to use UTF8.
Grant permissions to modify this database to the user account used by TeamCity to work with the database.
- 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:
The schema has to be empty (it must not contain any tables).
On TeamCity server side (with PostgreSQL)
On Oracle server side
Create an Oracle user account/schema for TeamCity.
Make sure that the national character set of the database instance is UTF or Unicode.
CREATE TABLEpermissions to a user whose account will be used by TeamCity to work with this database.
TeamCity, on the first connect, creates all necessary tables and indices in the user's schema. (Note: TeamCity never attempts to access other schemas even if they are accessible)
On TeamCity server side (with Oracle)
1. Get the Oracle JDBC driver. Supported driver versions are 11.1 and higher. Place the following files:
ojdbc7.jardepending on your database version)
orai18n.jar(can be omitted if missing in the driver version) into the < TeamCity Data Directory >/lib/jdbc directory (remove the existing files there, if any).
It is strongly recommended to locate the driver in your Oracle server installation. Contact your DBA for the files if required. Alternatively, download the Oracle JDBC driver from the Oracle web site. Make sure the driver version is compatible with your Oracle server.
2. Proceed with the TeamCity setup.
Microsoft SQL Server
For step-by-step instructions, see the dedicated page. The current section provides key details required for the setup.
On MS SQL server side
Create a new database. As the primary collation, use the case-sensitive collation (collation name ending with
_CS_AS) corresponding to your locale.
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.
Allocate sufficient transaction log space depending on how intensively the server will be used. The recommended setup is not less than 1Gb.
Make sure SQL Server Browser is running.
Make sure TCP/IP protocol is enabled for SQL Server instance.
On TeamCity server side (with MS SQL)
Unpack the downloaded package into a temporary directory.
mssql-jdbc-*.jre8.jarfrom the just downloaded package into the < TeamCity Data Directory >/lib/jdbc directory (remove the existing files there, if any). MS SQL integrated security (Windows authentication) requires installing
sqljdbc_auth.dllfrom the driver package as per instructions.
Proceed with the TeamCity setup.
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
database.properties ), it is highly recommended switching the native driver.
The due procedure for the switch is to:
create the server backup including the database
stop the server and configure the server to use native Microsoft JDBC driver as noted in the section above
restore the database from the backup into a new MS SQL database
run the server
Database Configuration Properties
The database connection settings are stored in the < 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.
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.
TeamCity uses Apache DBCP for database connection pooling. Refer to Apache Commons documentation for detailed description of configuration properties.