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 version 4.04
10
12 use CGI::Application::Plugin::DBH (qw/dbh_config dbh/);
13 sub cgiapp_init {
15 my $self = shift;
16 # use the same args as DBI->connect();
18 $self->dbh_config($data_source, $username, $auth, \%attr);
19 # or to use more than one dbh
21 $self->dbh_config('my_handle',
22 [ $data_source, $user, $auth, \%attr ]);
23 $self->dbh_config('my_other_handle',
24 [ $data_source, $user, $auth, \%attr ]);
25 }
26 sub my_run_mode {
28 my $self = shift;
29 my $date = $self->dbh->selectrow_array("SELECT CURRENT_DATE");
31 # again with a named handle
32 $date = $self->dbh('my_handle')->selectrow_array("SELECT CURRENT_DATE");
33 # OR ...
35 my $dbh = $self->dbh;
37 # again with a named handle
38 $dbh = $self->dbh('my_other_handle');
39 my $date = $dbh->selectrow_array("SELECT CURRENT_DATE");
40 }
41
43 CGI::Application::Plugin::DBH adds easy access to a DBI database handle
44 to your CGI::Application modules. Lazy loading is used to prevent a
45 database connection from being made if the "dbh" method is not called
46 during the request. In other words, the database connection is not
47 created until it is actually needed.
48
50 dbh()
51 my $date = $self->dbh->selectrow_array("SELECT CURRENT_DATE");
52 # again with a named handle
53 $date = $self->dbh('my_handle')->selectrow_array("SELECT CURRENT_DATE");
54 # OR ...
56 my $dbh = $self->dbh;
58 # again with a named handle
59 $dbh = $self->dbh('my_other_handle');
60 my $date = $dbh->selectrow_array("SELECT CURRENT_DATE");
61 This method will return the current DBI database handle. The database
63 handle is created on the first call to this method, and any subsequent
64 calls will return the same handle.
65 dbh_config()
67 sub cgiapp_init {
68 my $self = shift;
69 # use the same args as DBI->connect();
71 $self->dbh_config($data_source, $username, $auth, \%attr);
72 # or to use more than one dbh
74 $self->dbh_config('my_handle',
75 [ $data_source, $user, $auth, \%attr ]);
76 $self->dbh_config('my_other_handle',
77 [ $data_source, $user, $auth, \%attr ]);
78 # ...or use some existing handle you have
80 $self->dbh_config($DBH);
81 $self->dbh_config('my_handle', $DBH); # this works too
82 # Use a callback to create your owh handle that is still lazy loaded
84 $self->dbh_config(sub { DBI->connect_cached(); });
85 }
86 Used to provide your DBI connection parameters. You can either pass in
88 an existing DBI database handle, or provide the usual parameters used
89 for DBI->connect().
90 The recommended place to call "dbh_config" is in the "cgiapp_init"
92 stage of CGI::Application. If this method is called after the database
93 handle has already been accessed, then it will die with an error
94 message.
95 Automatic configuration using CGI::App instance parameters
97 An alternative to explicitly calling "dbh_config" in your application
99 is to rely on the presence of specific instance parameters that allow
100 the plugin to configure itself.
101 If you set the CGI::App parameter "::Plugin::DBH::dbh_config" to an
103 array reference the contents of that array will be used as parameters
104 to "dbh_config" (if it has not been explicitly called before).
105 The code in the synopsis can be rewritten as
107 use CGI::Application::Plugin::DBH (qw/dbh/);
109 # no longer a need to import dbh_config
110 sub cgiapp_init {
112 # you do not need to do anything here
113 }
114 sub my_run_mode {
116 # this part stays unchanged
118 ....
120 }
122 and in the instance script ( or instance configuration file, if you
124 have)
125 $app->param('::Plugin::DBH::dbh_config' =>
127 [ $data_source, $username, $auth, \%attr ] );
128 If you want to configure more than one handle, set up a hash with the
130 handle names as keys:
131 $app->param('::Plugin::DBH::dbh_config' =>
133 { my_handle => [ $data_source, $username, $auth, \%attr ] ,
134 my_other_handle => [ $data_source, $username, $auth, \%attr ]
135 } );
136 Automatic configuration with DBI environment variables
138 If you do not set any parameters, and do not call "dbh_config", this
140 plugin checks to see if you set the DBI environment variable "DBI_DSN".
141 If present, this DSN will be used for the default handle. Note that the
142 DBI documentation does not encourage using this method (especially in
143 the context of web applications), that you will most likely have to
144 also set "DBI_USER" and "DBI_PASS", and that this can only be used for
145 the default handle.
146 dbh_default_name()
148 sub my_runmode {
149 my $self = shift;
150 my $old_handle_name = $self->dbh_default_name('my_handle');
152 $self->some_legacy_code(); # some_legacy_code() will get "my_handle"
153 # when it calls $self->dbh() without parameters
154 $self->dbh_default_name($old_handle_name); # Return to normal.
156 }
157 Can be used to alter the name of the handle that is returned by dbh()
159 when called with no parameters. It can even be used to alter the name
160 used for the unnamed handle if called before dbh_config().
161 Using this method is completely optional. If you don't have a use for
163 it don't use it. Internally the handle name
164 "__cgi_application_plugin_dbh" is used to keep track of the unnamed
165 handle unless it is changed by dbh_default_name() before a call to
166 dbh_config() without a name parameter.
167
169 Ima::DBI is similar, but has much more complexity and features.
170 CGI::Application, DBI, CGI::Application::Plugin::ValidateRM
172
174 Mark Stosberg <mark@stosberg.com>
175
177 This software is copyright (c) 2013 by Mark Stosberg.
178 This is free software; you can redistribute it and/or modify it under
180 the same terms as the Perl 5 programming language system itself.
181perl v5.34.0 2022-01-20 CGI::Application::Plugin::DBH(3)