1Apache::DBI(3) User Contributed Perl Documentation Apache::DBI(3)
2
6 Apache::DBI - Initiate a persistent database connection
7
9 # Configuration in httpd.conf or startup.pl:
10 PerlModule Apache::DBI # this comes before all other modules using DBI
12 Do NOT change anything in your scripts. The usage of this module is
14 absolutely transparent !
15
17 This module initiates a persistent database connection.
18 The database access uses Perl's DBI. For supported DBI drivers see:
20 http://dbi.perl.org/
22 When loading the DBI module (do not confuse this with the Apache::DBI
24 module) it looks if the environment variable GATEWAY_INTERFACE starts
25 with 'CGI-Perl' and if the module Apache::DBI has been loaded. In this
26 case every connect request will be forwarded to the Apache::DBI module.
27 This looks if a database handle from a previous connect request is
28 already stored and if this handle is still valid using the ping method.
29 If these two conditions are fulfilled it just returns the database han‐
30 dle. The parameters defining the connection have to be exactly the
31 same, including the connect attributes! If there is no appropriate
32 database handle or if the ping method fails, a new connection is estab‐
33 lished and the handle is stored for later re-use. There is no need to
34 remove the disconnect statements from your code. They won't do anything
35 because the Apache::DBI module overloads the disconnect method.
36 The Apache::DBI module still has a limitation: it keeps database con‐
38 nections persistent on a per process basis. The problem is, if a user
39 accesses several times a database, the http requests will be handled
40 very likely by different servers. Every server needs to do its own con‐
41 nect. It would be nice, if all servers could share the database han‐
42 dles. Currently this is not possible, because of the distinct name-
43 space of every process. Also it is not possible to create a database
44 handle upon startup of the httpd and then inheriting this handle to
45 every subsequent server. This will cause clashes when the handle is
46 used by two processes at the same time.
47 With this limitation in mind, there are scenarios, where the usage of
49 Apache::DBI is depreciated. Think about a heavy loaded Web-site where
50 every user connects to the database with a unique userid. Every server
51 would create many database handles each of which spawning a new backend
52 process. In a short time this would kill the web server.
53 Another problem are timeouts: some databases disconnect the client
55 after a certain time of inactivity. The module tries to validate the
56 database handle using the ping-method of the DBI-module. This method
57 returns true as default. If the database handle is not valid and the
58 driver has no implementation for the ping method, you will get an error
59 when accessing the database. As a work-around you can try to replace
60 the ping method by any database command, which is cheap and safe or you
61 can deactivate the usage of the ping method (see CONFIGURATION below).
62 Here is generalized ping method, which can be added to the driver mod‐
64 ule:
65 package DBD::xxx::db; # ====== DATABASE ======
67 use strict;
68 sub ping {
70 my ($dbh) = @_;
71 my $ret = 0;
72 eval {
73 local $SIG{__DIE__} = sub { return (0); };
74 local $SIG{__WARN__} = sub { return (0); };
75 # adapt the select statement to your database:
76 $ret = $dbh->do('select 1');
77 };
78 return ($@) ? 0 : $ret;
79 }
80 Transactions: a standard DBI script will automatically perform a roll‐
82 back whenever the script exits. In the case of persistent database con‐
83 nections, the database handle will not be destroyed and hence no auto‐
84 matic rollback occurs. At a first glance it seems even to be possible,
85 to handle a transaction over multiple requests. But this should be
86 avoided, because different requests are handled by different servers
87 and a server does not know the state of a specific transaction which
88 has been started by another server. In general it is good practice to
89 perform an explicit commit or rollback at the end of every script. In
90 order to avoid inconsistencies in the database in case AutoCommit is
91 off and the script finishes without an explicit rollback, the
92 Apache::DBI module uses a PerlCleanupHandler to issue a rollback at the
93 end of every request. Note, that this CleanupHandler will only be used,
94 if the initial data_source sets AutoCommit = 0 or AutoCommit is turned
95 off, after the connect has been done (ie begin_work). However, because
96 a connection may have set other parameters, the handle is reset to its
97 initial connection state before it is returned for a second time.
98 This module plugs in a menu item for Apache::Status or Apache2::Status.
100 The menu lists the current database connections. It should be consid‐
101 ered incomplete because of the limitations explained above. It shows
102 the current database connections for one specific server, the one which
103 happens to serve the current request. Other servers might have other
104 database connections. The Apache::Status/Apache2::Status module has to
105 be loaded before the Apache::DBI module !
106
108 The module should be loaded upon startup of the Apache daemon. Add the
109 following line to your httpd.conf or startup.pl:
110 PerlModule Apache::DBI
112 It is important, to load this module before any other modules using DBI
114 !
115 A common usage is to load the module in a startup file via the PerlRe‐
117 quire directive. See eg/startup.pl and eg/startup2.pl for examples.
118 There are two configurations which are server-specific and which can be
120 done upon server startup:
121 Apache::DBI->connect_on_init($data_source, $username, $auth, \%attr)
123 This can be used as a simple way to have apache servers establish con‐
125 nections on process startup.
126 Apache::DBI->setPingTimeOut($data_source, $timeout)
128 This configures the usage of the ping method, to validate a connection.
130 Setting the timeout to 0 will always validate the database connection
131 using the ping method (default). Setting the timeout < 0 will de-acti‐
132 vate the validation of the database handle. This can be used for driv‐
133 ers, which do not implement the ping-method. Setting the timeout > 0
134 will ping the database only if the last access was more than timeout
135 seconds before.
136 For the menu item 'DBI connections' you need to call Apache::Sta‐
138 tus/Apache2::Status BEFORE Apache::DBI ! For an example of the configu‐
139 ration order see startup.pl.
140 To enable debugging the variable $Apache::DBI::DEBUG must be set. This
142 can either be done in startup.pl or in the user script. Setting the
143 variable to 1, just reports about a new connect. Setting the variable
144 to 2 enables full debug output.
145
147 MOD_PERL 2.0
148 Apache::DBI version 0.96 and should work under mod_perl 2.0 RC5 and
150 later with httpd 2.0.49 and later.
151 Apache::DBI versions less than 1.00 are NO longer supported. Addition‐
153 ally, mod_perl versions less then 2.0.0 are NO longer supported.
154 MOD_PERL 1.0 Note that this module needs mod_perl-1.08 or higher,
156 apache_1.3.0 or higher and that mod_perl needs to be configured with
157 the appropriate call-back hooks:
158 Apache::DBI v0.94 was the last version before dual mod_perl 2.x support
160 was begun. It still recommened that you use the latest version of
161 Apache::DBI because Apache::DBI versions less than 1.00 are NO longer
162 supported.
163 PERL_CHILD_INIT=1 PERL_STACKED_HANDLERS=1.
165
167 Apache, mod_perl, DBI
168
170* Philip M. Gollucci <pgollucci@p6m7g8.com> is currently packaging new
171releases.
172Ask Bjoern Hansen <ask@develooper.com> packaged a large number of releases.
173* Edmund Mergl was the original author of Apache::DBI. It is now supported
175and maintained by the modperl mailinglist, see the mod_perl documentation for
176instructions on how to subscribe.
177* mod_perl by Doug MacEachern.
178* DBI by Tim Bunce <dbi-users-subscribe@perl.org>
179
181 The Apache::DBI module is free software; you can redistribute it and/or
182 modify it under the same terms as Perl itself.
183perl v5.8.8 2007-03-23 Apache::DBI(3)