admin/configuration

database configuration

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

<connection-wait-time>

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.

<close-dangling-connections>

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>

child of resin,cluster,host,web-app

<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
ATTRIBUTE	DESCRIPTION	DEFAULT
backup-driver	Configures a backup database driver. If Resin can't connect to any of the main drivers, it will use one of the. backups
close-dangling-connections	If an application does not close a Connection by the end of the request, Resin will close it automatically an issue a warning.	true
connection	Defines initialization attributes for new connections, e.g. setting the transaction-isolation.	true
connection-wait-time	When max-connections has been reached, how long Resin will wait for a connection to become idle before giving up.	10min
driver	Configures the database driver, giving the driver's class name as well as its JDBC URL and any other configuration.	required
jndi-name	The JNDI name to register the connection's `DataSource` under. If the name can be relative to java:comp/env.
max-active-time	The maximum time Resin will allow a connection to remain open before forcing a close.	6 hours
max-close-statements	The maximum number of Statements Resin will hold to automatically close when the Connection closes.	256
max-connections	The maximum number of Connections allowed.	128
max-create-connections	The maximum number of connection creation allowed at one time.	5
max-idle-count	The maximum number of Connections in the idle pool.	1024
max-idle-time	The maximum time a connection will spend in the idle pool before closing.	30s
max-overflow-connections	The number of extra connection creation if the number of connections exceeds to pool size.	0
max-pool-time	The total time a connection can be used before it is automatically closed instead of returned to the idle pool.	24h
name	The IoC name to save the `ConnectionFactory` as, used with `@Named` to inject the resource.
password	The JDBC password for the connection.
ping	If true, Resin will ping the database before returning a connection from the pool (if ping-interval is exceeded).	false
ping-interval	How often an idle connection should ping the database to ensure it is still valid.	1s
ping-query	A custom query used to ping the database connection.
ping-table	A table used to ping the database connection.
prepared-statement-cache-size	How many `PreparedStatements` to save in the prepared statement cache.	0
save-allocation-stack-trace	If true, saves the location of the connection allocation as a stack trace.	false
spy	Enables spy logging of database statements. The logging occurs with name="com.caucho.sql" and level="fine".	false
transaction-timeout	Sets the transaction timeout.	none
user	Sets the authentication user.
wrap-statements	If true, Resin wraps statements and automatically closes them on connection close.	true
xa	Enables 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-rm	Workaround flag to handle certain database drivers that do not properly implement the XAResource API.	false

<database> schema

database = element database {
  backup-driver*
  & 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 {
  class?
  & url?
  & element * { * }?
}

connection = element connection {
  catalog?
  & read-only?
  & transaction-isolation?
}

driver = element driver {
  class?
  & url?
  & element * { * }?
}

Example: WEB-INF/resin-web.xml database

<web-app xmlns="http://caucho.com/ns/resin">

<database jndi-name='jdbc/test_mysql'>
  <driver class="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource">
    <url>jdbc:mysql://localhost:3306/test</url>
    <user></user>
    <password></password>
  </driver>
</database>

</web-app>

<driver>

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 {
  type,
  *
}

<max-active-time>

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.

<max-close-statements>

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.

<max-connections>

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.

<max-create-connections>

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.

<max-idle-time>

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.

<max-overflow-connections>

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.

<max-pool-time>

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.

<password>

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.

<ping>

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

<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

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.

<prepared-statement-cache-size>

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.

<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

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:setString(1,1)
0.6:executeQuery(select o.DATA from my_bean o where o.ID=?)

<transaction-timeout>

child of database

default -1

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