Connect Bitbucket to Oracle
This page describes how to connect Bitbucket Data Center to a Oracle database.
The overall process for using a Oracle database with Bitbucket is:
- Install Oracle where it is accessible to Bitbucket.
- Create a database and user on the Oracle server for Bitbucket to use.
- Install Bitbucket on Windows, or on Linux or Mac. See Getting started.
- Either:
- at Bitbucket install time, run the Setup Wizard to connect Bitbucket to the Oracle database, or
- at a later time, migrate Bitbucket to the Oracle database. See Using the Database Migration Wizard.
It is assumed here that you already have Oracle installed and running. For information about installing Oracle and creating Oracle databases, see the Oracle documentation pages. For the versions of Oracle supported by Bitbucket see Supported platforms.
Prerequisites
Backup
If you are migrating your data from the internal Bitbucket database, back up the home directory.
If you are migrating your Bitbucket data from a different external database, back up that database by following the instructions provided by the database vendor before proceeding with these instructions.
See Data recovery and backups.
Create the Bitbucket database
Before you can use Bitbucket with Oracle, you must set up Oracle as follows:
- Ensure that you have a database instance available for Bitbucket (either create a new one or use an existing one)
The character set of the database must be set to eitherAL32UTF8orUTF8, to support storage of Unicode data as per the Oracle documentation.
Note that it is important to the proper operation of Bitbucket that the database store its data in a case-sensitive manner. By changing the values of the NLS_COMP and/or NLS_SORT variables, it is possible to cause Oracle to perform its searches in a case-insensitive manner. We therefore strongly recommend that those variables be left at their default values. - Create a user that Bitbucket will connect as (e.g.
bitbucket).
Remember the database user name; it will be used to configure Bitbucket's connection to the database in subsequent steps.
The username can consist of one or more words. If you're using more than one word, you need to separate them with an underscore (_), not with a hyphen (-).- When you create a user in Oracle, a schema is automatically created.
- It is strongly recommended that you create a new database user for use by Bitbucket rather than sharing one that is used by other applications or people.
- Grant the Bitbucket user
connectandresourceroles only. Theconnectrole is required to set up a connection, whileresourcerole is required to allow the user to create objects in its own schema. - Note that Bitbucket requires the database to keep idle connections alive for at least 10 minutes. If the database is configured with less than a 10 minute connection timeout, there will be seemingly random connection errors.
The format of the command to create a user in Oracle is:
CREATE USER <user>
IDENTIFIED BY <password>
DEFAULT TABLESPACE USERS
QUOTA UNLIMITED ON USERS;
GRANT CONNECT, RESOURCE to <user>;Here is a simple example, using SQL*Plus, of how one might create a user called bitbucket with password jdHyd6Sn21 in tablespace users, and grant the user a minimal set of privileges. When you run the command on your machine, remember to replace the username, password and tablespace names with your own values.
CREATE USER bitbucket
IDENTIFIED BY jdHyd6Sn21
DEFAULT TABLESPACE USERS
QUOTA UNLIMITED ON USERS;
GRANT CONNECT, RESOURCE to bitbucket;This creates an empty Oracle schema with the name bitbucket, and a user that can log in from the host that Bitbucket is running on and who has full access to the newly created schema. In particular, the user is allowed to create sessions and tables.
Bitbucket will generally require about 25–30 connections to the database. The maximum number of connections is a configurable system property – see Database pool.
Download and install the Oracle thin driver
Due to licensing restrictions, we can’t bundle an Oracle driver with Bitbucket. To make your database driver is available to Bitbucket:
Stop Bitbucket.
Delete the bundled Oracle driver .jar file from your
<installation-directory>/app/WEB-INF/libdirectory. The driver file will be called something likeojdbc8-<version>-atlassian-hosted.jarwhere<version>is the version of the driver.Head to Oracle Database JDBC driver and Companion Jars Downloads. Download the appropriate driver. The driver file will be called something like
ojdbc8.jar.Drop the .jar file in your
<installation-directory>/app/WEB-INF/libdirectory.Oracle JDBC driver versions 12.2.0.1 and later have a known bug that sometimes causes JDBC connections to fail with a Socket Read Interrupted error. If you're using an affected version of the driver, you'll need to add the
-Doracle.jdbc.javaNetNio=falseJVM argument in theJVM_SUPPORT_RECOMMENDED_ARGSenvironment variable.Restart Bitbucket.
Go to
http://localhost:>in your browser to continue the setup process.
Connect Bitbucket to the Oracle database
You can now connect Bitbucket to the Oracle database, either:
- when you run the Setup Wizard at install time
- when you wish to migrate to Oracle either from the embedded Bitbucket database or from another external database
When running the Setup Wizard at install time
At the Database step, select External.
For Database type, select Oracle.
- Complete the form:
Hostname – the hostname or IP address of the computer running the database server.
Port – the TCP port with which Bitbucket can connect to the database server. The default value is the default port that Oracle runs against. You can change that if you know the port that your Oracle instance is using.
Database name – the name of the database that Bitbucket should connect to.
Database username – the username that Bitbucket should use to access the database.
Database password – the password that Bitbucket should use to access the database.
- Select Next and follow the instructions in the Bitbucket setup wizard.
When migrating to Oracle
Go to Bitbucket administration > Settings > Database.
- Select Migrate database.
For Database Type, select Oracle.
- Complete the form:
Hostname – the hostname or IP address of the computer running the database server.
Port – the TCP port with which Bitbucket can connect to the database server. The default value is the default port that Oracle runs against. You can change that if you know the port that your Oracle instance is using.
Database name – the name of the database that Bitbucket should connect to.
Database username – the username that Bitbucket should use to access the database.
Database password – the password that Bitbucket should use to access the database.
- Select Start migration.
