From fe39ffb8b90ae4e002ed73fe98617cd590abb467 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 08:33:50 +0200 Subject: Adding upstream version 2.4.56. Signed-off-by: Daniel Baumann --- docs/manual/mod/mod_dbd.html.en | 394 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 docs/manual/mod/mod_dbd.html.en (limited to 'docs/manual/mod/mod_dbd.html.en') diff --git a/docs/manual/mod/mod_dbd.html.en b/docs/manual/mod/mod_dbd.html.en new file mode 100644 index 0000000..b2aea5b --- /dev/null +++ b/docs/manual/mod/mod_dbd.html.en @@ -0,0 +1,394 @@ + + + + + +mod_dbd - Apache HTTP Server Version 2.4 + + + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.4

+
+
<-
+ +
+

Apache Module mod_dbd

+
+

Available Languages:  en  | + fr 

+
+ + + + +
Description:Manages SQL database connections
Status:Extension
Module Identifier:dbd_module
Source File:mod_dbd.c
Compatibility:Version 2.1 and later
+

Summary

+ +

mod_dbd manages SQL database connections using + APR. 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. For details, see the + APR website and this overview of the + Apache DBD Framework + by its original developer. +

+
+ +
top
+
+

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

+
top
+
+

Connecting

+ +

To connect to your database, you'll need to specify + a driver, and connection parameters. These vary from + one database engine to another. For example, to connect + to mysql, do the following:

+ +
DBDriver mysql
+DBDParams host=localhost,dbname=pony,user=shetland,pass=appaloosa
+ + +

You can then use this connection in a variety of other + modules, including mod_rewrite, + mod_authn_dbd, and mod_lua. + Further usage examples appear in each of those modules' + documentation.

+ +

See DBDParams for connection string + information for each of the supported database drivers.

+ +
top
+
+

Apache DBD API

+

mod_dbd exports five 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*);
+
+/* 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*));
+ +
top
+
+

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, + or to provide their own directives and use ap_dbd_prepare.

+ +

Caveat

+ When using prepared statements with a MySQL database, it is preferred to set + reconnect 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. +
+
top
+
+

SECURITY WARNING

+ +

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.

+

However, the FreeTDS driver is inherently + unsafe. The underlying library doesn't support + prepared statements, so the driver emulates them, and the + untrusted input is merged into the SQL statement.

+

It can be made safe by untainting 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:

+ 
  $untrusted =~ /([a-z]+)/;
+  $trusted = $1;
+

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:

+

+ "SELECT foo FROM bar WHERE input = %s" +

+

with other drivers, and suffer nothing worse than a failed query. + But with FreeTDS you'd need:

+

+ "SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s" +

+

Now anything that doesn't match the regexp's $1 match is + discarded, so the statement is safe.

+

An alternative to this may be the third-party ODBC driver, + which offers the security of genuine prepared statements.

+
+
top
+

DBDExptime Directive

+ + + + + + + +
Description:Keepalive time for idle connections
Syntax:DBDExptime time-in-seconds
Default:DBDExptime 300
Context:server config, virtual host
Status:Extension
Module:mod_dbd
+

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

+ +
+
top
+

DBDInitSQL Directive

+ + + + + + +
Description:Execute an SQL statement after connecting to a database
Syntax:DBDInitSQL "SQL statement"
Context:server config, virtual host
Status:Extension
Module:mod_dbd
+

Modules, that wish it, can have one or more SQL statements + executed when a connection to a database is created. Example + usage could be initializing certain values or adding a log + entry when a new connection is made to the database.

+ +
+
top
+

DBDKeep Directive

+ + + + + + + +
Description:Maximum sustained number of connections
Syntax:DBDKeep number
Default:DBDKeep 2
Context:server config, virtual host
Status:Extension
Module:mod_dbd
+

Set the maximum number of connections per process to be + sustained, other than for handling peak demand (threaded + platforms only).

+ +
+
top
+

DBDMax Directive

+ + + + + + + +
Description:Maximum number of connections
Syntax:DBDMax number
Default:DBDMax 10
Context:server config, virtual host
Status:Extension
Module:mod_dbd
+

Set the hard maximum number of connections per process + (threaded platforms only).

+ +
+
top
+

DBDMin Directive

+ + + + + + + +
Description:Minimum number of connections
Syntax:DBDMin number
Default:DBDMin 1
Context:server config, virtual host
Status:Extension
Module:mod_dbd
+

Set the minimum number of connections per process (threaded + platforms only).

+ +
+
top
+

DBDParams Directive

+ + + + + + +
Description:Parameters for database connection
Syntax:DBDParams +param1=value1[,param2=value2]
Context:server config, virtual host
Status:Extension
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.

+

Connection string parameters for current drivers include:

+
+
FreeTDS (for MSSQL and SyBase)
+
username, password, appname, dbname, host, charset, lang, server
+
MySQL
+
host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect
+
Oracle
+
user, pass, dbname, server
+
PostgreSQL
+
The connection string is passed straight through to PQconnectdb
+
SQLite2
+
The connection string is split on a colon, and part1:part2 is used as sqlite_open(part1, atoi(part2), NULL)
+
SQLite3
+
The connection string is passed straight through to sqlite3_open
+
ODBC
+
datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize
+
+ +
+
top
+

DBDPersist Directive

+ + + + + + +
Description:Whether to use persistent connections
Syntax:DBDPersist On|Off
Context:server config, virtual host
Status:Extension
Module:mod_dbd
+

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

+ +

Prior to version 2.2.2, this directive accepted only the values + 0 and 1 instead of Off and + On, respectively.

+ +
+
top
+

DBDPrepareSQL Directive

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

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

+ +
+
top
+

DBDriver Directive

+ + + + + + +
Description:Specify an SQL driver
Syntax:DBDriver name
Context:server config, virtual host
Status:Extension
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  | + fr 

+
top

Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our mailing lists.
+
+ \ No newline at end of file -- cgit v1.2.3