Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 9.x Documentation

Documentation for Previous Versions

Icon

You are viewing the documentation of TeamCity 9.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

If you evaluated TeamCity with the internal database and want to preserve the data while switching to an external database, please refer to Migrating to an External Database.By default, TeamCity runs

On this page:

Table of Contents

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 : the internal database may crash and lose all your data (e.g. on the "out of disk space" condition). Also, the internal database can 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 instances.

The database to be used is configured on the TeamCity start: all you need to do is select the type of the database and specify database connection settings. You may also need to download the JDBC driver for your database. The database connection settings are stored in <TeamCity Data Directory>\config\database.properties file. The file is a Java properties file.

The information below provides instruction on manual configuration of the external database to be used by TeamCity.

This page covers:

Table of Contents
maxLevel2

selectingDatabase
Anchor
selectingDatabase
Anchor
selectingDatabase
selectingDatabase

Anchor
Selecting External Database Engine
Selecting External Database Engine

Selecting External Database Engine

TeamCity supports MySQL, PostgreSQL, Oracle and MS SQL databases.
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:

  • MySQL
  • PostgreSQL
  • Oracle
  • MS SQL

Anchor
generalSteps
generalSteps

General Steps

  1. If you already ran TeamCity but do not want to preserve any data, delete TeamCity Data Directory.
    Warning

    If you delete TeamCity Data Directory, all the data you entered into TeamCity will be lost. To preserve your data, please refer to the migration guide.

  2. Run TeamCity with the default settings to create the <TeamCity Data Directory>.
  3. Shutdown the TeamCity server.
  4. Perform database-specific steps described below.
  5. Start the server. NotePlease note that TeamCity actively modifies its own database schema. The Configure the external database to be used by TeamCity (see the database-specific sections below).
  6. Run the TeamCity server for the first time.
  7. 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.

...

Database Configuration Properties

The database connection settings are stored in <TeamCity Data Directory>\config\database.properties file.

TeamCity uses Apache DBCP for database connection pooling. Please refer to http://commons.apache.org/dbcp/configuration.html for detailed description of configuration properties. Example configurations for each of supported databases are provided in the sections below.

...

  1. You may also need to download the JDBC driver for your database.
    Anchor
    database_driver
    database_driver
    Anchor
    Database Driver Installation
    Database Driver Installation
    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

...

  1. .
    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.

Database-specific Steps

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

Anchor
settingUpMySql
settingUpMySql

MySQL

Supported versions

On MySQL server side

Recommended database server settings:

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

Code Block
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

InstallationJDBC 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. In Proceed with the <TeamCity Data Directory>/config folder rename database.mysql.properties.dist file to database.properties and specify the required settings in this file:
    Code Block
    
    connectionUrl=jdbc:mysql://<host>/<database name>
    connectionProperties.user=<user>
    connectionProperties.password=<password>
    
    TeamCity setup.

Anchor
settingUpPostgreSql
settingUpPostgreSql

PostgreSQL

Supported versions

On PostgreSQL server side

  1. 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 a the user which account used by TeamCity will use to work with this database.
On TeamCity server side

...

  1. Check you JRE version to determine which JDBC driver is required. If you are using Java 1.6 to run TeamCity server, you need
    • the
    JDBC4 version. For Java 1.7 (recommended) or 1.8, use the JDBC41 version.
  2. Download the required PostgreSQL JDBC driver and place it into the <TeamCity Data Directory>/lib/jdbc.
  3. In <TeamCity Data Directory>/config rename
    • database.
    postgresql.properties.dist file to database.properties and specify the required settings in this file:
    Code Block
    
    connectionUrl=jdbc:postgresql://<host>/<database name>
    connectionProperties.user=<user>
    connectionProperties.password=<password>
    

...

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 another 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:

Code Block
create schema teamcity authorization teamcity;

The

...

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

...

On TeamCity server side

Anchor
JDBCdriverVersion
JDBCdriverVersion

  1. Check you JRE version to determine which JDBC driver is required. If you are using Java 1.6 to run TeamCity server, you need the JDBC4 version. For Java 1.7 (recommended) or 1.8, use the JDBC41 version.
  2. Download the required PostgreSQL JDBC driver and place it into the <TeamCity Data Directory>/lib/jdbc. Proceed with the TeamCity setup.

Anchor
settingUpOracle
settingUpOracle

Oracle

Supported versions

On Oracle server side

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

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

    • Make sure that the national character set of the database instance is UTF or Unicode.
    • Grant the CREATE SESSION, CREATE TABLE, permissions to a user whose account will be used by TeamCity to work with this database.
      hidden-data
      for the last one: login with user "Sys" and execute SQL: "grant execute on dbms_Lock to <teamcity-user>;"
      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)
      Note

      Make sure TeamCity user has quota for accessing table space.

On TeamCity server side

  1. Get the Oracle JDBC driver.
    Supported driver versions are 11.1 and higher.
    Place the following files:
    • ojdbc6.jar
    • orai18n.jar (can be omitted if missing in the driver version) into the <TeamCity Data Directory>/lib/jdbc directory.
      Note

      The Oracle JDBC driver must be compatible with the Oracle server.

      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. In Proceed with the <TeamCity Data Directory>/config folder rename database.oracle.properties.dist file to database.properties and specify the required settings in this file:
    Code Block
    
    connectionUrl=jdbc:oracle:thin:@//<host>:1521:<servicename>
    connectionProperties.user=<user>
    connectionProperties.password=<password>
    
    TeamCity setup.

Anchor
settingUpMSSQL
settingUpMSSQL

Microsoft SQL Server

Supported versions

On MS SQL server side

Info

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, 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).
  2. 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.
    If you're going to use SSL connections, ensure that the version of MS SQL server and the version of java (on the TeamCity side) are compatible. We recommend using the latest update of SQL server:
    • SQL Server 2012 - all versions
    • SQL Server 2008R2 - Service Pack 2 or Service Pack 1 cumulative update 6
    • SQL Server 2008 - Service Pack 3 cumulative update 4
    • SQL Server 2005 - only with JDK 6 update 27 or lower on the TeamCity side
      See details on compatibility issues.
  3. Allocate sufficient transaction log space. The requirements vary depending on how intensively the server will be used. It's recommended to setup not less then 1Gb.

On TeamCity server side

Show If

You can use either MS native JDBC driver (recommended) or JTDS JDBC driver one.

native

Native driver

  1. Download the MS sqljdbc package from the Microsoft Download Center and unpack it. Let us assume the directory where you've unpacked the package into is called sqljdbc_home.
  2. Copy the sqljdbc4.jar from the just downloaded package into the TeamCity Data Directory/lib/jdbc directory. In Proceed with the <TeamCity Data Directory>/config folder rename database.mssql.properties.dist file to database.properties file and specify the following required settings in this file: Code Block connectionUrl=jdbc:sqlserver://<host>:1433;databaseName=<database name> connectionProperties.user=<user> connectionProperties.password=<password> TeamCity setup.

...

Additional conection settings:

...

To specify additional settings:

  1. Stop the TeamCity server.
  2. Configure additional settings:
    • 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:
      Code Block
      
      connectionUrl=jdbc:sqlserver://<host>\\<instance_name>:1433;databaseName=<database_name>
      ...
      
      Anchor
      MSSQLIntegratedSecurity
      MSSQLIntegratedSecurity
    • If you prefer to use MS SQL integrated security (Windows authentication),

...

    • perform additional steps:
      1. Ensure that your Java bitness is the same as Windows bitness (in other words, use 64-bit Java with 64-bit Windows and 32-bit Java with 32-bit Windows).
      2. Copy the sqljdbc_home /enu/auth/x86/sqljdbc_auth.dll (in case of 32-bit system) or sqljdbc_home /enu/auth/x64/sqljdbc_auth.dll (in case of 64-bit system) into your Windows/system32 directory (or another directory denoted in %PATH%). Ensure that there are no other sqljdbc_auth.dll files in your system).
      3. In the
    <TeamCity data directory>/config folder create file
      1. the <TeamCity Data Directory>\config\database.properties
    and
      1. file, specify the connection URL (with no user names or passwords)
    in this file
      1. as follows:
        Code Block
        
        connectionUrl=jdbc:sqlserver://<host>:1433;databaseName=<database name>;integratedSecurity=true
        
        More details about setup integrated security for MS SQL native jdbc driver can be found here (for MS SQL 2005) and here (for MS SQL 2008).
  1. Start the TeamCity server.

Anchor
jtds
jtds

Show If
JTDS driver

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

  1. Download the latest 1.2.x jTDS driver distribution file (zip file), unpack the jtds-*.jar driver jar and place it to <>/lib/jdbc. (TeamCity is not tested with the driver version 1.3+. It also requires that TeamCity server is run under JDK 1.7+).
  2. In the <>/config folder rename database.mssql.properties.dist file to database.properties and specify the required settings in this file:

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 jtds-XXX-dist\x86\SSO\ntlmauth.dll file from the JTDS driver package to <TeamCity Home>\bin (when TeamCity is run under x86 JVM), for x64 JVM use jtds-XXX-dist\x64\SSO\ntlmauth.dll file. Also setup TeamCity server (service or process) to be run under user account that has access to the database.

The jtds driver doesn't know a "default" port value, so the port number in the connectionUrl is a mandatory parameter.

Please make sure SQL Server is configured to enable TCP connections on the port used in the connectionUrl.
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>

Anchor
properties
properties

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:

Panel
bgColor#FFFFFF
borderStyledashed

Installation and Upgrade: Migrating to an External Database

...