1Apache::DBI(3)        User Contributed Perl Documentation       Apache::DBI(3)
2
3
4

NAME

6       Apache::DBI - Initiate a persistent database connection
7

SYNOPSIS

9        # Configuration in httpd.conf or startup.pl:
10
11        PerlModule Apache::DBI  # this comes before all other modules using DBI
12
13       Do NOT change anything in your scripts. The usage of this module is
14       absolutely transparent !
15

DESCRIPTION

17       This module initiates a persistent database connection.
18
19       The database access uses Perl's DBI. For supported DBI drivers see:
20
21        http://dbi.perl.org/
22
23       When loading the DBI module (do not confuse this with the Apache::DBI
24       module) it checks if the environment variable 'MOD_PERL' has been set
25       and if the module Apache::DBI has been loaded. In this case every
26       connect request will be forwarded to the Apache::DBI module. This
27       checks if a database handle from a previous connect request is already
28       stored and if this handle is still valid using the ping method. If
29       these two conditions are fulfilled it just returns the database handle.
30       The parameters defining the connection have to be exactly the same,
31       including the connect attributes! If there is no appropriate database
32       handle or if the ping method fails, a new connection is established and
33       the handle is stored for later re-use. There is no need to remove the
34       disconnect statements from your code. They won't do anything because
35       the Apache::DBI module overloads the disconnect method.
36
37       The Apache::DBI module still has a limitation: it keeps database
38       connections persistent on a per process basis. The problem is, if a
39       user accesses a database several times, the http requests will be
40       handled very likely by different processes. Every process needs to do
41       its own connect. It would be nice if all servers could share the
42       database handles, but currently this is not possible because of the
43       distinct memory-space of each process. Also it is not possible to
44       create a database handle upon startup of the httpd and then inherit
45       this handle to every subsequent server. This will cause clashes when
46       the handle is used by two processes at the same time.  Apache::DBI has
47       built-in protection against this.  It will not make a connection
48       persistent if it sees that it is being opened during the server
49       startup.  This allows you to safely open a connection for grabbing data
50       needed at startup and disconnect it normally before the end of startup.
51
52       With this limitation in mind, there are scenarios, where the usage of
53       Apache::DBI is depreciated. Think about a heavy loaded Web-site where
54       every user connects to the database with a unique userid. Every server
55       would create many database handles each of which spawning a new backend
56       process. In a short time this would kill the web server.
57
58       Another problem are timeouts: some databases disconnect the client
59       after a certain period of inactivity. The module tries to validate the
60       database handle using the ping() method of the DBI-module. This method
61       returns true by default.  Most DBI drivers have a working ping()
62       method, but if the driver you're using doesn't have one and the
63       database handle is no longer valid, you will get an error when
64       accessing the database. As a work-around you can try to add your own
65       ping() method using any database command which is cheap and safe, or
66       you can deactivate the usage of the ping method (see CONFIGURATION
67       below).
68
69       Here is a generalized ping method, which can be added to the driver
70       module:
71
72          package DBD::xxx::db; # ====== DATABASE ======
73          use strict;
74
75          sub ping {
76            my ($dbh) = @_;
77            my $ret = 0;
78            eval {
79              local $SIG{__DIE__}  = sub { return (0); };
80              local $SIG{__WARN__} = sub { return (0); };
81              # adapt the select statement to your database:
82              $ret = $dbh->do('select 1');
83            };
84            return ($@) ? 0 : $ret;
85          }
86
87       Transactions: a standard DBI script will automatically perform a
88       rollback whenever the script exits. In the case of persistent database
89       connections, the database handle will not be destroyed and hence no
90       automatic rollback will occur. At a first glance it even seems possible
91       to handle a transaction over multiple requests. But this should be
92       avoided, because different requests are handled by different processes
93       and a process does not know the state of a specific transaction which
94       has been started by another process. In general, it is good practice to
95       perform an explicit commit or rollback at the end of every request. In
96       order to avoid inconsistencies in the database in case AutoCommit is
97       off and the script finishes without an explicit rollback, the
98       Apache::DBI module uses a PerlCleanupHandler to issue a rollback at the
99       end of every request. Note, that this CleanupHandler will only be used,
100       if the initial data_source sets AutoCommit = 0 or AutoCommit is turned
101       off, after the connect has been done (ie begin_work). However, because
102       a connection may have set other parameters, the handle is reset to its
103       initial connection state before it is returned for a second time.
104
105       This module plugs in a menu item for Apache::Status or Apache2::Status.
106       The menu lists the current database connections. It should be
107       considered incomplete because of the limitations explained above. It
108       shows the current database connections for one specific process, the
109       one which happens to serve the current request.  Other processes might
110       have other database connections.  The Apache::Status/Apache2::Status
111       module has to be loaded before the Apache::DBI module !
112

CONFIGURATION

114       The module should be loaded upon startup of the Apache daemon.  Add the
115       following line to your httpd.conf or startup.pl:
116
117        PerlModule Apache::DBI
118
119       It is important, to load this module before any other modules using DBI
120       !
121
122       A common usage is to load the module in a startup file called via the
123       PerlRequire directive. See eg/startup.pl and eg/startup2.pl for
124       examples.
125
126       There are two configurations which are server-specific and which can be
127       done upon server startup:
128
129        Apache::DBI->connect_on_init($data_source, $username, $auth, \%attr)
130
131       This can be used as a simple way to have apache servers establish
132       connections on process startup.
133
134        Apache::DBI->setPingTimeOut($data_source, $timeout)
135
136       This configures the usage of the ping method, to validate a connection.
137       Setting the timeout to 0 will always validate the database connection
138       using the ping method (default). Setting the timeout < 0 will de-
139       activate the validation of the database handle. This can be used for
140       drivers, which do not implement the ping-method. Setting the timeout >
141       0 will ping the database only if the last access was more than timeout
142       seconds before.
143
144       For the menu item 'DBI connections' you need to call
145       Apache::Status/Apache2::Status BEFORE Apache::DBI ! For an example of
146       the configuration order see startup.pl.
147
148       To enable debugging the variable $Apache::DBI::DEBUG must be set. This
149       can either be done in startup.pl or in the user script. Setting the
150       variable to 1, just reports about a new connect. Setting the variable
151       to 2 enables full debug output.
152

PREREQUISITES

154   MOD_PERL 2.0
155       Apache::DBI version 0.96 and later should work under mod_perl 2.0 RC5
156       and later with httpd 2.0.49 and later.
157
158       Apache::DBI versions less than 1.00 are NO longer supported.
159       Additionally, mod_perl versions less then 2.0.0 are NO longer
160       supported.
161
162   MOD_PERL 1.0 Note that this module needs mod_perl-1.08 or higher,
163       apache_1.3.0 or higher and that mod_perl needs to be configured with
164       the appropriate call-back hooks:
165         PERL_CHILD_INIT=1 PERL_STACKED_HANDLERS=1
166
167       Apache::DBI v0.94 was the last version before dual mod_perl 2.x support
168       was begun.  It still recommended that you use the latest version of
169       Apache::DBI because Apache::DBI versions less than 1.00 are NO longer
170       supported.
171

DO YOU NEED THIS MODULE?

173       Note that this module is intended for use in porting existing DBI code
174       to mod_perl, or writing code that can run under both mod_perl and CGI.
175       If you are using a database abstraction layer such as Class::DBI or
176       DBIx::Class that already manages persistent connections for you, there
177       is no need to use this module in addition.  (Another popular choice,
178       Rose::DB::Object, can cooperate with Apache::DBI or use your own custom
179       connection handling.)  If you are developing new code that is strictly
180       for use in mod_perl, you may choose to use "DBI->connect_cached()"
181       instead, but consider adding an automatic rollback after each request,
182       as described above.
183

SEE ALSO

185       Apache, mod_perl, DBI
186

AUTHORS

188       •   Philip M. Gollucci <pgollucci@p6m7g8.com> is currently packaging
189           new releases.
190
191           Ask Bjoern Hansen <ask@develooper.com> packaged a large number of
192           releases.
193
194       •   Edmund Mergl was the original author of Apache::DBI.  It is now
195           supported and maintained by the modperl mailinglist, see the
196           mod_perl documentation for instructions on how to subscribe.
197
198       •   mod_perl by Doug MacEachern.
199
200       •   DBI by Tim Bunce <dbi-users-subscribe@perl.org>
201
203       The Apache::DBI module is free software; you can redistribute it and/or
204       modify it under the same terms as Perl itself.
205
206
207
208perl v5.36.0                      2023-01-19                    Apache::DBI(3)
Impressum