Updating JDBC URL for Microsoft SQL Server

With JIRA 7.5, we've shipped a new Microsoft JDBC Driver 6.2.1 for SQL Server, which requires an update to the driver's URL in the dbconfig.xml file. In most cases, you can make the update automatically by running the JIRA configuration tool. However, if you've customized your DB configuration by adding properties to the URL, you'll need to adjust your URL to the new pattern manually.

Running the JIRA configuration tool

If you haven't made any changes to the JDBC URL, the JIRA Configuration Tool can be used to automatically update the configuration file:

  1. Go to <installation-directory>/bin, and run the config.bat / config.sh file
  2. Click Save. Your configuration will be updated
  3. Restart JIRA

If you're running on Windows, it's possible you don't have the necessary JRE_HOME or JAVA_HOME environment variable set (so the configuration tool will not run). In that case, you can configure the environment variable manually and restart Windows for it to take effect, and then run the configuration tool. Alternatively, you can update the URL manually as shown below.

Updating the URL Manually

If for some reason you cannot run the configuration tool (or it hasn't corrected the problem) you'll need to edit dbconfig.xml manually.

  1. Shut down JIRA, and back up your current <jira-home>/dbconfig.xml file.
  2. Adjust the url for the database to the following:
  3. Adjust the driver-class for the database to the following:

The new connection string URL takes the following format:

jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]

To specify a database name, you must include it at the end of the URL in the form of databaseName=jiradb.

For example, if your old database configuration looked like this:

<url>jdbc:jtds:sqlserver://sqlserver_hostname:1433/jiradb</url>
<driver-class>net.sourceforge.jtds.jdbc.Driver</driver-class>

You'd want to change it to:

<url>jdbc:sqlserver://sqlserver_hostname:1433;databaseName=jiradb</url>
<driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class>

Note about Named Instances and Port Numbers

In some cases, we've seen users unable to start JIRA, as JIRA reported it could not open the database requested by the login which would cause JIRA's startup to fail. In some environments, the login request doesn't get passed the correct instance. Removing the port number and specifying an instance name should allow the connection to succeed.

The old scheme was:

<url>jdbc:jtds:sqlserver://sqlserver_hostname:1433/jiradb;instance=instance_name</url>

In the new scheme, this would be:

<url>jdbc:sqlserver://sqlserver_hostname\instance_name:1433;databaseName=jiradb</url>

However, the login request appeared to be being passed to an incorrect instance - and thus the following was used:

<url>jdbc:sqlserver://sqlserver_hostname\instance_name;databaseName=jiradb</url>

As per Microsoft's documentation:

If both a portNumber and instanceName are used, the portNumber will take precedence and the instanceName will be ignored.

Last modified on Sep 8, 2017

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.