Apache Module mod_dbd

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.

Directives

Topics

See also

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.

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

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.

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.

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.

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.

Notice:This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our mailing lists.