<title>
Database Configuration
</title>

Resin's database configuration pulls configuration out of your application
and into the configuration files where it belongs.  The configuration
lets you create any number of named database pools.

<example title='resin.conf'>
&lt;caucho.com&gt;

&lt;resource-ref>
  &lt;res-ref-name>jdbc/test_db&lt;/res-ref-name>
  &lt;res-type>javax.sql.DataSource&lt;/res-type>
  &lt;init-param driver-name="org.gjt.mm.mysql.Driver"/>
  &lt;init-param url="jdbc:mysql://localhost:3306/test"/>
  &lt;init-param user="ferg"/>
  &lt;init-param password="changeit"/>
&lt;/resource-ref>

&lt;/caucho.com&gt;
</example>

<p/>The <var/resource-ref/> configuration is more general than just
configuring database pools.  So it needs <var/res-type/> of
<var/javax.sql.DataSource/> to say that it's configuring a database
pool and not, say, an imap client.

<p/>Since the database configuration puts the initialized pool in a JNDI
Context, the resource-ref needs to specify where in the JNDI tree the
data source belongs.  <var/res-ref-name/> tells Resin where to put
the data source in the JNDI tree.  The previous example used
<var/InitialContext().lookup("...")/> to grab the data source from the tree.
Although JNDI is slightly more complicated, using it means your
code can be independent of the database configuration.

<deftable title="Configuration Tags">
<tr><td>resource-ref<td>the standard configuration for data
sources.  (It can also be used to initialize other beans.)
<tr><td>res-ref-name<td>where to attach the data source in the
JNDI namespace.  In the example, the final name will
be <var/java:comp/env/jdbc/test_db/>.
<tr><td>res-type<td>The type of the resource we're configuring.
In this case, we're configuring a database pool, so the
resource type is <var/javax.sql.DataSource/>.
<tr><td>init-param<td>Lets you configure the database pool and
configure arbitrary properties of the JDBC driver.  Any bean
setter can be used.  So <var/driver-name/> translates
into <var/setDriverName/>.  You can look at <var/com.caucho.sql.DBPool/>
for the list of bean attributes in the pooling driver.
<tr><td>driver-name<td>Sets <var/DBPool.setDriverName/>.  Selects the
Java class of the JDBC driver.  You'll need to look at your driver's
documentation for the class name.
<tr><td>url<td>Sets <var/DBPool.setURL/>.  Selects the JDBC URL for
the datasource.  Again, you'll need to look at your driver's documentation
for this value.
<tr><td>user<td>the name of the database user
<tr><td>password<td>the database password
</deftable>

<p/>Some JDBC drivers may need additional properties, and others don't
need the <var/user/> and <var/password/> configuration.  You can
look at <var/com.caucho.sql.DBPool/> for the list of pooling attributes
and consult your JDBC driver documentation.

<p/>Any property can be configured with the <var/init-param/> entries.
The parameter name is converted to a <var/setXXX/> method using standard
bean conventions.  If the <var/setXXX/> is not in the pool, the
resource-ref configuration will call <var/setProperty/> to set any
driver property.  When Resin calls setProperty, it passes the exact
key given in the init-param element, without bean translations.

<subsection title='Classpath'>
You will need to add your JDBC driver to the classpath before starting
Resin.  There are several methods:

<ol>
<li>Add the driver to the CLASSPATH environment variable.
<li>Start Resin with a -classpath argument including the driver.
<li>Put the jar file in resin-2.0.x/lib.
</ol>

<p/>You can see the classpath Resin is using by starting it with the
-verbose option:

<example>
unix> <var/httpd.sh -verbose/>
</example>

</subsection>


