Caucho Technology
documentation
examples
changes

overview
quick start
installation
command-line
configuration
admin
amber
clustering
caching
database
deployment
ejb 3.0
embedding
filters
hessian
hmtp
ioc
jsp
logging
messaging
performance
quercus/php
remoting
scheduled tasks
security
server push
servlets
third-party
troubleshooting
virtual hosting
watchdog
webapp
xml and xslt

<cluster>
<database>
<host>
ports
<resin>
resource tags
rewrite
<server>
session
variables
<web-app>
index
relax schema

database: database tag configuration


The database tag configures a database as a javax.sql.DataSource with numerous options. Resin offers robust database connection pooling.

See Also

  • See Environment configuration for resources: classloader, databases, connectors, and resources.
  • See Database Configuration for a detailed overview of databases and Resin.

<connection-wait-time>

child of database

<connection-wait-time> configures the time a getConnection call should wait when then pool is full before trying to create an overflow connection.

default 10m

<close-dangling-connections>

child of database

<close-dangling-connections> closes open connections at the end of a request and logs a warning and stack trace.

default true

<driver>

child of database

<driver> configures a database driver for a connection pool. The individual driver information is available from the driver vendor or in the database driver page.

The content of the driver tag configures bean properties of the driver class, e.g. url, user, password.

driver schema
element driver {
  type,
  *
}

<database>

child of resin, cluster, host, web-app

<database> configures a database as a javax.sql.DataSource and stores it in jndi with the given jndi-name.

connection-wait-timeWhen the pool it full, how long to wait before opening a new connection anyway.10m
Example: mysql database
<web-app xmlns="http://caucho.com/ns/resin">
  <database jndi-name="jdbc/test">
    <driver type="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource">
      <url>jdbc:mysql://localhost:3306/test</url>
      <user></user>
      <password></password>
    </driver>
  </database>
</web-app>
database schema
element database {
  jndi-name
  & connection-Database?
  & driver+
  & connection-wait-time
  & max-active-time
  & commit-on-timeout
  & max-close-statements
  & max-connections
  & max-create-connections
  & max-idle-time
  & max-overflow-connections
  & max-pool-time
  & password
  & ping
  & ping-table
  & ping-query
  & ping-interval
  & prepared-statement-cache-size
  & save-allocation-stack-trace
  & spy
  & transaction-timeout
  & user
  & xa
  & xa-forbid-same-rm
  & wrap-statements
}

<max-active-time>

child of database

<max-active-time> configures the maximum time a connection can be active before Resin will automatically close it. Normally, the max-active-time should not be configured, since Resin will also automatically close a connection at the end of a request.

Sites should generally leave max-active-time at the default.

default 6h

<commit-on-timeout>

child of database

<commit-on-timeout> configures commit or rollback action to issue before closing connection that remained active past its configured max-active-time.

default false

<max-close-statements>

child of database

<max-close-statements> configures how many open statements Resin should save to for the connection close. Since the JDBC Connection.close() call automatically closes any open statements, Resin's database pool needs to keep track of any open statements to close them in case the application has forgotten. The <max-close-statements> is primarily needed for older database drivers implementing the java.sql.Driver interface.

default 256

<max-connections>

child of database

<max-connections> configures the maximum number of open connections allowed for Resin's database pool. Sites can use <max-connections> to throttle the number of database connections for an overloaded server. When max-connections is reached and an application calls getConnection, Resin will wait connection-wait-time or until a connection is freed before allocating a new connection.

default 128

<max-create-connections>

child of database

<max-create-connections> configures the maximum number of simultaneous connection creations. Since connection creation is slow and database access can be spiky, Resin's pool limits the number of new connections to the database at any time. Once a connection has succeeded, a new connection can proceed.

default 5

<max-idle-time>

child of database

<max-idle-time> configures the maximum time a connection can remain idle before Resin automatically closes it. Since idle databases tie up resources, Resin will slowly close idle connections that are no longer needed.

Higher values of <max-idle-time> will connections to remain in the idle pool for a longer time. Lower values will close idle connections more quickly.

default 30s

<max-pool-time>

child of database

<max-pool-time> configures the maximum time the connection can remain open. A connection could theoretically remain open, switching between active and idle, for an indefinite time. The <max-pool-time> allows a site to limit to total time of that connection.

Most sites will leave <max-pool-time> at the default.

default 24h

<password>

child of database

<password> configures the database connection password. Sites requiring additional security for their passwords can use the resin:type attribute to configure a password decoder.

<ping>

child of database

<ping> enables connection validation. When <ping> is enabled, Resin will test the connection with <ping-query> or <ping-table> before returning a connection to the user. If the connection fails the test, Resin will close it and return a new connection.

For efficiency, Resin will only validate the connection if it has been idle for longer than <ping-interval>.

default false

<ping-table>

child of database

<ping-table> configures the database table Resin should use to verify if a connection is still valid when returned from the pool.

<ping-query>

child of database

<ping-query> specifies the query to use for validating if a database connection is still valid when returned from the idle pool.

<ping-interval>

child of database

<ping-interval> configures when Resin should validate an idle connection. Connections which have been idle for less than <ping-interval> are assumed to be still valid without validation. Connections idle for longer than <ping-interval> are validated.

Sites can force a validation by setting <ping-interval> to 0.

default 1s

<prepared-statement-cache-size>

child of database

<prepared-statement-cache-size> configures how many prepared statements Resin should cache for each connection. Caching prepared statement can improve performance for some database drivers by avoiding repeated parsing of the query SQL.

default 0

<save-allocation-stack-trace>

child of database

<save-allocation-stack-trace> helps debugging application with a missing Connection.close() by saving the stack trace where the Connection.getConnection() was called. When Resin detects that the connection has failed to close, it can then print the allocation stack trace, which is more informative for tracking down errors.

<spy>

child of database

The <spy> tag is a very useful logging tag for debugging database problems. If <spy> is enabled, all database queries will be logged at the "fine" level. Applications can use <spy> to debug unexpected database queries, or to improve query performance.

default false
Example: spy output
0.6:setString(1,1)
0.6:executeQuery(select o.DATA from my_bean o where o.ID=?)

<transaction-timeout>

child of database

<transaction-timeout> configures the maximum time a transaction can be alive before a mandatory rollback.

default -1

Copyright © 1998-2008 Caucho Technology, Inc. All rights reserved.
Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.