<commit_before><?xml version="1.0"?>

<document>

 <properties>
  <title>James 2.1 - Using a Database</title>
 </properties>

<body>
<section name="Database Configuration">
<p>James has the capacity to use a JDBC-compatible database for storage of both message and user 
data.  This section explains how to configure James to utilize a database for storage.</p>
<subsection name="Requirements">
<p>Using James with a database backend has certain requirements.  Database configuration is 
extremely vendor-specific, so we can only state the requirements in general terms.</p>
<p>There must be a database instance accessible from the James server.  An account with appropriate
privileges (select, insert, delete into tables, and on initial startup creation of tables) and
with sufficient quota for the data to be inserted into the database must be available.  Also,
since James will use JDBC to access the database, an appropriate JDBC driver must be 
available for installation.</p>
<p>It is important to verify the functionality of the database before attempting to configure 
James to use it as a repository.  This will help ensure that configuration issues are properly
identified.</p>
</subsection>
<subsection name="Connection Configuration">
<p>Configuring the Phoenix container to work with JDBC is the first step in enabling James database support.</p>
<p>First, Phoenix must be able to load the JDBC classes.  To make these classes available to Phoenix, place the 
jar/zip files for the JDBC driver in the lib subdirectory of the James installation directory.  Any additional 
libraries upon which the JDBC library depends that are not part of the standard Java distribution should also be
added to this directory.</p>
<p>Please note that a MySQL driver is included as part of the James distribution and
so there is no need to add such a driver to the lib directory.</p>
<p>Second, the config.xml must be modified so that Phoenix initializes the database connections.  The relevant 
configuration is in the database-connections block.  The database-connections tag has only a single child tag, 
data-sources.  This latter tag is a simple container tag for a number of child elements.  It is these child 
elements, <strong>data-source</strong> elements, that define the database connections.</p>
<p>Each <strong>data-source</strong> tag has a required attribute, <strong>name</strong>.  This value 
must be unique to each <strong>data-source</strong> element.  It is this <strong>name</strong> that will 
be used to specify the database connection in other parts of the config.xml file.</p>
<p>The <strong>data-source</strong> element has five children, all of whom are required.
<ul>
<li><strong>driver</strong> - The class name of the database driver to be used.</li>
<li><strong>dburl</strong> - The JDBC connection URL for your database/driver.</li>
<li><strong>user</strong> - The user id of the database account to be used by this connection.</li>
<li><strong>password</strong> - The password of the database account to be used by this connection.</li>
<li><strong>max</strong> - The maximum number of JDBC connections to be used concurrently by this data-source.</li>
</ul>
</p>

<p>Generally, you simply configure these entries in the config.xml
file, which are commented, in order to use a database with James.  You
would then use the db: or dbfile: prefix instead of the file: prefix
for a particular repository.  You are currently free to mix and match
your use of these different storage types for different repositories.
See <a href="repositories_2_1.html">Repository Configuration</a> for
more details.</p>

<p>If you are using a SQL database with unusual SQL commands, you may
need to add special entries to the sqlResources.xml file, which tells
James how to interact with different SQL databases.  The James team
does try to keep sqlResources.xml updated, so if you do run into a
special case, please let us know.</p>

</subsection>
<subsection name="Known Issues">
<p>There are some vendor-specific subtleties in using databases with James that have been observed 
by some users.  These issues (and methods to resolve them) are recorded on the <commit_msg>Added an example section<commit_after><?xml version="1.0"?>

<document>

 <properties>
  <title>James 2.1 - Using a Database</title>
 </properties>

<body>
<section name="Database Configuration">
<p>James has the capacity to use a JDBC-compatible database for storage of both message and user 
data.  This section explains how to configure James to utilize a database for storage.</p>
<subsection name="Requirements">
<p>Using James with a database backend has certain requirements.  Database configuration is 
extremely vendor-specific, so we can only state the requirements in general terms.</p>
<p>There must be a database instance accessible from the James server.  An account with appropriate
privileges (select, insert, delete into tables, and on initial startup creation of tables) and
with sufficient quota for the data to be inserted into the database must be available.  Also,
since James will use JDBC to access the database, an appropriate JDBC driver must be 
available for installation.</p>
<p>It is important to verify the functionality of the database before attempting to configure 
James to use it as a repository.  This will help ensure that configuration issues are properly
identified.</p>
</subsection>
<subsection name="Connection Configuration">
<p>Configuring the Phoenix container to work with JDBC is the first step in enabling James database support.</p>
<p>First, Phoenix must be able to load the JDBC classes.  To make these classes available to Phoenix, place the 
jar/zip files for the JDBC driver in the lib subdirectory of the James installation directory.  Any additional 
libraries upon which the JDBC library depends that are not part of the standard Java distribution should also be
added to this directory.</p>
<p>Please note that a MySQL driver is included as part of the James distribution and
so there is no need to add such a driver to the lib directory.</p>
<p>Second, the config.xml must be modified so that Phoenix initializes the database connections.  The relevant 
configuration is in the database-connections block.  The database-connections tag has only a single child tag, 
data-sources.  This latter tag is a simple container tag for a number of child elements.  It is these child 
elements, <strong>data-source</strong> elements, that define the database connections.</p>
<p>Each <strong>data-source</strong> tag has a required attribute, <strong>name</strong>.  This value 
must be unique to each <strong>data-source</strong> element.  It is this <strong>name</strong> that will 
be used to specify the database connection in other parts of the config.xml file.</p>
<p>The <strong>data-source</strong> element has five children, all of whom are required.
<ul>
<li><strong>driver</strong> - The class name of the database driver to be used.</li>
<li><strong>dburl</strong> - The JDBC connection URL for your database/driver.</li>
<li><strong>user</strong> - The user id of the database account to be used by this connection.</li>
<li><strong>password</strong> - The password of the database account to be used by this connection.</li>
<li><strong>max</strong> - The maximum number of JDBC connections to be used concurrently by this data-source.</li>
</ul>
</p>

<p>Generally, you simply configure these entries in the config.xml
file, which are commented, in order to use a database with James.  You
would then use the db: or dbfile: prefix instead of the file: prefix
for a particular repository.  You are currently free to mix and match
your use of these different storage types for different repositories.
See <a href="repositories_2_1.html">Repository Configuration</a> for
more details.</p>

<p>If you are using a SQL database with unusual SQL commands, you may
need to add special entries to the sqlResources.xml file, which tells
James how to interact with different SQL databases.  The James team
does try to keep sqlResources.xml updated, so if you do run into a
special case, please let us know.</p>

</subsection>

<subsection name="An example">

<p>The configuration file has commented out examples for MySQL and
MSSQL data sources, and for each of the standard repositories.  For
example, to use MySQL, you would uncomment and adjust the following
data-source element.  You must create the database, in this case named
<strong>mail</strong>, the user, and assign the user priviledges.
James will automatically create the tables it needs.</p>

<source>
&lt;data-source name="maildb" class="org.apache.james.util.mordred.JdbcDataSource"&gt;
  &lt;driver&gt;org.gjt.mm.mysql.Driver&lt;/driver&gt;
  &lt;dburl&gt;jdbc:mysql://127.0.0.1/mail&lt;/dburl&gt;
  &lt;user&gt;username&lt;/user&gt;
  &lt;password&gt;password&lt;/password&gt;
  &lt;max&gt;20&lt;/max&gt;
&lt;/data-source&gt;
</source>

<p>Once you have created the data-source element, you can use it else where in the configuration file.  For example, the following element tells James to use the maildb data-source and dbfile storage mechanism for the message spool:</p>

<source>
&lt;spoolRepository&gt;
   &lt;repository destinationURL="dbfile://maildb/spool/spool" type="SPOOL"/&gt;
&lt;/spoolRepository&gt;
</source>

<p>The following element tells James to store mailboxes in a the maildb data-source:</p>

<source>
&lt;inboxRepository&gt;
   &lt;repository destinationURL="db://maildb/inbox/" type="MAIL"/&gt;
&lt;/inboxRepository&gt;
</source>

<p>The configuration file contains further examples.</p>
</subsection>

<subsection name="Known Issues">
<p>There are some vendor-specific subtleties in using databases with James that have been observed 
by some users.  These issues (and methods to resolve them) are recorded on the 
{'fraction_non_alphanumeric': 0.07996342206868523, 'fraction_numerical': 0.00203210729526519, 'mean_word_length': 4.810507674144038, 'pattern_counts': {'":': 0, '<': 169, '<?xml version=': 2, '>': 169, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 12}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7234632', 'n_tokens_mistral': 2622, 'n_tokens_neox': 2555, 'n_words': 1329}