Caucho Technology
  • resin 4.0
  • database configuration

    Resin provides a robust and tested connection pool that is used to obtain connections to databases.



    child of database
    default 10m

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


    child of database
    default true

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


    <database> defines a database (i.e. DataSource) resource.

    The database configuration section has more details on the configuration. A code pattern for using databases is in a DataSource tutorial.

    <database> Attributes
    backup-driverConfigures a backup database driver. If Resin can't connect to any of the main drivers, it will use one of the. backups
    close-dangling-connectionsIf an application does not close a Connection by the end of the request, Resin will close it automatically an issue a warning.true
    connectionDefines initialization attributes for new connections, e.g. setting the transaction-isolation.true
    connection-wait-timeWhen max-connections has been reached, how long Resin will wait for a connection to become idle before giving up.10min
    driverConfigures the database driver, giving the driver's class name as well as its JDBC URL and any other configuration.required
    jndi-nameThe JNDI name to register the connection's DataSource under. If the name can be relative to java:comp/env.
    max-active-timeThe maximum time Resin will allow a connection to remain open before forcing a close.6 hours
    max-close-statementsThe maximum number of Statements Resin will hold to automatically close when the Connection closes.256
    max-connectionsThe maximum number of Connections allowed.128
    max-create-connectionsThe maximum number of connection creation allowed at one time.5
    max-idle-countThe maximum number of Connections in the idle pool.1024
    max-idle-timeThe maximum time a connection will spend in the idle pool before closing.30s
    max-overflow-connectionsThe number of extra connection creation if the number of connections exceeds to pool size.0
    max-pool-timeThe total time a connection can be used before it is automatically closed instead of returned to the idle pool.24h
    nameThe IoC name to save the ConnectionFactory as, used with @Named to inject the resource.
    passwordThe JDBC password for the connection.
    pingIf true, Resin will ping the database before returning a connection from the pool (if ping-interval is exceeded).false
    ping-intervalHow often an idle connection should ping the database to ensure it is still valid.1s
    ping-queryA custom query used to ping the database connection.
    ping-tableA table used to ping the database connection.
    prepared-statement-cache-sizeHow many PreparedStatements to save in the prepared statement cache.0
    save-allocation-stack-traceIf true, saves the location of the connection allocation as a stack trace.false
    spyEnables spy logging of database statements. The logging occurs with name="com.caucho.sql" and level="fine".false
    transaction-timeoutSets the transaction timeout.none
    userSets the authentication user.
    wrap-statementsIf true, Resin wraps statements and automatically closes them on connection close.true
    xaEnables automatic enlistment of Connections with any UserTransaction. Disabling <xa> means the connection are independent of transactions, useful for read-only connections.true
    xa-forbid-same-rmWorkaround flag to handle certain database drivers that do not properly implement the XAResource API.false
    <database> schema
    database = element database {
      & close-dangling-connections?
      & connection?
      & connection-wait-time?
      & driver+
      & jndi-name?
      & max-active-time?
      & max-close-statements?
      & max-connections?
      & max-create-connections?
      & max-idle-count?
      & max-idle-time?
      & max-overflow-connections?
      & max-pool-time?
      & name?
      & password?
      & ping?
      & ping-interval?
      & ping-query?
      & ping-table?
      & prepared-statement-cache-size?
      & save-allocation-stack-trace?
      & spy?
      & transaction-timeout?
      & user?
      & wrap-statements?
      & xa?
      & xa-forbid-same-rm?
    backup-driver = element backup-driver {
      & url?
      & element * { * }?
    connection = element connection {
      & read-only?
      & transaction-isolation?
    driver = element driver {
      & url?
      & element * { * }?
    Example: WEB-INF/resin-web.xml database
    <web-app xmlns="">
    <database jndi-name='jdbc/test_mysql'>
      <driver class="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource">


    child of database

    <driver> configures a database driver for a connection pool. The individual driver information is available from the driver vendor or on the Caucho Wiki.

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

    <driver> schema
    element driver {


    child of database
    default 6h

    <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.


    child of database
    default 256

    <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.


    child of database
    default 128

    <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.


    child of database
    default 5

    <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.


    child of database
    default 30s

    <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.


    child of database
    default 0

    <max-overflow-connections> extends <connection-max> temporarily in case of overflow. After the <connection-wait-time> expires, Resin can create an overflow connection to handle unforseen load spikes.


    child of database
    default 24h

    <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.


    child of database

    <password> configures the database connection password. Sites requiring additional security for their passwords can use the <mypkg:MyDecryptor/> syntax to configure a password decoder.


    child of database
    default false

    <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>.


    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.


    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.


    child of database
    default 1s

    <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.


    child of database
    default 0

    <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.


    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.


    child of database
    default false

    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.

    Example: spy output
    0.6:executeQuery(select o.DATA from my_bean o where o.ID=?)


    child of database
    default -1

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

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