Apache Module mod_dbd
Description: | Manages SQL database connections |
---|---|
Status: | Extension |
ModuleIdentifier: | dbd_module |
SourceFile: | mod_dbd.c |
Compatibility: | Version 2.1 and later |
Summary
mod_dbd
manages SQL database connections using APR. It provides database connections on request to modules requiring SQL database functions, and takes care of managing databases with optimal efficiency and scalability for both threaded and non-threaded MPMs. For details, see the APR website and this overview of the Apache DBD Framework by its original developer.
Connection Pooling
This module manages database connections, in a manner optimised for the platform. On non-threaded platforms, it provides a persistent connection in the manner of classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python). On threaded platform, it provides an altogether more scalable and efficient connection pool, as described in this article at ApacheTutor. Note that mod_dbd
supersedes the modules presented in that article.
Connecting
To connect to your database, you'll need to specify a driver, and connection parameters. These vary from one database engine to another. For example, to connect to mysql, do the following:
DBDriver mysql DBDParams host=localhost,dbname=pony,user=shetland,pass=appaloosa
You can then use this connection in a variety of other modules, including mod_rewrite
, mod_authn_dbd
, and mod_lua
. Further usage examples appear in each of those modules' documentation.
See DBDParams
for connection string information for each of the supported database drivers.
Apache DBD API
mod_dbd
exports five functions for other modules to use. The API is as follows:
typedef struct { apr_dbd_t *handle; apr_dbd_driver_t *driver; apr_hash_t *prepared; } ap_dbd_t; /* Export functions to access the database */ /* acquire a connection that MUST be explicitly closed. * Returns NULL on error */ AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*); /* release a connection acquired with ap_dbd_open */ AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*); /* acquire a connection that will have the lifetime of a request * and MUST NOT be explicitly closed. Return NULL on error. * This is the preferred function for most applications. */ AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*); /* acquire a connection that will have the lifetime of a connection * and MUST NOT be explicitly closed. Return NULL on error. */ AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*); /* Prepare a statement for use by a client module */ AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*); /* Also export them as optional functions for modules that prefer it */ APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*)); APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*)); APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*)); APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*)); APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));
SQL Prepared Statements
mod_dbd
supports SQL prepared statements on behalf of modules that may wish to use them. Each prepared statement must be assigned a name (label), and they are stored in a hash: the prepared
field of an ap_dbd_t
. Hash entries are of type apr_dbd_prepared_t
and can be used in any of the apr_dbd prepared statement SQL query or select commands.
It is up to dbd user modules to use the prepared statements and document what statements can be specified in httpd.conf, or to provide their own directives and use ap_dbd_prepare
.
Caveat
When using prepared statements with a MySQL database, it is preferred to setreconnect
to 0 in the connection string as to avoid errors that arise from the MySQL client reconnecting without properly resetting the prepared statements. If set to 1, any broken connections will be attempted fixed, but as mod_dbd is not informed, the prepared statements will be invalidated. SECURITY WARNING
Any web/database application needs to secure itself against SQL injection attacks. In most cases, Apache DBD is safe, because applications use prepared statements, and untrusted inputs are only ever used as data. Of course, if you use it via third-party modules, you should ascertain what precautions they may require.
However, the FreeTDS driver is inherently unsafe. The underlying library doesn't support prepared statements, so the driver emulates them, and the untrusted input is merged into the SQL statement.
It can be made safe by untainting all inputs: a process inspired by Perl's taint checking. Each input is matched against a regexp, and only the match is used, according to the Perl idiom:
$untrusted =~ /([a-z]+)/; $trusted = $1;
To use this, the untainting regexps must be included in the prepared statements configured. The regexp follows immediately after the % in the prepared statement, and is enclosed in curly brackets {}. For example, if your application expects alphanumeric input, you can use:
"SELECT foo FROM bar WHERE input = %s"
with other drivers, and suffer nothing worse than a failed query. But with FreeTDS you'd need:
"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"
Now anything that doesn't match the regexp's $1 match is discarded, so the statement is safe.
An alternative to this may be the third-party ODBC driver, which offers the security of genuine prepared statements.
DBDExptime Directive
Description: | Keepalive time for idle connections |
---|---|
Syntax: | DBDExptime time-in-seconds |
Default: | DBDExptime 300 |
Context: | server config, virtual host |
Status: | Extension |
Module: | mod_dbd |
Set the time to keep idle connections alive when the number of connections specified in DBDKeep has been exceeded (threaded platforms only).
DBDInitSQL Directive
Description: | Execute an SQL statement after connecting to a database |
---|---|
Syntax: | DBDInitSQL "SQL statement" |
Context: | server config, virtual host |
Status: | Extension |
Module: | mod_dbd |
Modules, that wish it, can have one or more SQL statements executed when a connection to a database is created. Example usage could be initializing certain values or adding a log entry when a new connection is made to the database.
DBDKeep Directive
Description: | Maximum sustained number of connections |
---|---|
Syntax: | DBDKeep number |
Default: | DBDKeep 2 |
Context: | server config, virtual host |
Status: | Extension |
Module: | mod_dbd |
Set the maximum number of connections per process to be sustained, other than for handling peak demand (threaded platforms only).
DBDMax Directive
Description: | Maximum number of connections |
---|---|
Syntax: | DBDMax number |
Default: | DBDMax 10 |
Context: | server config, virtual host |
Status: | Extension |
Module: | mod_dbd |
Set the hard maximum number of connections per process (threaded platforms only).
DBDMin Directive
Description: | Minimum number of connections |
---|---|
Syntax: | DBDMin number |
Default: | DBDMin 1 |
Context: | server config, virtual host |
Status: | Extension |
Module: | mod_dbd |
Set the minimum number of connections per process (threaded platforms only).
DBDParams Directive
Description: | Parameters for database connection |
---|---|
Syntax: | DBDParams param1=value1[,param2=value2] |
Context: | server config, virtual host |
Status: | Extension |
Module: | mod_dbd |
As required by the underlying driver. Typically this will be used to pass whatever cannot be defaulted amongst username, password, database name, hostname and port number for connection.
Connection string parameters for current drivers include:
- FreeTDS (for MSSQL and SyBase)
- username, password, appname, dbname, host, charset, lang, server
- MySQL
- host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect
- Oracle
- user, pass, dbname, server
- PostgreSQL
- The connection string is passed straight through to
PQconnectdb
- SQLite2
- The connection string is split on a colon, and
part1:part2
is used assqlite_open(part1, atoi(part2), NULL)
- SQLite3
- The connection string is passed straight through to
sqlite3_open
- ODBC
- datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize
DBDPersist Directive
Description: | Whether to use persistent connections |
---|---|
Syntax: | DBDPersist On|Off |
Context: | server config, virtual host |
Status: | Extension |
Module: | mod_dbd |
If set to Off, persistent and pooled connections are disabled. A new database connection is opened when requested by a client, and closed immediately on release. This option is for debugging and low-usage servers.
The default is to enable a pool of persistent connections (or a single LAMP-style persistent connection in the case of a non-threaded server), and should almost always be used in operation.
Prior to version 2.2.2, this directive accepted only the values 0
and 1
instead of Off
and On
, respectively.
DBDPrepareSQL Directive
Description: | Define an SQL prepared statement |
---|---|
Syntax: | DBDPrepareSQL "SQL statement" label |
Context: | server config, virtual host |
Status: | Extension |
Module: | mod_dbd |
For modules such as authentication that repeatedly use a single SQL statement, optimum performance is achieved by preparing the statement at startup rather than every time it is used. This directive prepares an SQL statement and assigns it a label.
DBDriver Directive
Description: | Specify an SQL driver |
---|---|
Syntax: | DBDriver name |
Context: | server config, virtual host |
Status: | Extension |
Module: | mod_dbd |
Selects an apr_dbd driver by name. The driver must be installed on your system (on most systems, it will be a shared object or dll). For example, DBDriver mysql
will select the MySQL driver in apr_dbd_mysql.so.
Please login to continue.