Debian Codegraph @

README

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