1CGI::Application::PlugiUns:e:rDBCHo(n3t)ributed Perl DocCuGmIe:n:tAaptpiloincation::Plugin::DBH(3)
2
6 CGI::Application::Plugin::DBH - Easy DBI access from CGI::Application
7
9 use CGI::Application::Plugin::DBH (qw/dbh_config dbh/);
10 sub cgiapp_init {
12 my $self = shift;
13 # use the same args as DBI->connect();
15 $self->dbh_config($data_source, $username, $auth, \%attr);
16 # or to use more than one dbh
18 $self->dbh_config('my_handle',
19 [ $data_source, $user, $auth, \%attr ]);
20 $self->dbh_config('my_other_handle',
21 [ $data_source, $user, $auth, \%attr ]);
22 }
23 sub my_run_mode {
25 my $self = shift;
26 my $date = $self->dbh->selectrow_array("SELECT CURRENT_DATE");
28 # again with a named handle
29 $date = $self->dbh('my_handle')->selectrow_array("SELECT CURRENT_DATE");
30 # OR ...
32 my $dbh = $self->dbh;
34 # again with a named handle
35 $dbh = $self->dbh('my_other_handle');
36 my $date = $dbh->selectrow_array("SELECT CURRENT_DATE");
37 }
38
40 CGI::Application::Plugin::DBH adds easy access to a DBI database handle
41 to your CGI::Application modules. Lazy loading is used to prevent a
42 database connection from being made if the "dbh" method is not called
43 during the request. In other words, the database connection is not
44 created until it is actually needed.
45
47 dbh()
48 my $date = $self->dbh->selectrow_array("SELECT CURRENT_DATE");
49 # again with a named handle
50 $date = $self->dbh('my_handle')->selectrow_array("SELECT CURRENT_DATE");
51 # OR ...
53 my $dbh = $self->dbh;
55 # again with a named handle
56 $dbh = $self->dbh('my_other_handle');
57 my $date = $dbh->selectrow_array("SELECT CURRENT_DATE");
58 This method will return the current DBI database handle. The database
60 handle is created on the first call to this method, and any subsequent
61 calls will return the same handle.
62 dbh_config()
64 sub cgiapp_init {
65 my $self = shift;
66 # use the same args as DBI->connect();
68 $self->dbh_config($data_source, $username, $auth, \%attr);
69 # or to use more than one dbh
71 $self->dbh_config('my_handle',
72 [ $data_source, $user, $auth, \%attr ]);
73 $self->dbh_config('my_other_handle',
74 [ $data_source, $user, $auth, \%attr ]);
75 # ...or use some existing handle you have
77 $self->dbh_config($DBH);
78 $self->dbh_config('my_handle', $DBH); # this works too
79 # Use a callback to create your owh handle that is still lazy loaded
81 $self->dbh_config(sub { DBI->connect_cached(); });
82 }
83 Used to provide your DBI connection parameters. You can either pass in
85 an existing DBI database handle, or provide the usual parameters used
86 for DBI->connect().
87 The recommended place to call "dbh_config" is in the "cgiapp_init"
89 stage of CGI::Application. If this method is called after the database
90 handle has already been accessed, then it will die with an error
91 message.
92 Automatic configuration using CGI::App instance parameters
94 An alternative to explicitly calling "dbh_config" in your application
96 is to rely on the presence of specific instance parameters that allow
97 the plugin to configure itself.
98 If you set the CGI::App parameter "::Plugin::DBH::dbh_config" to an
100 array reference the contents of that array will be used as parameters
101 to "dbh_config" (if it has not been explicitly called before).
102 The code in the synopsis can be rewritten as
104 use CGI::Application::Plugin::DBH (qw/dbh/);
106 # no longer a need to import dbh_config
107 sub cgiapp_init {
109 # you do not need to do anything here
110 }
111 sub my_run_mode {
113 # this part stays unchanged
115 ....
117 }
119 and in the instance script ( or instance configuration file, if you
121 have)
122 $app->param('::Plugin::DBH::dbh_config' =>
124 [ $data_source, $username, $auth, \%attr ] );
125 If you want to configure more than one handle, set up a hash with the
127 handle names as keys:
128 $app->param('::Plugin::DBH::dbh_config' =>
130 { my_handle => [ $data_source, $username, $auth, \%attr ] ,
131 my_other_handle => [ $data_source, $username, $auth, \%attr ]
132 } );
133 Automatic configuration with DBI environment variables
135 If you do not set any parameters, and do not call "dbh_config", this
137 plugin checks to see if you set the DBI environment variable "DBI_DSN".
138 If present, this DSN will be used for the default handle. Note that the
139 DBI documentation does not encourage using this method (especially in
140 the context of web applications), that you will most likely have to
141 also set "DBI_USER" and "DBI_PASS", and that this can only be used for
142 the default handle.
143 dbh_default_name()
145 sub my_runmode {
146 my $self = shift;
147 my $old_handle_name = $self->dbh_default_name('my_handle');
149 $self->some_legacy_code(); # some_legacy_code() will get "my_handle"
150 # when it calls $self->dbh() without parameters
151 $self->dbh_default_name($old_handle_name); # Return to normal.
153 }
154 Can be used to alter the name of the handle that is returned by dbh()
156 when called with no parameters. It can even be used to alter the name
157 used for the unamed handle if called before dbh_config().
158 Using this method is completely optional. If you don't have a use for
160 it don't use it. Internally the handle name
161 "__cgi_application_plugin_dbh" is used to keep track of the unnamed
162 handle unless it is changed by dbh_default_name() before a call to
163 dbh_config() without a name parameter.
164
166 Ima::DBI is similar, but has much more complexity and features.
167 CGI::Application, DBI, CGI::Application::Plugin::ValidateRM, perl(1)
169
171 Mark Stosberg <mark@summersault.com>
172 Multi Handle Support added by: Tony Fraser <tony@sybaspace.com>
174 Autoconfig Support added by: Thilo Planz <thilo@cpan.org>
176
178 Copyright (C) 2004 Mark Stosberg <mark@summersault.com>
179 This library is free software. You can modify and or distribute it
181 under the same terms as Perl itself.
182perl v5.12.0 2010-04-30 CGI::Application::Plugin::DBH(3)