 ------
 How to use an external database?
 ------
 Emmanuel Venisse
 ------
 Oct 12 2007
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

How to use an external database?

* Supported databases

    * Derby

    * MySQL

    * Postgres

    * MS SQL Server (with modifications)

    * Oracle (with modifications)

* Configure Continuum

  There is some information in the installation guides for the {{{../installation/standalone.html} standalone Continuum
  installation}} and the {{{../installation/tomcat.html} Continuum web application deployed to Tomcat}}.

** Standalone version

    To use an external database with Continuum standalone, you must configure DataSources in <<<$CONTINUUM_HOME/contexts/continuum.xml>>>

%{snippet|id=datasources|url=http://svn.apache.org/repos/asf/continuum/trunk/continuum-jetty/src/main/contexts/continuum.xml}

    In addition, you must add the JDBC driver to the <<<$CONTINUUM_HOME/lib>>> directory, and update
    <<<$CONTINUUM_HOME/conf/wrapper.conf>>> to list the driver instead of Derby. For example:

----
wrapper.java.classpath.15=%REPO_DIR%/postgresql-8.4-702.jdbc3.jar
----

    If you use MS SQL Server or Oracle, you will need to adjust the
    <<<$CONTINUUM_HOME/apps/continuum/WEB-INF/classes/META-INF/plexus/application.xml>>> file to change the
    <<<javax.jdo.option.Mapping>>> value from <<<default>>> to <<<mssql>>> or <<<oracle>>> respectively. Bear in mind that
    this change will need to be made again across release upgrades.

%{snippet|id=mapping|url=http://svn.apache.org/repos/asf/continuum/trunk/continuum-webapp/src/main/resources/META-INF/plexus/application.xml}

** Web Application

    To use an external database with the Continuum web application, you should configure the DataSource in your container.

    Make sure the JDBC driver is available in the expected location for your container.

    If you use MS SQL Server or Oracle, you will need to adjust the
    <<<WEB-INF/classes/META-INF/plexus/application.xml>>> file in the unpacked web application to change the
    <<<javax.jdo.option.Mapping>>> value from <<<default>>> to <<<mssql>>> or <<<oracle>>> respectively. Bear in mind that
    this change will need to be made again across release upgrades.

%{snippet|id=mapping|url=http://svn.apache.org/repos/asf/continuum/trunk/continuum-webapp/src/main/resources/META-INF/plexus/application.xml}

* Shutdown Procedure

   When using an external database, it is very important to stop Continuum prior to stopping or restarting the database.
   Continuum may exhibit unpredictable behavior if the database disappears while it is running, and may not recover
   once the database comes back up.  If this happens, you must re-start Continuum.