05 MSSQL with the JTDS JDBC Driver

Owned by Ryan Elenbaum
Last updated: Jun 09, 2008 by Mark MarkVersion comment
3 min read

Setting up A Microsoft SQL Server Database

Overview

Microsoft SQL Server (MSSQL) is a commercial database product available from Microsoft at http://www.microsoft.com/sql/default.mspx

Obtain the Driver

An MSSQL JDBC driver is available through Microsoft at: http://www.microsoft.com/sql/downloads/default.mspx This driver will work but there are some bugs. The prefered driver is JTDS. It can be obtained for free from http://jtds.sourceforge.net/ Other Commercial MSSQL JDBC drivers are availiable.

Download and extract the current version. Copy the .jar file a location accessible from uPortal (for example, /usr/local/java/mssql/lib/jtds.jar).

Properties Configuration

build.properties

The uPortal build.properties will need to be modifed. Find the property called jdbcDriver and change it to point to the MSSQL jar file, for example:

jdbcDriver.jar=./lib/jtds.jar

rdbm.properties

The uPortal rdbm.properties file (in the properties directory) needs to modified to specify the driver properties. The rdbm.properties file contains several sample entries. Uncomment (or add) the lines for the MSSQL database and make whatever changes necessary to match your local database installation, For example:

#### Microsoft SQL Server
jdbcDriver=net.sourceforge.jtds.jdbc.Driver
jdbcUrl=jdbc:jtds:sqlserver://replaceWithServerName:1433/replaceWithDatabaseName;SelectMethod=cursor 
jdbcUser=replaceWithUsername 
jdbcPassword=replaceWithPassword

dbloader.xml

Useful Information

You should be able to skip this step if using uPortal 2.5.1 or greater. If dbloader.xml from 2.5.1 on doesn't work for you out of the box with the jtds driver please file a bug in JIRA.

This file is used by the DbLoader tool to create the uPortal database tables and populate the database. It contains several sample entries which create db-type-mappings for different databases. Find the tags for an HypersonicSQL database and modify the db-version, driver-name, and driver-version as necessary. For example:

<db-type-mapping>
    <db-name>Microsoft SQL Server</db-name>
    <db-version>08.00.0760</db-version>
    <driver-name>jTDS Type 4 JDBC Driver for MS SQL Server and Sybase</driver-name>
    <driver-version>1.0.3</driver-version>
    <type><generic>INTEGER</generic><local>INTEGER</local></type>
    <type><generic>VARCHAR</generic><local>VARCHAR</local></type>
    <type><generic>TEXT</generic><local>TEXT</local></type>
    <type><generic>TIMESTAMP</generic><local>DATETIME</local></type>
  <type><generic>LONGVARCHAR</generic><local>NTEXT</local></type>
    <!-- map more types here -->
 </db-type-mapping>
<db-type-mapping>
    <db-name>Microsoft SQL Server</db-name>
    <db-version>08.00.0760</db-version>
    <driver-name>jTDS Type 4 JDBC Driver for MS SQL Server and Sybase</driver-name>
    <driver-version>1.1</driver-version>
    <type><generic>INTEGER</generic><local>INTEGER</local></type>
    <type><generic>VARCHAR</generic><local>VARCHAR</local></type>
    <type><generic>TEXT</generic><local>TEXT</local></type>
    <type><generic>TIMESTAMP</generic><local>DATETIME</local></type>
  <type><generic>LONGVARCHAR</generic><local>NTEXT</local></type>
    <!-- map more types here -->
 </db-type-mapping>

PersonDirs.xml

Useful Information

Skip this step if using uPortal 2.5.1 or greater.

This file is used if the database is to be used to provide user directory information

    <!-- JDBC Properties -->
        <driver>net.sourceforge.jtds.jdbc.Driver</driver>
     <url>jdbc:jtds:sqlserver://replaceWithServerName:1433/replaceWithDatabaseName;SelectMethod=cursor</url>
        <logonid>replaceWithUsername</logonid>
        <logonpassword>replaceWithPassword</logonpassword> 
        <uidquery>SELECT FIRST_NAME + ' ' + LAST_NAME AS FIRST_LAST, FIRST_NAME, LAST_NAME, EMAIL FROM UP_PERSON_DIR WHERE USER_NAME=?</uidquery>

Load the database

Create the database: Refer to the Microsoft SQL Server database documentation for instructions regarding how to create an MSSQL database instances. The database name, port number, and driver information must reflect what was defined in the rdbm.properties file.

Create the tables and populate the database: From the uPortal build directory, run "ant db" to execute the ant target which loads the database. The ant target uses the Dbloader tool.

Connection Pooling

Starting with uPortal 2.5.0 DBCP is configured to pool connections automatically at ant deploy time.

Additional Notes