diff options
Diffstat (limited to 'docs/manual/mod/mod_dbd.html.en')
| -rw-r--r-- | docs/manual/mod/mod_dbd.html.en | 228 |
1 files changed, 114 insertions, 114 deletions
diff --git a/docs/manual/mod/mod_dbd.html.en b/docs/manual/mod/mod_dbd.html.en index 4cb913f729..05eefa48a5 100644 --- a/docs/manual/mod/mod_dbd.html.en +++ b/docs/manual/mod/mod_dbd.html.en @@ -66,120 +66,6 @@ <li><a href="../misc/password_encryptions.html">Password Formats</a></li> </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> -<div class="section"> -<h2><a name="pooling" id="pooling">Connection Pooling</a></h2> - <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">this - article at ApacheTutor</a>. Note that <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> - supersedes the modules presented in that article.</p> -</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> -<div class="section"> -<h2><a name="API" id="API">Apache DBD API</a></h2> - <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> exports five functions for other modules - to use. The API is as follows:</p> - -<pre class="prettyprint lang-c">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*); - -/* acquire a connection that will have the lifetime of a connection - * and MUST NOT be explicitly closed. Return NULL on error. - */ -AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*); - -/* Prepare a statement for use by a client module */ -AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*); - -/* 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*)); -APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*)); -APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));</pre> - -</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> -<div class="section"> -<h2><a name="prepared" id="prepared">SQL Prepared Statements</a></h2> - <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> 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, - or to provide their own directives and use <code>ap_dbd_prepare</code>.</p> - - <div class="warning"><h3>Caveat</h3> - When using prepared statements with a MySQL database, it is preferred to set - <code>reconnect</code> 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. - </div> -</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> -<div class="section"> -<h2><a name="security" id="security">SECURITY WARNING</a></h2> - - <p>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.</p> - <p>However, the <var>FreeTDS</var> driver is inherently - <strong>unsafe</strong>. The underlying library doesn't support - prepared statements, so the driver emulates them, and the - untrusted input is merged into the SQL statement.</p> - <p>It can be made safe by <em>untainting</em> 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:</p> - <div class="example"><pre><code> $untrusted =~ /([a-z]+)/; - $trusted = $1;</code></pre></div> - <p>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:</p> - <div class="example"><p><code> - <code>"SELECT foo FROM bar WHERE input = %s"</code> - </code></p></div> - <p>with other drivers, and suffer nothing worse than a failed query. - But with FreeTDS you'd need:</p> - <div class="example"><p><code> - <code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code> - </code></p></div> - <p>Now anything that doesn't match the regexp's $1 match is - discarded, so the statement is safe.</p> - <p>An alternative to this may be the third-party ODBC driver, - which offers the security of genuine prepared statements.</p> -</div> -<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="directive-section"><h2><a name="DBDExptime" id="DBDExptime">DBDExptime</a> <a name="dbdexptime" id="dbdexptime">Directive</a></h2> <table class="directive"> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Keepalive time for idle connections</td></tr> @@ -337,6 +223,120 @@ APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const c driver in apr_dbd_mysql.so.</p> </div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="pooling" id="pooling">Connection Pooling</a></h2> + <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">this + article at ApacheTutor</a>. Note that <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> + supersedes the modules presented in that article.</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="API" id="API">Apache DBD API</a></h2> + <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> exports five functions for other modules + to use. The API is as follows:</p> + +<pre class="prettyprint lang-c">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*); + +/* acquire a connection that will have the lifetime of a connection + * and MUST NOT be explicitly closed. Return NULL on error. + */ +AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*); + +/* Prepare a statement for use by a client module */ +AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*); + +/* 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*)); +APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*)); +APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));</pre> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="prepared" id="prepared">SQL Prepared Statements</a></h2> + <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> 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, + or to provide their own directives and use <code>ap_dbd_prepare</code>.</p> + + <div class="warning"><h3>Caveat</h3> + When using prepared statements with a MySQL database, it is preferred to set + <code>reconnect</code> 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. + </div> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="security" id="security">SECURITY WARNING</a></h2> + + <p>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.</p> + <p>However, the <var>FreeTDS</var> driver is inherently + <strong>unsafe</strong>. The underlying library doesn't support + prepared statements, so the driver emulates them, and the + untrusted input is merged into the SQL statement.</p> + <p>It can be made safe by <em>untainting</em> 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:</p> + <div class="example"><pre><code> $untrusted =~ /([a-z]+)/; + $trusted = $1;</code></pre></div> + <p>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:</p> + <div class="example"><p><code> + <code>"SELECT foo FROM bar WHERE input = %s"</code> + </code></p></div> + <p>with other drivers, and suffer nothing worse than a failed query. + But with FreeTDS you'd need:</p> + <div class="example"><p><code> + <code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code> + </code></p></div> + <p>Now anything that doesn't match the regexp's $1 match is + discarded, so the statement is safe.</p> + <p>An alternative to this may be the third-party ODBC driver, + which offers the security of genuine prepared statements.</p> +</div> </div> <div class="bottomlang"> <p><span>Available Languages: </span><a href="../en/mod/mod_dbd.html" title="English"> en </a> | |