Update the Microsoft SQL Server JDBC URL in Jira server
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
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.
Solution
Running the JIRA configuration tool
If you haven't made any changes to the JDBC URL, the Using the JIRA application configuration tool can be used to automatically update the configuration file:
Go to
<installation-directory>/bin, and run theconfig.bat / config.shfileClick Save. Your configuration will be updated
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 Installing Java 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.
Shut down JIRA, and back up your current
<jira-home>/dbconfig.xmlfile.Adjust the
urlfor the database to the following:Adjust the
driver-classfor the database to the following:
The new connection string URL takes the following format:
1
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:
1
2
<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:
1
2
<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:
1
<url>jdbc:jtds:sqlserver://sqlserver_hostname:1433/jiradb;instance=instance_name</url>In the new scheme, this would be:
1
<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:
1
<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.
Note about Integrated Security
Please see KB article here - Use Integrated Authentication with SQL Server in Jira Server
Was this helpful?