<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-Database_Configuration">
  <title>Database Configuration</title>

  <section id="sect-Reference_Guide-Database_Configuration-Overview">
    <title>Overview</title>

    <para>&PRODUCT; has two different database dependencies. One is the
    identity service configuration, which depends on Hibernate. The other is Java content repository (JCR) service, which
    depends on JDBC API, and can integrate with any existing datasource implementation.</para>

    <para>When you change the database configuration for the first time,
    GateIn will automatically generate the proper schema (assuming that the
    database user has the appropriate permissions).</para>

    <para>&PRODUCT; assumes the default encoding for your database is
    <literal>latin1</literal>. You may need to change this parameter for
    your database in order for &PRODUCT; to work properly.</para>
  </section>

  <section id="sect-Reference_Guide-Database_Configuration-JCR_database_configuration">
    <title>Configuring the database for JCR</title>

    <para>To configure the database used by JCR you will need to edit the
    file:<programlisting>$JBOSS_HOME/server/default/conf/gatein/configuration.properties</programlisting></para>

    <para>For Tomcat, the file is located at <programlisting>$TOMCAT_HOME/gatein/conf/configuration.properties</programlisting></para>

    <para>And edit the values of driver, url, username and password with the
    values for your JDBC connection (please, refer to your database JDBC driver
    documentation).</para>

    <programlisting role="XML">gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver
gatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name}
gatein.jcr.datasource.username=sa
gatein.jcr.datasource.password=
</programlisting>

    <para>By default, the name of the database is "jdbcjcr_${name}" - ${name}
    should be a part of the database name, as it is dynamically replaced by the
    name of the portal container extension (for instance,
    gatein-sample-portal.ear defines "sample-portal" as container name and the
    default portal defines "portal" as container name).</para>

    <para>In the case of HSQL the databases are created automatically. For any
    other database you will need to create a database named jdbcjcr_portal
    (and "jdbcjcr_sample-portal" if you have gatein-sample-portal.ear in
    $JBOSS_HOME/server/default/deploy - note that some databases don't accept '-'
    in the database name, so you may have to remove
    $JBOSS_HOME/server/default/deploy/gatein-sample-portal.ear)</para>

    <para>Make sure the user has rights to create tables on jdbcjcr_portal, and
    to update them as they will be automatically created during the first startup .</para>

    <para>Also add your database's JDBC driver into the classpath - you can put it in
    $JBOSS_HOME/server/default/lib (or $TOMCAT_HOME/lib, if you are running on
    Tomcat)</para>

    <para>MySQL example:</para>

    <para>Let's configure our JCR to store data in MySQL. Let's pretend we
    have a user named "gateinuser" with a password "gateinpassword". We would
    create a database "mygateindb_portal" (remember that _portal is required),
    and assign our user the rights to create tables.</para>

    <para>Then we need to add MySQL's JDBC driver to the classpath, and
    finally edit gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration
    to contain the following:<programlisting>gatein.jcr.datasource.driver=com.mysql.jdbc.Driver
gatein.jcr.datasource.url=jdbc:mysql://localhost:3306/mygateindb${container.name.suffix}
gatein.jcr.datasource.username=gateinuser
gatein.jcr.datasource.password=gateinpassword
</programlisting></para>
  </section>

  <section id="sect-Reference_Guide-Database_Configuration-Database_for_default_identity_store">
    <title>Configuring the database for the default identity store</title>

    <para>By default, users are stored in a database. To change the database in which to
    store users, you will need to edit the file:</para>

    <para><programlisting>$JBOSS_HOME/server/default/conf/gatein/configuration.properties</programlisting>For
    Tomcat, the file is located at <programlisting>$TOMCAT_HOME/gatein/conf/configuration.properties</programlisting></para>

    <para>You will find the same kind of configuration as in
    jcr-configuration.xml:<programlisting>gatein.idm.datasource.driver=org.hsqldb.jdbcDriver
gatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name}
gatein.idm.datasource.username=sa
gatein.idm.datasource.password</programlisting></para>
  </section>
</section>
