Connecting Bitbucket Server to SQL Server
This page describes how to connect Bitbucket Server to a Microsoft SQL Server database. You can connect Bitbucket to a SQL server either at install time using the Setup Wizard, or later using the Using the Database Migration Wizard. These instructions assume that you already have SQL Server installed and running.
The overall process for using a SQL Server database with Bitbucket Server is:
- Install SQL Server where it is accessible to Bitbucket Server.
- Create a database and user on the SQL Server instance for Bitbucket Server to use.
- Install Bitbucket Server on Windows, or on Linux or Mac. See the Bitbucket Server installation guide.
See Supported platforms for the versions of SQL Server supported by Bitbucket Server.
Prerequisites
Back up your current database
If you are migrating your data from the internal Bitbucket Server database, back up the Bitbucket Server home directory.
If you are migrating your Bitbucket Server 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 Server database
Before you can use Bitbucket Server with SQL Server, you must set up SQL Server as follows:
| Step | Notes |
| Create a database | e.g. bitbucket. Remember this database name for the connection step below. |
| Set the collation type | This should be case-sensitive, for example, 'SQL_Latin1_General_CP1_CS_AS' (CS = Case Sensitive). |
| Set the isolation level | Configure the database to use the isolation level, Read Committed with Row Versioning. |
| Create a database user | e.g. bitbucketuser. This database user should not be the database owner, but should be in the db_owner role. It needs to be in this role during setup and at all points when Bitbucket Server is running due to the way Bitbucket Server interacts with the database. See SQL Server Startup Errors. Remember this database user name for the connection step below. |
| Set database user permissions | The Bitbucket Server database user has permission to connect to the database, and to create and drop tables, indexes and other constraints, and insert and delete data, in the newly-created database. |
| Enable TCP/IP | Ensure that TCP/IP is enabled on SQL Server and that SQL Server is listening on the correct port (which is 1433 for a default SQL Server installation). Remember this port number for the connection step below. |
| Check the authentication mode | Ensure that SQL Server is operating in the appropriate authentication mode. By default, SQL Server operates in 'Windows Authentication Mode'. However, if your user is not associated with a trusted SQL connection, 'Microsoft SQL Server, Error: 18452' is received during Bitbucket Server startup, and you will need to change the authentication mode to 'Mixed Authentication Mode'. Bitbucket Server instances running on Windows are also able to support SQL Server databases running in 'Windows Authentication Mode'. This is described at the bottom of this page and it has to be manually configured: Connecting Bitbucket Server to SQL Server - Use Integrated Authentication (Optional) |
| Check that SET NOCOUNT is off | Ensure that the SET NOCOUNT option is turned off. You can do that in SQL Server Management Studio as follows:
|
Note that Bitbucket Server will generally require about 25–30 connections to the database.
Note also that Bitbucket Server 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.
Here is an example of how to create and configure the SQL Server database from the command line. When Bitbucket Server and SQL Server run on the same physical computer (accessible through localhost), run the following commands (replacing bitbucketuser and password with your own values):
SQL Server> CREATE DATABASE bitbucket
SQL Server> GO
SQL Server> USE bitbucket
SQL Server> GO
SQL Server> ALTER DATABASE bitbucket SET ALLOW_SNAPSHOT_ISOLATION ON
SQL Server> GO
SQL Server> ALTER DATABASE bitbucket SET READ_COMMITTED_SNAPSHOT ON
SQL Server> GO
SQL Server> ALTER DATABASE bitbucket COLLATE SQL_Latin1_General_CP1_CS_AS
SQL Server> GO
SQL Server> SET NOCOUNT OFF
SQL Server> GO
SQL Server> USE master
SQL Server> GO
SQL Server> CREATE LOGIN bitbucketuser WITH PASSWORD=N'password', DEFAULT_DATABASE=bitbucket, CHECK_EXPIRATION=OFF, CHECK_POLICY=OFF
SQL Server> GO
SQL Server> ALTER AUTHORIZATION ON DATABASE::bitbucket TO bitbucketuser
SQL Server> GOThis creates an empty SQL Server database with the name bitbucket, and a user that can log in from the host that Bitbucket Server is running on who has full access to the newly created database. In particular, the user should be allowed to create and drop tables, indexes and other constraints.
Connect Bitbucket Server to the SQL Server database
You can now connect Bitbucket Server to the SQL Server database, either:
- when you run the Setup Wizard, at install time,
- when you wish to migrate to SQL Server, either from the embedded database or from another external database.
When running the Setup Wizard at install time
- Select External at the 'Database' step.
- Select SQL Server for Database Type.
- Complete the form. See the table below for details.
- Click Next, and follow the instructions in the Bitbucket Server Setup Wizard.
When migrating to SQL Server
- In the Bitbucket Server administration area, click Database (under 'Settings').
- Click Migrate database.
- Select SQL Server for Database Type.
- Complete the form. See the table below for details.
- Click Start Migration.
| Hostname | The hostname or IP address of the computer running the database server. |
| Port | The TCP port with which Bitbucket Server can connect to the database server. The default value of 1433 is the default port that SQL Server runs against. You can change that if you know the port that your SQL Server instance is using. |
| Database name | The name of the database that Bitbucket Server should connect to. |
| Database username | The username that Bitbucket Server should use to access the database. |
| Database password | The password that Bitbucket Server should use to access the database. |
Named Instances
If you have a named instance on your server, you will need to manually edit the bitbucket.properties file as described on the Connecting to named instances in SQL Server from Bitbucket Server Knowledge Base article.
Use Integrated Authentication or 'Windows Authentication Mode' (Optional)
Windows authentication is only available for Bitbucket Server instances running on Windows. It cannot be used on Linux because Microsoft does not provide shared objects for it. You will either need to run Bitbucket Server on Windows, allowing you to use Windows security, or you will need to enable mixed-mode authentication for SQL Server if you are running Bitbucket Server on Linux. Unfortunately, there are no other options at this time.
Integrated authentication uses a native DLL to access the credentials of the logged-in user to authenticate with SQL Server. The native DLLs for both 32- and 64-bit systems are included in the distribution; there is no need to download the entire package from Microsoft.
Bitbucket Server does not currently support configuring the system to use integrated authentication from the UI (Vote for it! STASH-3035 - Getting issue details... STATUS ). This means you can't currently migrate to SQL Server with integrated authentication, nor can you configure Bitbucket Server to use SQL Server with integrated authentication during initial setup. However, if Bitbucket Server has already been configured to use SQL Server (for example, when the Setup Wizard was run at first use), you can enable integrated authentication by directly modifying Bitbucket Server's configuration, as follows:
- Based on the JVM being used to run Bitbucket Server, rename either the
x64orx86DLL tosqljdbc_auth.dllinlib/native. Note that running on Windows x64 does not require the use of thex64DLL; you should only use thex64DLL if you are also using a 64-bit JVM. - In
_start-webapp.bat, aJVM_LIBRARY_PATHvariable has already been defined. Simply remove the leadingrem. Note that if you are putting the native DLL in an alternative location, you may need to change the value to point to your own path. The value of theJVM_LIBRARY_PATHvariable will automatically be included in the command line when Tomcat is run usingstart-bitbucket.bat. - Edit the
%BITBUCKET_HOME%\shared\bitbucket.propertiesfile to include;integratedSecurity=truein thejdbc.urlline. Note thatjdbc.userandjdbc.passwordwill no longer be used to supply credentials but they must still be defined – Bitbucket Server will fail to start if these properties are removed. - Ensure the Bitbucket Server process or service is running as the correct user to access SQL Server. (Note that this user is generally a Windows Domain User Account, but should not be a member of any administrators groups, that is local, domain, or enterprise.)
It is also possible to configure integrated authentication over Kerberos, rather than using the native DLLs. Details for that are included in the JDBC documentation.
Install the JDBC driver
This section is only relevant to some distributions of Bitbucket Server, for example if you are running Bitbucket Server via the Atlassian Plugin SDK, or have built Bitbucket Server from source.
If the SQL Server JDBC driver is not bundled with Bitbucket Server, you will need to download and install the driver yourself.
- Download the appropriate JDBC driver from the Microsoft download site.
- Install the driver file to your
<Bitbucket home directory>/libdirectory (for Bitbucket Server 2.1 or later). - Stop, then restart, Bitbucket Server. See Starting and stopping Bitbucket Server.
If Bitbucket Server was configured to use Microsoft SQL Server by manually entering a JDBC URL, please refer to this guide.