Transitioning from jTDS to Microsoft's JDBC driver

Connecting Bitbucket Server to SQL Server

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This page describes how to change from using jTDS to using the Microsoft SQL Server JDBC driver to access Microsoft SQL Server.

What do I have to do?

If Bitbucket Server was configured to use Microsoft SQL Server by following the steps outlined in Connecting Bitbucket Server to SQL Server no change is necessary . However, If Bitbucket Server was configured to use Microsoft SQL Server by manually entering a JDBC URL, the system will lock on startup if the driver class and URL are not manually updated.

How to proceed

In the Bitbucket Server home directorybitbucket.properties must be edited to change the JDBC driver and URL. The existing configuration should look similar to this:

jdbc.driver=net.sourceforge.jtds.jdbc.Driver
jdbc.url=jdbc:jtds:sqlserver://localhost:1433;databaseName=stash;
jdbc.user=stashuser
jdbc.password=secretpassword

(warning) The JDBC URL above is in the format constructed by Bitbucket Server when Connecting Bitbucket Server to SQL Server and will automatically be updated to a URL compatible with Microsoft's driver, with no change required on the administrator's part.  If the URL contains additional properties, such as domain=, it will need to be manually updated.

To use Microsoft's SQL Server driver, the settings above would be updated to this:

jdbc.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
jdbc.url=jdbc:sqlserver://localhost:1433;databaseName=stash;
jdbc.user=stashuser
jdbc.password=secretpassword

The exact values to use in the new URL are beyond the scope of this documentation; they must be chosen based on the jTDS settings they are replacing.

Additional Information for the curious

The new JDBC driver class is: com.microsoft.sqlserver.jdbc.SQLServerDriver

The JDBC URL format for the jTDS driver is documented on SourceForge at http://jtds.sourceforge.net/faq.html#urlFormat.

The JDBC URL format for Microsoft's SQL Server driver is documented on MSDN at http://msdn.microsoft.com/en-us/library/ms378428.aspx, with documentation for additional properties at http://msdn.microsoft.com/en-us/library/ms378988.aspx.

Why change drivers?

Click here to find all the technical details...

Recent releases of Hibernate, which Bitbucket Server uses to simplify its persistence layer, have introduced a requirement that the JDBC drivers and connection pools used be JDBC4-compliant. JDBC4 was introduced with Java 6.

The jTDS driver used by releases prior to Bitbucket Server 2.1 is a JDBC3 driver, compatible with Java 1.3, and therefore cannot be used with newer versions of Hibernate. While jTDS 1.3.0 implements JDBC4, and JDBC4.1 which is provided by Java 7, it requires a Java 7 runtime environment. Upgrading Bitbucket Server to that version was a non-starter, as it would require raising the minimum Java version for the product to Java 7.

Instead, the decision was made to replace jTDS with Microsoft's own SQL Server driver. Microsoft's driver is actively maintained, where jTDS is only recently seeing its first updates in over 3 years, and supports all the features of SQL Server, including SQL Server 2012.

Bitbucket Server attempts to automatically update jTDS JDBC URLs to values compatible with Microsoft's JDBC driver. However, for installations using custom JDBC URLs–for example, to use domain authentication–such automatic updating is not possible; the URL, which was manually entered, must be manually updated.

Last modified on Sep 16, 2015

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.