1<!--$Id: mod.so,v 10.6 2007/07/07 14:45:24 bostic Exp $-->
2<!--Copyright (c) 1997,2008 Oracle.  All rights reserved.-->
3<!--See the file LICENSE for redistribution information.-->
4<html>
5<head>
6<title>Berkeley DB Reference Guide: Using Berkeley DB with Apache</title>
7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
9</head>
10<body bgcolor=white>
11<a name="2"><!--meow--></a><a name="3"><!--meow--></a>
12<table width="100%"><tr valign=top>
13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Extensions</dl></b></td>
14<td align=right><a href="../tcl/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../ext/perl.html"><img src="../../images/next.gif" alt="Next"></a>
15</td></tr></table>
16<p align=center><b>Using Berkeley DB with Apache</b></p>
17<p>A mod_db4 Apache module is included in the Berkeley DB distribution, providing
18a safe framework for running Berkeley DB applications in an Apache 1.3
19environment.  Apache natively provides no interface for communication
20between threads or processes, so the mod_db4 module exists to provide
21this communication.</p>
22<p>In general, it is dangerous to run Berkeley DB in a multiprocess system
23without some facility to coordinate database recovery between processes
24sharing the database environment after application or system failure.
25Failure to run recovery after failure can include process hangs and an
26inability to access the database environment.  The mod_db4 Apache module
27oversees the proper management of Berkeley DB database environment resources.
28Developers building applications using Berkeley DB as the storage manager
29within an Apache module should employ this technique for proper resource
30management.</p>
31<p>Specifically, mod_db4 provides the following facilities:</p>
32<ol>
33<p><li>New constructors for <a href="../../api_c/env_class.html">DB_ENV</a> and <a href="../../api_c/db_class.html">DB</a> handles, which install
34replacement open/close methods.
35<p><li>Transparent caching of open <a href="../../api_c/env_class.html">DB_ENV</a> and <a href="../../api_c/db_class.html">DB</a> handles.
36<p><li>Reference counting on all structures, allowing the module to detect the
37initial opening of any managed database and automatically perform recovery.
38<p><li>Automatic detection of unexpected failures (segfaults, or a module
39actually calling exit() and avoiding shut down phases), and automatic
40termination of all child processes with open database resources to
41attempt consistency.
42</ol>
43<p>mod_db4 is designed to be used as an alternative interface to Berkeley DB.  To
44have another Apache module (for example, mod_foo) use mod_db4, do not
45link mod_foo against the Berkeley DB library.  In your mod_foo makefile, you
46should:</p>
47<blockquote><pre>#include "mod_db4_export.h"</pre></blockquote>
48<p>and add your Apache include directory to your CPPFLAGS.</p>
49<p>In mod_foo, to create a mod_db4 managed <a href="../../api_c/env_class.html">DB_ENV</a> handle, use the
50following:</p>
51<blockquote><pre>int mod_db4_db_env_create(DB_ENV **dbenvp, u_int32_t flags);</pre></blockquote>
52<p>which takes identical arguments to <a href="../../api_c/env_class.html">db_env_create</a>.</p>
53<p>To create a mod_db4 managed <a href="../../api_c/db_class.html">DB</a> handle, use the following:</p>
54<blockquote><pre>int mod_db4_db_create(DB **dbp, DB_ENV *dbenv, u_int32_t flags);</pre></blockquote>
55<p>which takes identical arguments to <a href="../../api_c/db_class.html">db_create</a>.</p>
56<p>Otherwise the API is completely consistent with the standard Berkeley DB
57API.</p>
58<p>The mod_db4 module requires the Berkeley DB library be compiled with C++
59extensions and the MM library.  (The MM library provides an abstraction
60layer which allows related processes to share data easily. On systems
61where shared memory or other inter-process communication mechanisms are
62not available, the MM library emulates them using temporary files. MM
63is used in several operating systems to provide shared memory pools to
64Apache modules.)</p>
65<p>To build this apache module, perform the following steps:</p>
66<blockquote><pre>% ./configure --with-apxs=[path to the apxs utility] \
67	--with-db4=[Berkeley DB library installation directory] \
68	--with-mm=[libmm installation directory]
69% make
70% make install</pre></blockquote>
71<p>Post-installation, modules can use this extension via the functions
72documented in $APACHE_INCLUDEDIR/mod_db4_export.h.</p>
73<table width="100%"><tr><td><br></td><td align=right><a href="../tcl/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../ext/perl.html"><img src="../../images/next.gif" alt="Next"></a>
74</td></tr></table>
75<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
76</body>
77</html>
78