External Database Configuration

3 minute read

During the CloudBees Flow server installation, if you elected not to install the built-in (default) database, you need to configure an alternate database. a CloudBees Flow enterprise license is required to configure an alternate database. For more information about supported databases, see Database Requirements . For installation instructions, see Configuring CloudBees Flow to Use an Alternate Database .

Database Interactions

Your database administrator (DBA) must create a database for use specifically by CloudBees Flow. The CloudBees Flow server interacts with the database using a JDBC driver for each of the databases that CloudBees Flow supports.

The first step in any interaction is to present user credentials to the database. This information is stored in the CloudBees Flow database.properties file as a user name plus a password. The password is stored as an encrypted string, using the “passkey” generated by the server.

Database User

For MS SQL Server and MySQL, your DBA should create a database user for use specifically by CloudBees Flow. For Oracle, your DBA must create a database user for use specifically by CloudBees Flow.

The CloudBees Flow database user must have permissions to add or delete rows from the database at all times. The database user must also have rights to create or delete tables, and add or remove a columns, indices, and constraints to a table at certain defined times.

When the CloudBees Flow server first starts up, CloudBees Flow creates a schema in the specified database, so the database user should be the owner of the CloudBees Flow database. This allows CloudBees Flow to make the required schema changes.

If the CloudBees Flow server cannot connect to the database, it continues to wait for a valid database configuration. Check the log files for a successful database connection.

Default Database Ports

The supported external databases use the following ports:

Port Used by




Microsoft SQL Server



MySQL Prerequisites

Ensuring Database User Permission to Create and Delete a Schema During an Upgrade

CloudBees supports installations only where the database user has rights to create and delete tables at all times. To upgrade the MySQL databases, the database user must also have permissions to create and delete schema (databases) for the duration of the upgrade. For security reasons, permissions granted to database users to create and delete schema in multi-tenant MySQL databases may be revoked after the upgrade process is complete.

Installing the JDBC Driver

For MySQL, the JDBC driver is not installed by the CloudBees Flow installer (for licensing reasons). It must be downloaded and installed separately from the MySQL website. For more information, go to Installing the MySQL JDBC Driver .

Setting the Default MySQL Server Timezone

By default, a MySQL instance uses the timezone from the operating system, which might cause the following bootstrap failure if the instance is using the MySQL JDBC Connector/J driver version 8.0 or later:

{noformat} 2018-07-27T03:47:35.070 | ERROR | bootstrap | | | | HikariPool | CloudBees Flow - Exception during pool initialization. java.sql.SQLException: The server time zone value 'PDT' is unrecognized or represents more than one time zone. You must configure either the server or JDBC driver (via the serverTimezone configuration property) to use a more specific time zone value if you want to utilize time zone support. at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:127) at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:95)

Setting Character Encoding to UTF-8 and Default Collation to Case-Insensitive

Tuning Memory Allocation

To tune memory allocation, see the KBEC-00038 - Improving CloudBees Flow server performance by tuning memory allocation knowledge base article.

Oracle RAC

You can configure CloudBees Flow to work with Oracle Real Application Clusters (RAC), which provides software for clustering and high availability in Oracle database environments. For instructions, see the KBEC-00064 - Using Oracle RAC Server with CloudBees Flow knowledge base article.