1CGI::Application::PlugiUns:e:rDBCHo(n3t)ributed Perl DocCuGmIe:n:tAaptpiloincation::Plugin::DBH(3)
2
3
4

NAME

6       CGI::Application::Plugin::DBH - Easy DBI access from CGI::Application
7

VERSION

9       version 4.04
10

SYNOPSIS

12        use CGI::Application::Plugin::DBH (qw/dbh_config dbh/);
13
14        sub cgiapp_init  {
15           my $self = shift;
16
17           # use the same args as DBI->connect();
18           $self->dbh_config($data_source, $username, $auth, \%attr);
19
20           # 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
27        sub my_run_mode {
28           my $self = shift;
29
30           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
34           # OR ...
35
36           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

DESCRIPTION

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

METHODS

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
55        # OR ...
56
57        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
62       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
66   dbh_config()
67        sub cgiapp_init  {
68           my $self = shift;
69
70           # use the same args as DBI->connect();
71           $self->dbh_config($data_source, $username, $auth, \%attr);
72
73           # 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
79           # ...or use some existing handle you have
80           $self->dbh_config($DBH);
81           $self->dbh_config('my_handle', $DBH);   # this works too
82
83           # Use a callback to create your owh handle that is still lazy loaded
84           $self->dbh_config(sub { DBI->connect_cached(); });
85        }
86
87       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
91       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
96       Automatic configuration using CGI::App instance parameters
97
98       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
102       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
106       The code in the synopsis can be rewritten as
107
108         use CGI::Application::Plugin::DBH (qw/dbh/);
109           # no longer a need to import dbh_config
110
111         sub cgiapp_init  {
112            # you do not need to do anything here
113         }
114
115         sub my_run_mode {
116
117           # this part stays unchanged
118
119           ....
120
121         }
122
123       and in the instance script ( or instance configuration file, if you
124       have)
125
126          $app->param('::Plugin::DBH::dbh_config' =>
127               [ $data_source, $username, $auth, \%attr ] );
128
129       If you want to configure more than one handle, set up a hash with the
130       handle names as keys:
131
132           $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
137       Automatic configuration with DBI environment variables
138
139       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
147   dbh_default_name()
148        sub my_runmode {
149           my $self = shift;
150
151           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
155           $self->dbh_default_name($old_handle_name);    # Return to normal.
156        }
157
158       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
162       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

SEE ALSO

169       Ima::DBI is similar, but has much more complexity and features.
170
171       CGI::Application, DBI, CGI::Application::Plugin::ValidateRM
172

AUTHOR

174       Mark Stosberg <mark@stosberg.com>
175
177       This software is copyright (c) 2013 by Mark Stosberg.
178
179       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.
181
182
183
184perl v5.34.0                      2021-07-22  CGI::Application::Plugin::DBH(3)
Impressum