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