Apache HTTP Server Version 2.1

Apache > HTTP Server > Documentation > Version 2.1 > Modules

# Apache Module mod_dbd

Available Languages: en

Description: | Manages SQL database connections
Status: | Experimental
Module Identifier: | dbd_module
Source File: | mod_dbd.c
Compatibility: | Version 2.1 and higher

### Summary

`mod_dbd` manages SQL database connections using apr_dbd. 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.

### Directives

### Topics

- Connection Pooling
- Apache DBD API
- SQL Prepared Statements

## 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. `mod_dbd` supersedes the modules presented in that article.

## Apache DBD API

`mod_dbd` exports three 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*);

    /* 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*));

## 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.

## DBDExptime Directive

Description: | Keepalive time for idle connections
Syntax: | `DBDExptime time-in-seconds`
Context: | server config, virtual host
Status: | Experimental
Module: | mod_dbd

Set the time to keep idle connections alive where the number of connections specified in DBDKeep has been exceeded (threaded platforms only).

## DBDKeep Directive

Description: | Maximum sustainednumber of connections
Syntax: | `DBDKeep number`
Context: | server config, virtual host
Status: | Experimental
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`
Context: | server config, virtual host
Status: | Experimental
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`
Context: | server config, virtual host
Status: | Experimental
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: | Experimental
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.

## DBDPersist Directive

Description: | Whether to use persistent connections
Syntax: | `DBDPersist 0|1`
Context: | server config, virtual host
Status: | Experimental
Module: | mod_dbd

If set to 0, 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.

## DBDPrepareSQL Directive

Description: | Define an SQL prepared statement
Syntax: | `DBDPrepareSQL "SQL statement" label`
Context: | server config, virtual host
Status: | Experimental
Module: | mod_dbd

For modules such as authentication that use 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: | Experimental
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.

Available Languages: en