PostgreSQL™ includes two implementations of DataSource , as shown in Table 11.2, “DataSource Implementations”. One that does pooling and the other that does not. The pooling implementation does not actually close connections when the client calls the close method, but instead returns the connections to a pool of available connections for other clients to use. This avoids any overhead of repeatedly opening and closing connections, and allows a large number of clients to share a small number of database connections.

The pooling data-source implementation provided here is not the most feature-rich in the world. Among other things, connections are never closed until the pool itself is closed; there is no way to shrink the pool. As well, connections requested for users other than the default configured user are not pooled. Its error handling sometimes cannot remove a broken connection from the pool. In general it is not recommended to use the PostgreSQL™ provided connection pool. Check your application server or check out the excellent jakarta commons DBCP project.

Both implementations use the same configuration scheme. JDBC requires that a DataSource be configured via JavaBean properties, shown in Table 11.3, “DataSource Configuration Properties”, so there are get and set methods for each of these properties.

The pooling implementation requires some additional configuration properties, which are shown in Table 11.4, “Additional Pooling DataSource Configuration Properties”.

Example 11.1, “DataSource Code Example” shows an example of typical application code using a pooling DataSource.

PGPoolingDataSource source = new PGPoolingDataSource();
source.setDataSourceName("A Data Source");
source.setServerName("localhost");
source.setDatabaseName("test");
source.setUser("testuser");
source.setPassword("testpassword");
source.setMaxConnections(10);

Connection conn = null;
try {
    conn = source.getConnection();
    // use connection
} catch (SQLException e) {
    // log error
} finally {
    if (con != null) {
        try { conn.close(); } catch (SQLException e) {}
    }
}