<?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" role="NotInToc">
  <title>Database Configuration</title>

    <para>&PRODUCT; has two different database dependencies. One is the
    identity service configuration, which depends on Hibernate. The other is the 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
    <emphasis>latin1</emphasis>. You may need to change this parameter for
    your database so that &PRODUCT; works properly.</para>
	<para>
		The database configuration in GateIn can be divided into 2 main topics:
	</para>
	<itemizedlist>
       <listitem>
          <para><link linkend="sect-Reference_Guide-Database_Configuration-JCR_database_configuration">Configure the database for JCR</link></para>
      </listitem>
       <listitem>
          <para><link linkend="sect-Reference_Guide-Database_Configuration-Database_for_default_identity_store">Configure the database for the default identity store</link></para>
      </listitem>
  </itemizedlist>

  <para xml:id="sect-Reference_Guide-Database_Configuration-JCR_database_configuration">
    <citetitle>
        <emphasis role="bold">Configure the database for JCR</emphasis>
    </citetitle>
  </para>
    <para>To configure the database used by JCR, edit the
    file: <filename>$PLATFORM_JBOSS_HOME/server/default/conf/gatein/configuration.properties</filename>.</para>

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

    <para>Next, edit the values of driver, url, username and password with the
    values for your JDBC connection. To learn more, refer to your database JDBC driver
    documentation.</para>

    <programlisting language="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 example,
    <filename>gatein-sample-portal.ear</filename> defines "sample-portal" as the container name and the
    default portal defines "portal" as the container name.</para>

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

    <para>Make sure the user has rights to create tables on <emphasis>jdbcjcr_portal</emphasis>, 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
    <filename>$PLATFORM_JBOSS_HOME/server/default/lib</filename> (or <filename>$PLATFORM_TOMCAT_HOME/lib</filename>, if you are running on
    Tomcat).</para>

    <para>MySQL example:</para>

    <para>Configure the JCR to store data in MySQL and assume that you created a user named "gateinuser" with a password "gateinpassword". Next, create a database <emphasis>mygateindb_portal</emphasis> (remember that portal is required),
    and assign the rights to create tables to the users.</para>

    <para>Add the MySQL's JDBC driver to the classpath, and
    finally edit <filename>gatein.ear/portal.war/WEB-INF/conf/jcr/jcr-configuration</filename>
    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>
    <para xml:id="sect-Reference_Guide-Database_Configuration-Database_for_default_identity_store">
    <citetitle>
        <emphasis role="bold">Configure the database for the default identity store</emphasis>
    </citetitle>
  </para>
    <para>By default, users are stored in a database. To change the database where users are stored, you need to edit the file:</para>

    <para>For Jboss: <filename>$PLATFORM_JBOSS_HOME/server/default/conf/gatein/configuration.properties</filename></para>
    <para>For Tomcat: <filename>$PLATFORM_TOMCAT_HOME/gatein/conf/configuration.properties</filename></para>

    <para>You will find the same type of configuration as in
    <filename>jcr-configuration.xml</filename>:<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>
    <para>
        <prompt>
            <emphasis role="bold">See also</emphasis>
        </prompt>
    </para>
    <itemizedlist>
        <listitem>
            <para>
                <link linkend="sect-Reference_Guide-EMail_Service_Configuration">Email Service Configuration</link>
            </para>
        </listitem>
    </itemizedlist>
</section>
