Resin Documentation

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 Environment configuration for resources: classloader, databases, connectors, and resources.
• See Database Configuration for a detailed overview of databases and Resin.

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

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

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

element driver {
  type,
  *
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

0.6:setString(1,1)
0.6:executeQuery(select o.DATA from my_bean o where o.ID=?)

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