primrose.config

This page explains the settings available when you setup primrose.
Below is an example config file. Note that you may add comments by starting a line with a #.

	poolName=primrose
	base=40
	log=/tmp/primrose_pool_${yyyy-MM-dd}.log
	idleTime=300000
	logLevel=verbose,info,warn,error,crisis
	driverClass=org.postgresql.Driver
	driverURL=jdbc:postgresql://localhost:5432/test
	user=mysuer
	password=mypassword
	killActiveConnectionsOverAge=120000
	cycleConnections=1000
	queueConnectionRequests=true
	waitForConnectionIfDatabaseIsDown=false
	#checkSQL=select 1 from test
	#runPooledMode=true
	#encryptionFileKey=/usr/tomcat/conf/primrose.key
	#connectionTransactionIsolation=TRANSACTION_READ_COMMITTED
	#dumpConnectionOnSQLException=false
	#adminEmail=joe@bloggs.com
	#smtpMailExchangeServer=smtp_out.bloggs.com
	#smtpMailExchangeServerPort=123
	#emailEvents=start,stop,unclose,kill,nofree,dbcrash
	#onExceptionCheckSQL=select 1 from dual
	#numberOfConnectionsToInitializeWith=0

poolName

This is the name by which a pool is known, and can be looked up programatically using JNDI under a URL such as java:comp/env/poolName

base

This controls how many connections are available in the pool. If the maximum connections are reached during an application's runtime, you may configure primrose to either reject incoming connections using the or to queue up connection requests until a connection becomes available using the 'queueConnectionRequests' setting.
Values for the setting are any postive integer.

log

This controls the location to which log messages for a pool are written. You may write all messages to a single log, or have a single log file per pool.
If the file name given does not exist, messages are written to stdout.
Primrose can also cycle log files on a day by day basis.
An example would be : log=/tmp/primrose_pool_${yyyy-MM-dd}.log
This would log files to "/tmp", creating files that looked like primrose_pool_2007-05-29.log

idleTime

This controls how long a connection should remain inactive in the pool. The value is a positive integer, in milliseconds. Once the period has expired, the connection is removed from the pool in order to conserve resources.
This also allows your pool to grow and shrink according to how busy your application is being used.
An example would be :idleTime=120000 which means that a connection would be removed from the pool after being inactive for 2 minutes.
You may disable this by deleting/commenting out the setting, or using -1 as the value.

logLevel

This controls how much logging you get in your log file. Values are comma delimted in a string, and mean :

verbose - loads of logging, good for debug - but not great for production environments.
info - less logging than verbose - includes a line about who (what code) called the pool, and the SQL they executed.
warn - minimal log messages about potentially dangerous events
error - messages highlighting crucial errors that have occured in the pool
crisis - really bad stuff that will probably mean application failure

A debug/devel example could be :logLevel=verbose,info,warn,error,crisis
A live/production example could be :logLevel=info,warn,error,crisis

driverClass

The JDBC driver class name you wish primrose to connect to your database with. An example would be :driverClass=org.postgresql.Driver

driverURL

The JDBC driver URL you wish primrose to connect to your database with. An example would be :driverURL=jdbc:postgresql://localhost:5432/test

user

The database user you wish primrose to connect to your database with. An example would be :user=myuser

password

The database password you wish primrose to connect to your database with. An example would be :password=mypassword

killActiveConnectionsOverAge

Sometimes applications do not release connections, due to bugs in code, or an unexpected failure. This setting allows primrose to attempt to close down connections which exceed the given time.
Values are in milliseconds.
An example would be :killActiveConnectionsOverAge=120000 which means that a connection would be closed and removed from the pool after being active for 2 minutes.
You may disable this by deleting/commenting out the setting, or using -1 as the value.

cycleConnections

You may wish a connection to perform a maximum number of calls before being refreshed, or cycled. This setting dictates how many calls should be done before the connection is cycled.
Values may be any postive integer, or -1 (minus one) to disable (ie never cycle).
An example would be :cycleConnections=1000 which would cycle the connection after 1000 calls.
You may disable this by deleting/commenting out the setting, or using -1 as the value.

queueConnectionRequests

Controls whether the pool should enforce client calls to queue up for a connection if the pool is full (ie no connections available).
Values can be either 'true' or 'false'.
If set to false, then a SQLException will be thrown to the client caller if their are no available connections.
An example would be :queueConnectionRequests=true

waitForConnectionIfDatabaseIsDown

Controls whether the pool should queue connection requests if it deems the database to be down.
If set to 'true', then the pool will keep trying to get a connection from a db (if previously uncontactable).
If set to 'false', then the pool will throw a SQLException.
An example would be :waitForConnectionIfDatabaseIsDown=false

checkSQL

Indicates that before handing our a connection, the pool should run some SQL to test if the connection is still valid.
Can be useful for critical applications, where a possibly stale (yet open as returned from isClosed()) connection is never desired.
Remember that performance is impacted by setting this.
An example would be :checkSQL=select 1 from test.
Delete this setting if you do not wish to enable the feature.

runPooledMode

Indicates that you wish to run a pool in "non-pooling" mode (ie give out a brand new connection each time - never pool them) ... more of a debug parameter really.
Default is 'true'. Set to 'false' to disable pooling.
Remember that performance is impacted by setting this to true.
An example would be :runPooledMode=false.

encryptionFileKey

Indicates that you have encrypted your 'password' setting - and this file should point to the encryption key (full path and file name).
Default is to not use encryption.
Remember that performance is impacted by setting this to true.
An example would be :encryptionFileKey=/usr/tomcat/conf/primrose.key.
See this document for how to actually create your key and encrypt your passwords.

connectionTransactionIsolation

Sets the connection's transaction isolation level.
Reset each time a connection is handed out to the given setting.
Possible values are :

TRANSACTION_NONE :: A constant indicating that transactions are not supported.
TRANSACTION_READ_COMMITTED :: A constant indicating that dirty reads are prevented; non-repeatable reads and phantom reads can occur.
TRANSACTION_READ_UNCOMMITTED :: A constant indicating that dirty reads, non-repeatable reads and phantom reads can occur.
TRANSACTION_REPEATABLE_READ :: A constant indicating that dirty reads and non-repeatable reads are prevented; phantom reads can occur.
TRANSACTION_SERIALIZABLE :: A constant indicating that dirty reads, non-repeatable reads and phantom reads are prevented.

Default is to use the driver's default.
An example would be :connectionTransactionIsolation=TRANSACTION_READ_COMMITTED.

connectionAutoCommit

Sets the value of the connection's auto-commit value.
Reset each time a connection is handed out to the given setting.
Default is 'true'. Set to 'false' to turn off auto-commit.
An example would be :connectionAutoCommit=true.

numberOfConnectionsToInitializeWith

The number of connections the pool should load on initialization.
Default is 1.
An example to load none on startup would be :numberOfConnectionsToInitializeWith=0.
An example to load 5 on startup would be :numberOfConnectionsToInitializeWith=5.

adminEmail

An email address that the pool will email if it encounters problems.
An example would be :adminEmail=joe@bloggs.com.
Note that the property smtpMailExchangeServer must also be set.
Note that if you wish to recieve emails from the pool, you will need to install mail.jar and activation.jar, available from Sun :
Download mail.jar
Download activation.jar

smtpMailExchangeServer

The mail exchange server to send emails through (if the adminEmail property is set).
An example would be :smtpMailExchangeServer=smtp.bloggs.com.

smtpMailExchangeServerPort

The mail exchange server port to send emails through (if the adminEmail property is set).
Note that by default it is set to port 25 - you only need set this property if your SMTP server is listening on a different port
An example would be :smtpMailExchangeServerPort=123.

emailEvents

The events you would like to recieve emails about (if the adminEmail property is set).
An example would be :emailEvents=start,stop,unclose,kill.
Or another example would be :emailEvents=unclose,kill.

Events are :

start : A pool has been started.
stop : A pool has been stopped.
unclose : Unclosed ResultSet or Statement objects have been found when the connection was closed.
kill : A connection has been killed due to it exceeding the max execute time (killActiveConnectionsOverAge property).
exception : When a SQLException occurs on a major operation (such as close(), execute(), executeQuery() etc)..
dbcrash : The DB appears to have crashed (when a SQLException occurs as above, try to connect to the DB, and if it fails, this event is triggered).Note that if you use this event, the parameter 'onExceptionCheckSQL' must be set
nofree : When the pool is maxxed out - no connections can be handed out due to the max number are in use.Note - use this event with caution - it may generate a
lot

of emails !

onExceptionCheckSQL

Some SQL to run against the DB to see if it has crashed. Note that this parameter must be used in tandam with the 'emailEvent' parameter 'dbcrash' - it will have no effect if this is not done.
An example would be :onExceptionCheckSQL=select 1 from dual.

dumpConnectionOnSQLException

Whether or not connections should be dumped from the pool when a SQLException occurs on close or execute statements.
Default is true (ie yes, dump connections that encounter an error on execute. Note that the SQLException is not hidden - calling code will still recieve the SQLException, but the connection will not be returned to the pool).
Valid values are 'true' or 'false'.
An example would be :dumpConnectionOnSQLException=false.

Documentation | Downloads

Home >> Documentation >> primrose.config