]> granicus.if.org Git - apache/commitdiff
Committing mod_dbd as new.
authorNick Kew <niq@apache.org>
Wed, 18 May 2005 09:19:34 +0000 (09:19 +0000)
committerNick Kew <niq@apache.org>
Wed, 18 May 2005 09:19:34 +0000 (09:19 +0000)
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@170729 13f79535-47bb-0310-9956-ffa450edef68

CHANGES
docs/manual/mod/mod_dbd.xml [new file with mode: 0644]
docs/manual/mod/mod_dbd.xml.meta [new file with mode: 0644]
modules/experimental/mod_dbd.c [new file with mode: 0644]
modules/experimental/mod_dbd.h [new file with mode: 0644]

diff --git a/CHANGES b/CHANGES
index e1b0240511918ded322bfa3ab27a65c73cda0e16..f4a3f2dbb9df1f4954385435fe0eae75f03ffb08 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -2,6 +2,10 @@ Changes with Apache 2.1.5
 
   [Remove entries to the current 2.0 section below, when backported]
 
+  *) mod_dbd: New additions: mod_dbd.c, mod_dbd.h, mod_dbd.xml
+     Provide module hooks for apr_dbd; optimise for httpd
+     threaded and non-threaded arch [Nick Kew]
+
   *) ab: SSL support rewritten, improved, and enabled if SSL is enabled
      during the build; -f and -Z arguments added to specify SSL protocol
      options.  [Masaoki Kobayashi <masaoki techfirm.co.jp>]
diff --git a/docs/manual/mod/mod_dbd.xml b/docs/manual/mod/mod_dbd.xml
new file mode 100644 (file)
index 0000000..32c414a
--- /dev/null
@@ -0,0 +1,214 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 151408 $ -->
+
+<!--
+ Copyright 2004-2005 The Apache Software Foundation or its licensors, as
+ applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<modulesynopsis metafile="mod_dbd.xml.meta">
+
+<name>mod_dbd</name>
+<description>Manages SQL database connections</description>
+<status>Experimental</status>
+<sourcefile>mod_dbd.c</sourcefile>
+<identifier>dbd_module</identifier>
+<compatibility>Version 2.1 and higher</compatibility>
+
+<summary>
+    <p>mod_dbd manages SQL database connections using
+    <a href="http://people.apache.org/~niq/dbd.html">apr_dbd</a>.
+    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.</p>
+</summary>
+
+<section id="reslist"><title>Connection Pooling</title>
+    <p>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 <em>connection pool</em>, as
+    described in <a href="http://www.apachetutor.org/dev/reslist"
+    title="Connection pooling in Apache">this article at ApacheTutor</a>.
+    mod_dbd supersedes the modules presented in that article.</p>
+</section>
+
+<section id="API"><title>Apache DBD API</title>
+    <p>mod_dbd exports three functions for other modules to use.
+    The API is as follows:</p>
+<pre><code>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*));
+</code></pre>
+</section>
+
+<section id="prepared"><title>SQL Prepared Statements</title>
+    <p>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 <code>prepared</code> field of an <code>ap_dbd_t</code>.
+    Hash entries are of type <code>apr_dbd_prepared_t</code>
+    and can be used in any of the apr_dbd prepared statement
+    SQL query or select commands.</p>
+    <p>It is up to dbd user modules to use the prepared statements
+    and document what statements can be specified in httpd.conf.</p>
+</section>
+
+<directivesynopsis>
+<name>DBDriver</name>
+<description>Specify an SQL driver</description>
+<syntax>DBDriver <var>name</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>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, <samp>DBDriver mysql</samp> will select the MySQL
+    driver in apr_dbd_mysql.so.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>DBDParams</name>
+<description>Parameters for database connection</description>
+<syntax>DBDParams <var>param1=value1,param2=value2</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>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.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>DBDPersist</name>
+<description>Whether to use persistent connections</description>
+<syntax>DBDPersist <var>[0|1]</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>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.</p>
+    <p>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.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>DBDPrepareSQL</name>
+<description>Define an SQL prepared statement</description>
+<syntax>DBDPrepareSQL <var>"SQL statement"</var> <var>label</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>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.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>DBDMin</name>
+<description>Minimum number of connections</description>
+<syntax>DBDMin <var>number</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>Set the minimum number of connections per process (threaded
+    platforms only).</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>DBDKeep</name>
+<description>Maximum sustainednumber of connections</description>
+<syntax>DBDKeep <var>number</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>Set the maximum number of connections per process to be
+    sustained, other than for handling peak demand (threaded
+    platforms only).</p>
+</usage>
+</directivesynopsis>
+<directivesynopsis>
+<name>DBDMax</name>
+<description>Maximum number of connections</description>
+<syntax>DBDMax <var>number</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>Set the hard maximum number of connections per process
+    (threaded platforms only).</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>DBDExptime</name>
+<description>Keepalive time for idle connections</description>
+<syntax>DBDExptime <var>time-in-seconds</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>Set the time to keep idle connections alive where the number
+    of connections specified in DBDKeep has been exceeded (threaded
+    platforms only).</p>
+</usage>
+</directivesynopsis>
+
+
+</modulesynopsis>
+
diff --git a/docs/manual/mod/mod_dbd.xml.meta b/docs/manual/mod/mod_dbd.xml.meta
new file mode 100644 (file)
index 0000000..220ab31
--- /dev/null
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<metafile>
+  <basename>mod_dbd</basename>
+  <path>/mod/</path>
+  <relpath>..</relpath>
+
+  <variants>
+    <variant>en</variant>
+  </variants>
+</metafile>
diff --git a/modules/experimental/mod_dbd.c b/modules/experimental/mod_dbd.c
new file mode 100644 (file)
index 0000000..370568a
--- /dev/null
@@ -0,0 +1,461 @@
+/* Copyright 2003-5 WebThing Ltd
+ * Copyright 2005 The Apache Software Foundation or its licensors, as
+ * applicable.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* Overview of what this is and does:
+ * http://www.apache.org/~niq/dbd.html
+ * or
+ * http://apache.webthing.com/database/
+ */
+
+/* Bump the version for committing to apache svn */
+#define VERSION "0.2"
+
+#include <ctype.h>
+
+#include "http_protocol.h"
+#include "http_config.h"
+#include "http_log.h"
+#include "apr_reslist.h"
+#include "apr_strings.h"
+
+#include "apr_dbd.h"
+#include "mod_dbd.h"
+
+extern module AP_MODULE_DECLARE_DATA dbd_module;
+
+/************ svr cfg: manage db connection pool ****************/
+
+typedef struct dbd_prepared {
+    const char *label;
+    const char *query;
+    struct dbd_prepared *next;
+} dbd_prepared;
+typedef struct svr_cfg {
+    const char *name;
+    const char *params;
+    int persist;
+    dbd_prepared *prepared;
+#if APR_HAS_THREADS
+    apr_reslist_t *dbpool;
+    int nmin;
+    int nkeep;
+    int nmax;
+    int exptime;
+#else
+    ap_dbd_t *conn;
+#endif
+} svr_cfg;
+
+typedef enum { cmd_name, cmd_params, cmd_persist,
+               cmd_min, cmd_keep, cmd_max, cmd_exp
+} cmd_parts;
+
+
+#define ISINT(val) \
+        for (p = val; *p; ++p)        \
+                if (!isdigit(*p))        \
+                        return "Argument must be numeric!"
+static const char *dbd_param(cmd_parms *cmd, void *cfg, const char *val)
+{
+    const char *p;
+    apr_dbd_driver_t *driver = NULL;
+    svr_cfg *svr = (svr_cfg*) ap_get_module_config
+        (cmd->server->module_config, &dbd_module);
+
+    switch ((int) cmd->info) {
+    case cmd_name:
+        svr->name = val;
+        /* loading the driver involves once-only dlloading that is
+         * best done at server startup.  This also guarantees that
+         * load_driver won't return an error later.
+         */
+        switch (apr_dbd_get_driver(cmd->pool, svr->name, &driver)) {
+        case APR_ENOTIMPL:
+            return apr_psprintf(cmd->pool, "DBD: No driver for %s", svr->name);
+        case APR_EDSOOPEN:
+            return apr_psprintf(cmd->pool,
+                                "DBD: Can't load driver file apr_dbd_%s.so",
+                                svr->name);
+        case APR_ESYMNOTFOUND:
+            return apr_psprintf(cmd->pool,
+                                "DBD: Failed to load driver apr_dbd_%s_driver",
+                                svr->name);
+        }
+        break;
+    case cmd_params:
+        svr->params = val;
+        break;
+    case cmd_persist:
+        ISINT(val);
+        svr->persist = atoi(val);
+        break;
+#if APR_HAS_THREADS
+    case cmd_min:
+        ISINT(val);
+        svr->nmin = atoi(val);
+        break;
+    case cmd_keep:
+        ISINT(val);
+        svr->nkeep = atoi(val);
+        break;
+    case cmd_max:
+        ISINT(val);
+        svr->nmax = atoi(val);
+        break;
+    case cmd_exp:
+        ISINT(val);
+        svr->exptime = atoi(val);
+        break;
+#endif
+    }
+    return NULL;
+}
+static const char *dbd_prepare(cmd_parms *cmd, void *cfg, const char *query,
+                               const char *label)
+{
+    svr_cfg *svr = (svr_cfg*) ap_get_module_config
+        (cmd->server->module_config, &dbd_module);
+    dbd_prepared *prepared = apr_pcalloc(cmd->pool, sizeof(dbd_prepared));
+    prepared->label = label;
+    prepared->query = query;
+    prepared->next = svr->prepared;
+    svr->prepared = prepared;
+    return NULL;
+}
+static const command_rec dbd_cmds[] = {
+    AP_INIT_TAKE1("DBDriver", dbd_param, (void*)cmd_name, RSRC_CONF,
+                  "SQL Driver"),
+    AP_INIT_TAKE1("DBDParams", dbd_param, (void*)cmd_params, RSRC_CONF,
+                  "SQL Driver Params"),
+    AP_INIT_TAKE1("DBDPersist", dbd_param, (void*)cmd_persist, RSRC_CONF,
+                  "Use persistent connection/pool"),
+    AP_INIT_TAKE2("DBDPrepareSQL", dbd_prepare, NULL, RSRC_CONF,
+                  "Prepared SQL statement, label"),
+#if APR_HAS_THREADS
+    AP_INIT_TAKE1("DBDMin", dbd_param, (void*)cmd_min, RSRC_CONF,
+                  "Minimum number of connections"),
+    AP_INIT_TAKE1("DBDKeep", dbd_param, (void*)cmd_keep, RSRC_CONF,
+                  "Maximum number of sustained connections"),
+    AP_INIT_TAKE1("DBDMax", dbd_param, (void*)cmd_max, RSRC_CONF,
+                  "Maximum number of connections"),
+    AP_INIT_TAKE1("DBDExptime", dbd_param, (void*)cmd_exp, RSRC_CONF,
+                  "Keepalive time for idle connections"),
+#endif
+    {NULL}
+};
+#define COND_PARAM(x,val) \
+    if (cfg->x == val) {              \
+        cfg->x = ((svr_cfg*)base)->x; \
+    }
+#define COND_PARAM0(x) COND_PARAM(x,0)
+#define COND_PARAM1(x) COND_PARAM(x,-1)
+static void *dbd_merge(apr_pool_t *pool, void *base, void *add) {
+    svr_cfg *cfg = apr_pmemdup(pool, add, sizeof(svr_cfg));
+    COND_PARAM0(name);
+    COND_PARAM0(params);
+    COND_PARAM1(persist);
+#if APR_HAS_THREADS
+    COND_PARAM0(nmin);
+    COND_PARAM0(nkeep);
+    COND_PARAM0(nmax);
+    COND_PARAM0(exptime);
+#endif
+    return cfg;
+}
+#undef COND_PARAM
+#undef COND_PARAM0
+#undef COND_PARAM1
+static void *dbd_cfg(apr_pool_t *p, server_rec *x)
+{
+    svr_cfg *svr = (svr_cfg*) apr_pcalloc(p, sizeof(svr_cfg));
+    svr->persist = -1;
+    return svr;
+}
+static apr_status_t dbd_prepared_init(apr_pool_t *pool, svr_cfg *svr,
+                                      ap_dbd_t *dbd)
+{
+    dbd_prepared *p;
+    apr_status_t ret = APR_SUCCESS;
+    apr_dbd_prepared_t *stmt = NULL;
+    dbd->prepared = apr_hash_make(pool);
+
+    for (p = svr->prepared; p; p = p->next) {
+        if (apr_dbd_prepare(dbd->driver, pool, dbd->handle, p->query,
+                            p->label, &stmt) == 0) {
+            apr_hash_set(dbd->prepared, p->label, APR_HASH_KEY_STRING, stmt);
+        }
+        else {
+            ret = APR_EGENERAL;
+        }
+    }
+    return ret;
+}
+#if APR_HAS_THREADS
+/************ svr cfg: manage db connection pool ****************/
+/* an apr_reslist_constructor for SQL connections */
+static apr_status_t dbd_construct(void **db, void *params, apr_pool_t *pool)
+{
+    svr_cfg *svr = (svr_cfg*) params;
+    ap_dbd_t *rec = apr_pcalloc(pool, sizeof(ap_dbd_t));
+    apr_status_t rv = apr_dbd_get_driver(pool, svr->name, &rec->driver);
+
+    rv = apr_dbd_open(rec->driver, pool, svr->params, &rec->handle);
+    switch (rv) {
+    case APR_EGENERAL:
+        ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,
+                      "DBD: Can't connect to %s[%s]", svr->name, svr->params);
+        return rv;
+    }
+    *db = rec;
+    dbd_prepared_init(pool, svr, rec);
+    return rv;
+}
+static apr_status_t dbd_destruct(void *sql, void *params, apr_pool_t *pool)
+{
+    ap_dbd_t *rec = sql;
+    return apr_dbd_close(rec->driver, rec->handle);
+}
+
+static apr_status_t dbd_setup(apr_pool_t *pool, server_rec *s)
+{
+    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);
+    apr_status_t rv = apr_reslist_create(&svr->dbpool, svr->nmin, svr->nkeep,
+                                         svr->nmax, svr->exptime,
+                                         dbd_construct, dbd_destruct,
+                                         svr, pool);
+    if (rv == APR_SUCCESS) {
+        apr_pool_cleanup_register(pool, svr->dbpool,
+                                  (void*)apr_reslist_destroy,
+                                  apr_pool_cleanup_null);
+    }
+    else {
+        ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,
+                      "DBD Pool: failed to initialise");
+    }
+    return rv;
+}
+
+#endif
+
+
+/* Functions we export for modules to use:
+        - open acquires a connection from the pool (opens one if necessary)
+        - close releases it back in to the pool
+*/
+
+#if APR_HAS_THREADS
+ap_dbd_t* ap_dbd_open(apr_pool_t *pool, server_rec *s)
+{
+    ap_dbd_t *rec = NULL;
+    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);
+    apr_status_t rv;
+    const char *errmsg;
+
+    if (!svr->persist) {
+        rec = apr_pcalloc(pool, sizeof(ap_dbd_t));
+        rv = apr_dbd_get_driver(pool, svr->name, &rec->driver);
+
+        rv = apr_dbd_open(rec->driver, pool, svr->params, &rec->handle);
+        switch (rv) {
+        case APR_EGENERAL:
+            ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,
+                          "DBD: Can't connect to %s[%s]",
+                          svr->name, svr->params);
+            return NULL;
+        }
+        dbd_prepared_init(pool, svr, rec);
+        return rec;
+    }
+
+    if (!svr->dbpool) {
+        if (dbd_setup(s->process->pool, s) != APR_SUCCESS) {
+            return NULL;
+        }
+    }
+    if (apr_reslist_acquire(svr->dbpool, (void**)&rec) != APR_SUCCESS) {
+        ap_log_perror(APLOG_MARK, APLOG_ERR, 0, pool,
+                      "Failed to acquire DBD connection from pool!");
+        return NULL;
+    }
+    if (apr_dbd_check_conn(rec->driver, pool, rec->handle) != APR_SUCCESS) {
+        errmsg = apr_dbd_error(rec->driver, rec->handle, rv);
+        if (!errmsg) {
+            errmsg = "(unknown)";
+        }
+        ap_log_perror(APLOG_MARK, APLOG_ERR, 0, pool,
+                      "DBD[%s] Error: %s", svr->name, errmsg );
+        apr_reslist_invalidate(svr->dbpool, rec);
+        return NULL;
+    }
+    return rec;
+}
+#else
+ap_dbd_t* ap_dbd_open(apr_pool_t *pool, server_rec *s)
+{
+    apr_status_t rv;
+    const char *errmsg;
+    ap_dbd_t *rec = NULL;
+    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);
+
+    if (!svr->persist) {
+        rec = apr_pcalloc(pool, sizeof(ap_dbd_t));
+        rv = apr_dbd_get_driver(pool, svr->name, &rec->driver);
+
+        rv = apr_dbd_open(rec->driver, pool, svr->params, &rec->handle);
+        switch (rv) {
+        case APR_EGENERAL:
+            ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,
+                          "DBD: Can't connect to %s[%s]",
+                          svr->name, svr->params);
+            return NULL;
+        }
+        dbd_prepared_init(pool, svr, rec);
+        return rec;
+    }
+/* since we're in nothread-land, we can mess with svr->conn with impunity */
+    if (svr->conn) {
+        if (apr_dbd_check_conn(svr->conn->driver, pool, svr->conn->handle) != 0){
+            errmsg = apr_dbd_error(rec->driver, rec->handle, rv);
+            if (!errmsg) {
+                errmsg = "(unknown)";
+            }
+            ap_log_perror(APLOG_MARK, APLOG_ERR, 0, pool,
+                          "DBD[%s] Error: %s", svr->name, errmsg);
+            svr->conn = NULL;
+        }
+    }
+    if (!svr->conn) {
+        svr->conn = apr_pcalloc(pool, sizeof(ap_dbd_t));
+        rv = apr_dbd_get_driver(pool, svr->name, &svr->conn->driver);
+
+        rv = apr_dbd_open(svr->conn->driver, pool, svr->params,
+                          &svr->conn->handle);
+        switch (rv) {
+        case APR_EGENERAL:
+            ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,
+                          "DBD: Can't connect to %s[%s]",
+                          svr->name, svr->params);
+            return NULL;
+        }
+        dbd_prepared_init(pool, svr, rec);
+    }
+    return svr->conn;
+}
+#endif
+void ap_dbd_close(server_rec *s, ap_dbd_t *sql)
+{
+    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);
+    if (!svr->persist) {
+        apr_dbd_close(sql->driver, sql->handle);
+    }
+#if APR_HAS_THREADS
+    else {
+        apr_reslist_release(svr->dbpool, sql);
+    }
+#endif
+}
+#if APR_HAS_THREADS
+typedef struct {
+    ap_dbd_t *conn;
+    apr_reslist_t *dbpool;
+} dbd_pool_rec;
+static apr_status_t dbd_release(void *REQ)
+{
+    dbd_pool_rec *req = REQ;
+    apr_reslist_release(req->dbpool, req->conn);
+    return APR_SUCCESS;
+}
+ap_dbd_t *ap_dbd_acquire(request_rec *r)
+{
+    svr_cfg *svr;
+    dbd_pool_rec *req = ap_get_module_config(r->request_config, &dbd_module);
+    if (!req) {
+        req = apr_palloc(r->pool, sizeof(dbd_pool_rec));
+        req->conn = ap_dbd_open(r->pool, r->server);
+        if (req->conn) {
+            svr = ap_get_module_config(r->server->module_config, &dbd_module);
+            ap_set_module_config(r->request_config, &dbd_module, req);
+            if (svr->persist) {
+                req->dbpool = svr->dbpool;
+                apr_pool_cleanup_register(r->pool, req, dbd_release,
+                                          apr_pool_cleanup_null);
+            }
+            else {
+                apr_pool_cleanup_register(r->pool, req->conn->handle,
+                                          (void*)req->conn->driver->close,
+                                          apr_pool_cleanup_null);
+            }
+        }
+    }
+    return req->conn;
+}
+#else
+ap_dbd_t *ap_dbd_acquire(request_rec *r)
+{
+    svr_cfg *svr;
+    ap_dbd_t *ret = ap_get_module_config(r->request_config, &dbd_module);
+    if (!ret) {
+        svr = ap_get_module_config(r->server->module_config, &dbd_module);
+        ret = ap_dbd_open(r->pool, r->server);
+        if ( ret ) {
+            ap_set_module_config(r->request_config, &dbd_module, ret);
+            if (!svr->persist) {
+                apr_pool_cleanup_register(r->pool, svr->conn->handle,
+                                          (void*)svr->conn->driver->close,
+                                          apr_pool_cleanup_null);
+            }
+            /* if persist then dbd_open registered cleanup on proc pool */
+        }
+    }
+    return ret;
+}
+#endif
+static int dbd_token(apr_pool_t *pool,  apr_pool_t *p0,
+                     apr_pool_t *p1, server_rec *s)
+{
+    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);
+    if (svr && svr->name) {
+        ap_add_version_component(pool, apr_psprintf(pool, "DBD:%s/%s",
+                                                    svr->name, VERSION));
+    }
+    else {
+        ap_add_version_component(pool, "DBD/" VERSION);
+    }
+    return OK;
+}
+
+static void dbd_hooks(apr_pool_t *pool)
+{
+#if APR_HAS_THREADS
+    ap_hook_child_init((void*)dbd_setup, NULL, NULL, APR_HOOK_MIDDLE);
+#endif
+    ap_hook_post_config(dbd_token, NULL, NULL, APR_HOOK_MIDDLE);
+    APR_REGISTER_OPTIONAL_FN(ap_dbd_open);
+    APR_REGISTER_OPTIONAL_FN(ap_dbd_close);
+    APR_REGISTER_OPTIONAL_FN(ap_dbd_acquire);
+    apr_dbd_init(pool);
+}
+
+module AP_MODULE_DECLARE_DATA dbd_module = {
+    STANDARD20_MODULE_STUFF,
+    NULL,
+    NULL,
+    dbd_cfg,
+    dbd_merge,
+    dbd_cmds,
+    dbd_hooks
+};
diff --git a/modules/experimental/mod_dbd.h b/modules/experimental/mod_dbd.h
new file mode 100644 (file)
index 0000000..75738d9
--- /dev/null
@@ -0,0 +1,41 @@
+/*        Copyright (c) 2004, Nick Kew.  All rights reserved.
+
+        If this is accepted by ASF for inclusion in APR-UTIL,
+        I will assign copyright to ASF and license under ASF terms.
+
+        Otherwise I will retain copyright and license under
+        terms of my choice.
+*/
+#ifndef DBD_H
+#define DBD_H
+
+#include <httpd.h>
+#include <apr_optional.h>
+#include <apr_hash.h>
+
+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*));
+
+#endif