Setting up an External Database
Last modified: 20 April 2023By default, TeamCity runs using an internal database based on the HSQLDB database engine. The internal database suits evaluation purposes since 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. External database is usually more reliable and provides better performance. TeamCity supports MySQL, PostgreSQL, Oracle, MS SQL and Sybase databases.
The database connection settings are configured in <
>\config\database.properties
file. If the file is not present, TeamCity automatically uses internal database.
This page covers external database setup for the first use with TeamCity. If you evaluated TeamCity with internal database and want to preserve the data while switching to an external database, please refer to Migrating to an External Database guide.
General Steps
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 Migrating to an External Database.
Run TeamCity with the default settings to create the <TeamCity Data Directory>.
Shutdown the TeamCity server.
Perform database-specific steps described below.
Start the server.
note
Please note that TeamCity actively modifies its own database schema. 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
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.
tip
For all supported databases there are template files with database-specific properties, which you can use. These templates are located in the
<TeamCity Data Directory>/config
directory and have the following name format:database.<database_type>.properties.dist
. In order to use a template, copy it todatabase.properties
and then modify it to specify correct properties for your database connections.
Database Driver Installation
Due to licensing terms, TeamCity does not bundle driver jars for external databases. You will need to download the Java driver and put the appropriate jars (see below) from it into <
>/lib/jdbc
directory (create it if necessary). In prior TeamCity versions, put the driver jar(s) into webapps/ROOT/WEB-INF/lib
directory of TeamCity installation (for .exe and .tar.gz distributions). Please note that you will need to repeat the step next time you upgrade TeamCity.
MySQL
Supported versions: (5.0.40+) Recommended database server settings:
use InnoDB storage engine
use case-sensitive collation
Installation:
Download the MySQL JDBC driver from http://dev.mysql.com/downloads/connector/j/.
database_driver MySQL connector driver jar (
mysql-connector-java-
*
-bin.jar
from the downloaded archive).Create an empty database for TeamCity in MySQL and grant permissions to modify this database to a user from which TeamCity will work with this database.
In the
<TeamCity data directory>/config
folder renamedatabase.mysql.properties
file todatabase.properties
and specify the required settings in this file:connectionUrl=jdbc:mysql://<host>/<database name> connectionProperties.user=<user> connectionProperties.password=<password>
PostgreSQL
Supported versions: 8.3+
Download the PostgreSQL JDBC driver from http://jdbc.postgresql.org/download.html and place it into the
<TeamCity data directory>/lib/jdbc
.Create an empty database for TeamCity in PostgreSQL and grant permissions to modify this database to a user from which TeamCity will work with this database. Be sure to set up it to use UTF8.
In the
<TeamCity data directory>/config
folder create filedatabase.properties
and specify the required settings in this file:connectionUrl=jdbc:postgresql://<host>/<database name> connectionProperties.user=<user> connectionProperties.password=<password>
Oracle
Supported versions: 10g, 11g
Create an Oracle user account for TeamCity (with CREATE SESSION, CREATE TABLE, EXECUTE ON SYS.DBMS_LOCK permissions).
Get the Oracle JDBC driver from your Oracle server installation, it should be two files:
ojdbc6.jar
andorai18n.jar
in case you using Java 1.6 (see also http://www.oracle.com/technetwork/database/enterprise-edition/jdbc-112010-090769.html),or
ojdbc14.jar
andorai18n.jar
for earlier Java versions. or download them from http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc_10201.html and place them to<TeamCity data directory>/lib/jdbc
. Please make sure to use the specified driver version 10.2.0.1.0 or higher, earlier driver versions may not function properly with TeamCity.
In the
<TeamCity data directory>/config
folder create filedatabase.properties
and specify the required settings in this file:connectionUrl=jdbc:oracle:thin:@<host>:1521:<servicename> connectionProperties.user=<user> connectionProperties.password=<password>
Microsoft SQL Server
Supported versions: 2005, 2008
On MS SQL server side
Create new database. Ensure that case insensitive collation is selected for this database, and it is the same as the collation of the tempdb database.
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 database schema.
On TeamCity server side
You can use either jtds (open source) or native (free for downloading).
JTDS driver
Download the latest jTDS driver ditributive file (
zip
file), unpack thejtds-*.jar
driver jar and place it to<TeamCity data directory>/lib/jdbc
.In the
<TeamCity data directory>/config
folder create filedatabase.properties
and specify the required settings in this file:connectionUrl=jdbc:jtds:sqlserver://<host>:1433/<database name> connectionProperties.user=<user> connectionProperties.password=<password>
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
. Also setup TeamCity server (service or process) to be run under user account that has access to the database.
note
The
jtds
driver doesn't know a "default" port value, so the port number in theconnectionUrl
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 adding the "instance" property into the connection URL, like the following: connectionUrl=jdbc:jtds:sqlserver://<host>:1433/<database name>;instance=sqlexpress
Native driver
Download the MS sqljdbc package from [http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a737000d-68d0-4531-b65d-da0f2a735707] and unpack it. Let us assume the directory where you've unpacked the package into is called sqljdbc_home.
Copy the sqljdbc4.jar from the just downloaded package into the
/lib/jdbc
directory.In the
<TeamCity data directory>/config
folder createdatabase.properties
file and specify the following required settings in this file:connectionUrl=jdbc:sqlserver://<host>:1433;databaseName=<database name> connectionProperties.user=<user> connectionProperties.password=<password>
If you use named instance you can specify the instance name in the connection URL, like the following:
connectionUrl=jdbc:sqlserver://<host>\\<instance_name>:1433;databaseName=<database_name> ...
If you prefer to use Windows authentication, follow the additional steps:
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).
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).
In the
<TeamCity data directory>/config
folder create filedatabase.properties
and specify the connection URL (with no user names or passwords) in this file:connectionUrl=jdbc:sqlserver://<host>:1433;databaseName=<database name>;integratedSecurity=true
Sybase
Supported version: ASE 15.0.3
TeamCity needs special configuration of the database to work appropriately. Sybase should be configured to work with Case-insensitive table names.
Ensure that Sybase server is set up to use case-insensitive table names. This can be done in Sybase server config utility:
Click on the "Configure Adaptive Server" button and select the server from the list
Click on the "Language" button
Click the button under the "Sort Order" label, and select the case-insensitive option (for example, "Dictionary order, case insensitive, accent insensitive").
Create a new empty database and apply the following options: Use the actual database name instead of
DB_NAME
.use master go create database DB_NAME on general = 4096 log on general = 1024 with override go exec master..sp_dboption DB_NAME, "allow nulls by default", true go exec master..sp_dboption DB_NAME, "select into", true go exec master..sp_dboption DB_NAME , "trunc log on chkpt" , true go exec master..sp_dboption DB_NAME, "ddl in tran", true go exec master..sp_dboption tempdb, "ddl in tran", true go checkpoint go commit go
Ensure the user that will be used by TeamCity to access the database has necessary permissions. Use the actual database name instead of
DB_NAME
, user name instead ofTC_USER
and password instead ofTC_USER_PASSWORD
.use DB_NAME go exec sp_adduser 'TC_USER', 'TC_USER_PASSWORD', null go exec sp_modifylogin TC_USER, defdb, 'DB_NAME' go grant create default to TC_USER go grant create table to TC_USER go grant create view to TC_USER go grant create rule to TC_USER go grant create procedure to TC_USER go commit go
Get the driver (file
jconn3.jar
that can be found in<Sybase home directory>/jConnect-6_0/classes
) and place it to<TeamCity data directory>/lib/jdbc
.In the
<TeamCity data directory>/config
folder create or modify thedatabase.properties
file and specify the following settings in this file, replacingDB_NAME
,TC_USER
andTC_USER_PASSWORD
with the values used during database configuration:connectionUrl=jdbc:sybase:Tds:<HOST_NAME>:5000 connectionProperties.user=<TC_USER> connectionProperties.password=<TC_USER_PASSWORD>
Thanks for your feedback!