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.

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.

+ +