Represents a database connection pool.
A ConnectionPool can be used to obtain connections to a database and execute statements. This class opens a number of database connections and allows callers to obtain and use a database connection in a reentrant manner. Applications can instantiate as many ConnectionPool objects as needed and against as many different database systems as needed.
Connection URL:
The URL given to a Connection Pool at creation time specifies a database connection in the standard URL format:
The property names user
and password
are always recognized and specify how to log in to the database. Other properties depend on the database server in question. Username and password can alternatively be specified in the auth-part of the URL. If port number is omitted, the default port number for the database server is used.
MySQL:
Example URL for MySQL:
Or using the auth-part of the URL:
See mysql options for all properties that can be set for a mysql connection URL.
SQLite:
For SQLite, the URL should specify a database file. SQLite uses pragma commands for performance tuning and other special purpose database commands. Pragma syntax in the form name=value
can be added as properties to the URL.
Example URL for SQLite (with recommended pragmas):
PostgreSQL:
Example URL for PostgreSQL:
Or using the auth-part and SSL:
See postgresql options for all properties that can be set for a postgresql connection URL.
Oracle:
Example URL for Oracle:
Or using the auth-part and SYSDBA role:
See oracle options for all properties that can be set for an oracle connection URL.
Pool Management:
The pool is designed to dynamically manage the number of active connections based on usage patterns. A reaper
thread is automatically started when the pool is initialized, performing two critical functions:
- Sweeping through the pool at regular intervals (default every 60 seconds) to close connections that have been inactive for a specified time (default 90 seconds).
- Performing periodic validation (ping test) on idle connections to ensure they remain valid and responsive.
Example Usage:
URL url(
"mysql://localhost/test?user=root&password=swordfish");
pool.start();
auto photo = result.
getBlob(
"photo");
}
Represents a database connection pool.
Definition zdbpp.h:1740
Represents a connection to a SQL database system.
Definition zdbpp.h:1331
ResultSet executeQuery(const std::string &sql, Args &&... args)
Executes a SQL query and returns a ResultSet.
Definition zdbpp.h:1545
Represents a database result set.
Definition zdbpp.h:591
int getInt(int columnIndex)
Gets the designated column's value as an int.
Definition zdbpp.h:732
bool next()
Moves the cursor to the next row.
Definition zdbpp.h:678
std::optional< std::string_view > getString(int columnIndex)
Gets the designated column's value as a string.
Definition zdbpp.h:708
std::optional< std::span< const std::byte > > getBlob(int columnIndex)
Gets the designated column's value as a byte span.
Definition zdbpp.h:796
Represents an immutable Uniform Resource Locator.
Definition zdbpp.h:334
- Note
- This ConnectionPool is thread-safe.
- Warning
- A ConnectionPool is neither copyable nor movable. It is designed to be a long-lived object that manages database connections throughout the lifetime of your application. Typically, you would instantiate one or more ConnectionPool objects as part of a resource management class or in the global scope of your application.
|
using | AbortHandler = std::function<void(std::string_view)> |
|
const URL & | getURL () const noexcept |
| Gets the URL of the connection pool.
|
|
void | setInitialConnections (int initialConnections) noexcept |
| Sets the number of initial connections in the pool.
|
|
int | getInitialConnections () noexcept |
| Gets the number of initial connections in the pool.
|
|
void | setMaxConnections (int maxConnections) noexcept |
| Sets the maximum number of connections in the pool.
|
|
int | getMaxConnections () noexcept |
| Gets the maximum number of connections in the pool.
|
|
void | setConnectionTimeout (int connectionTimeout) noexcept |
| Sets the connection inactive timeout value in seconds.
|
|
int | getConnectionTimeout () noexcept |
| Gets the connection timeout value.
|
|
void | setAbortHandler (AbortHandler abortHandler=nullptr) noexcept |
| Sets the function to call if a fatal error occurs in the library.
|
|
void | setReaper (int sweepInterval) noexcept |
| Customizes the reaper thread behavior or disables it.
|
|
void setReaper |
( |
int | sweepInterval | ) |
|
|
noexcept |
Customizes the reaper thread behavior or disables it.
By default, a reaper thread is automatically started when the pool is initialized, with a default sweep interval of 60 seconds. This method allows you to change the sweep interval or disable the reaper entirely.
The reaper thread closes inactive Connections in the pool, down to the initial connection count. An inactive Connection is closed if its connectionTimeout
has expired or if it fails a ping test. Active Connections (those in current use) are never closed by this thread.
This method can be called before or after ConnectionPool::start(). If called after start, the changes will take effect on the next sweep cycle.
- Parameters
-
sweepInterval | Number of seconds between sweeps of the reaper thread. Set to 0 or a negative value to disable the reaper thread. |