Setting Up A Microsoft SQL Server Database (Using the jTDS JDBC Driver)
Overview
Microsoft SQL Server (MSSQL) is a commercial database product available from Microsoft at http://www.microsoft.com/sql/default.mspx
Obtaining a Driver
Since the jTDS JDBC driver for MSSQL is not available in the central Maven repository, it must be placed into the local repository of each machine on which you wish to build uPortal.
As an alternative to this, you could set up a maven repository for use by multiple machines.
The first step is to download the JDBC driver for your database. The preferred driver is the JTDS driver from sourceforge. It can be obtained here.
To install the JAR into your local maven repository, use the following command:
mvn install:install-file -DgroupId=net.sourceforge -DartifactId=jtds -Dversion=1.2 -Dpackaging=jar -DgeneratePom=true -Dfile=jtds-1.2.jar
The groupId, artifactId and version specified in this command are up to you, but they should match the JAR vendor, name and version to avoid confusion down the road.
JAR Configuration
Opening /uPortal/pom.xml, there is a section about 92 lines down that reads:
<!-- The JDBC Driver used by uPortal --> <jdbc.groupId>hsqldb</jdbc.groupId> <jdbc.artifactId>hsqldb</jdbc.artifactId> <jdbc.version>${hsqldb.version}</jdbc.version>
We will modify this to use the MSSQL driver, using the group, artifact and version information from the mvn install:install-file command above.
<!-- The JDBC Driver used by uPortal --> <jdbc.groupId>net.sourceforge</jdbc.groupId> <jdbc.artifactId>jtds</jdbc.artifactId> <jdbc.version>1.2</jdbc.version>
See Issues section about possible issues using this driver.
JDBC Configuration
Edit /uPortal/uportal-impl/src/main/resources/properties/rdbm.properties by adding the following information for MSSQL, modifying the url, username and password as appropriate:
##### Microsoft SQL Server hibernate.connection.driver_class=net.sourceforge.jtds.jdbc.Driver hibernate.connection.url=jdbc:jtds:sqlserver://my.school.edu:1433/uPortal3db hibernate.connection.username=test hibernate.connection.password=mypass hibernate.dialect=org.hibernate.dialect.SQLServerDialect
Edit /uPortal/uportal-impl/src/main/resources/properties/db/dbloader.xml by adding the following entry (if it does not already exist):
<db-type-mapping> <db-name>Microsoft SQL Server</db-name> <db-version>09.00.2047</db-version> <driver-name>jTDS Type 4 JDBC Driver for MS SQL Server and Sybase</driver-name> <driver-version>1.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> </db-type-mapping>
You will have to change the db-version entry to match your version of MS SQL Server.
Testing The Configuration
Running the dbtest
ant target will tell you if you have configured the database connection properly.
ant dbtest
Execute "ant initportal" to build the database tables and copy files to your servlet container.
Start your servlet container.
Loading the Database
Loading the database requires a couple of steps:
- Create the database: 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.
Issues and Known Bugs
Additional Notes
An alternative JDBC driver is available directly from Microsoft at: http://www.microsoft.com/sql/downloads/default.mspx
Credits
Much of the information on this page was provided by ~bneupane on the uportal-user list. Thanks.