| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <html> |
| <head> |
| <title>James Server - |
| James 2.3 - Using a Database</title> |
| <style type="text/css" media="all"> |
| @import url("./css/maven-base.css"); |
| @import url("./css/maven-theme.css"); |
| @import url("./css/site.css"); |
| </style> |
| <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" /> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="http://james.apache.org/index.html" id="bannerLeft"> |
| |
| <img src="images/james-server-logo.gif" alt="" /> |
| |
| </a> |
| <a href="http://www.apache.org/index.html" id="bannerRight"> |
| |
| <img src="images/asf-logo-reduced.gif" alt="" /> |
| |
| </a> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| |
| |
| |
| |
| |
| <div class="xleft"> |
| Last Published: 09/02/2009 |
| </div> |
| <div class="xright"> <a href="../../index.html">JAMES Project</a> |
| | |
| <a href="../../server/index.html">Server</a> |
| | |
| <a href="../../mailet/index.html">Mailets</a> |
| | |
| <a href="../../jspf/index.html">jSPF</a> |
| | |
| <a href="../../mime4j/index.html">Mime4J</a> |
| | |
| <a href="../../jsieve/index.html">JSieve</a> |
| | |
| <a href="../../postage/index.html">Postage</a> |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| |
| |
| |
| |
| |
| <h5>James Server</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="../index.html">Overview</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../design_objectives.html">Objectives</a> |
| </li> |
| |
| |
| |
| |
| |
| <li class="expanded"> |
| <a href="../FAQ.html">James FAQ</a> |
| <ul> |
| |
| <li class="none"> |
| <a href="../james_and_sendmail.html">James and Sendmail</a> |
| </li> |
| </ul> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/james">Wiki</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../rfclist.html">Useful RFCs</a> |
| </li> |
| </ul> |
| <h5>Overview</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="index.html">Introduction</a> |
| </li> |
| |
| <li class="none"> |
| <a href="release-notes.html">Release Notes</a> |
| </li> |
| </ul> |
| <h5>Concepts</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="summary.html">Summary</a> |
| </li> |
| |
| <li class="none"> |
| <a href="spoolmanager.html">SpoolManager</a> |
| </li> |
| |
| <li class="none"> |
| <a href="repositories.html">Repositories</a> |
| </li> |
| |
| <li class="none"> |
| <a href="mailet_api.html">The Mailet API</a> |
| </li> |
| </ul> |
| <h5>How to...</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="build_instructions.html">Build James</a> |
| </li> |
| |
| <li class="none"> |
| <a href="installation_instructions.html">Install James</a> |
| </li> |
| </ul> |
| <h5>Configuration</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="dns_configuration.html">DNS Server</a> |
| </li> |
| |
| <li class="none"> |
| <a href="pop3_configuration.html">POP3 Server</a> |
| </li> |
| |
| <li class="none"> |
| <a href="smtp_configuration.html">SMTP Server</a> |
| </li> |
| |
| <li class="none"> |
| <a href="nntp_configuration.html">NNTP Server</a> |
| </li> |
| |
| <li class="none"> |
| <a href="fetchmail_configuration.html">FetchMail</a> |
| </li> |
| |
| <li class="none"> |
| <a href="remotemanager_configuration.html">RemoteManager</a> |
| </li> |
| |
| <li class="none"> |
| <a href="spoolmanager_configuration.html">SpoolManager</a> |
| </li> |
| |
| <li class="none"> |
| <a href="serverwide_configuration.html">Server-wide</a> |
| </li> |
| |
| <li class="none"> |
| <a href="adding_users.html">Adding Users</a> |
| </li> |
| |
| <li class="none"> |
| <a href="provided_matchers.html">Provided Matchers</a> |
| </li> |
| |
| <li class="none"> |
| <a href="provided_mailets.html">Provided Mailets</a> |
| </li> |
| </ul> |
| <h5>Common Configurations</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="smtp_auth.html">Using SMTP AUTH</a> |
| </li> |
| |
| <li class="none"> |
| <strong>Using a Database with James</strong> |
| </li> |
| |
| <li class="none"> |
| <a href="usingTLS.html">Using TLS/SSL</a> |
| </li> |
| |
| <li class="none"> |
| <a href="mailing_lists.html">Creating Mailing Lists</a> |
| </li> |
| </ul> |
| <h5>Customization</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="custom_matcher.html">How to write a custom Matcher</a> |
| </li> |
| |
| <li class="none"> |
| <a href="custom_mailet.html">How to write a custom Mailet</a> |
| </li> |
| </ul> |
| <h5>Project</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="changelog.html">Changelog</a> |
| </li> |
| </ul> |
| <h5>Project Documentation</h5> |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="collapsed"> |
| <a href="project-info.html">Project Information</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="collapsed"> |
| <a href="project-reports.html">Project Reports</a> |
| </li> |
| </ul> |
| <h5>Project</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="http://issues.apache.org/jira/browse/JAMES">Bug Database</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://svn.apache.org/viewvc/james/server/">Source Code</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../todo.html">TODO</a> |
| </li> |
| </ul> |
| <h5>Downloads</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="../../download.cgi">Stable releases</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../downloadunstable.cgi">Unstable releases</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://people.apache.org/builds/james/nightly/">Nightly builds</a> |
| </li> |
| </ul> |
| <a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"> |
| <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img> |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| |
| |
| |
| |
| |
| <a name="Database Configuration"></a><div class="section"><h2>Database Configuration</h2> |
| <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> |
| <a name="Requirements"></a><div class="section"><h3>Requirements</h3> |
| <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> |
| </div> |
| <a name="Connection Configuration"></a><div class="section"><h3>Connection Configuration</h3> |
| <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>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> |
| |
| |
| 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.html">Repository Configuration</a> for |
| more details. A sample configuration is described below. |
| |
| </div> |
| <a name="SQL Statement Configuration"></a><div class="section"><h3>SQL Statement Configuration</h3> |
| The precise SQL statements used by James to modify and view data stored in the database are specified in |
| an external configuration file. The sqlResources.xml file |
| (which can be found in the apps/james/conf directory) is a sample configuration file that contains the SQL |
| statements used by James. The purpose of each of these statements, as well as the repository with which |
| they are associated, is documented in situ. |
| |
| If you are using a SQL database with unusual SQL commands or data types, you may |
| need to add special entries to this file. The James team |
| does try to keep sqlResources.xml updated, so if you do run into a |
| special case, please let us know. |
| |
| Also, if the database tables are not created a priori, but rather are to be created by James |
| upon startup, special attention should be paid to the "create table" statements in this file. Such |
| statements tend to be both very database and very database instance specific. |
| </div> |
| <a name="Sample James Configuration"></a><div class="section"><h3>Sample James Configuration</h3> |
| |
| <p>The config.xml 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.</p> |
| |
| <p>You must create the database, in this case named |
| <strong>mail</strong>, the user, and assign the user privileges. |
| You may create the tables before running James or, if you so choose, James |
| will automatically create the tables it needs. In the latter case the user |
| must have table creation privileges.</p> |
| |
| <div class="source"><pre> |
| <data-source name="maildb" class="org.apache.james.util.mordred.JdbcDataSource"> |
| <driver>com.mysql.jdbc.Driver</driver> |
| <dburl>jdbc:mysql://127.0.0.1/mail</dburl> |
| <user>username</user> |
| <password>password</password> |
| <max>20</max> |
| </data-source> |
| </pre></div> |
| |
| <p>Once the data-source element has been created, it can be referenced elsewhere in the config.xml |
| file. For example, the following element tells James to use the maildb data-source and dbfile |
| storage mechanism for the message spool:</p> |
| |
| <div class="source"><pre> |
| <spoolRepository> |
| <repository destinationURL="dbfile://maildb/spool/spool" type="SPOOL"/> |
| </spoolRepository> |
| </pre></div> |
| |
| <p>The following element tells James to store mailboxes in a the maildb data-source:</p> |
| |
| <div class="source"><pre> |
| <inboxRepository> |
| <repository destinationURL="db://maildb/inbox/" type="MAIL"/> |
| </inboxRepository> |
| </pre></div> |
| |
| <p>The configuration file contains further examples.</p> |
| </div> |
| <a name="Known Issues"></a><div class="section"><h3>Known Issues</h3> |
| <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 |
| <a href="../FAQ.html">James FAQ</a> as they are reported. Please consult the FAQ if you encounter any |
| difficulties.</p> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright">© |
| 2002-2009 |
| |
| The Apache Software Foundation |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"> |
| </script> |
| <script type="text/javascript"> |
| _uacct = "UA-1384591-1"; |
| urchinTracker(); |
| </script> |
| </body> |
| </html> |
