Coverage Summary

# File Coverage

blib/lib/Prancer/Database.pm
Criterion | Covered | Total | %
--- | --- | --- | ---
statement | 21 | 48 | 43.8
branch | 0 | 10 | 0.0
condition | 0 | 9 | 0.0
subroutine | 7 | 12 | 58.3
pod | 0 | 1 | 0.0
total | 28 | 80 | 35.0

line | stmt | bran | cond | sub | pod | time | code
--- | --- | --- | --- | --- | --- | --- | ---
1 |  |  |  |  |  |  | package Prancer::Database;
2 |  |  |  |  |  |  |
3 | 4 |  |  | 4 |  | 2463 | use strict;
| 4 |  |  |  |  | 4 |
| 4 |  |  |  |  | 124 |
4 | 4 |  |  | 4 |  | 8 | use warnings FATAL => 'all';
| 4 |  |  |  |  | 4 |
| 4 |  |  |  |  | 90 |
5 |  |  |  |  |  |  |
6 | 4 |  |  | 4 |  | 18 | use Carp;
| 4 |  |  |  |  | 4 |
| 4 |  |  |  |  | 152 |
7 | 4 |  |  | 4 |  | 11 | use Prancer;
| 4 |  |  |  |  | 3 |
| 4 |  |  |  |  | 94 |
8 | 4 |  |  | 4 |  | 14 | use Module::Load ();
| 4 |  |  |  |  | 4 |
| 4 |  |  |  |  | 49 |
9 | 4 |  |  | 4 |  | 13 | use Try::Tiny;
| 4 |  |  |  |  | 3 |
| 4 |  |  |  |  | 131 |
10 | 4 |  |  | 4 |  | 9 | use Prancer qw(logger);
| 4 |  |  |  |  | 10 |
| 4 |  |  |  |  | 1300 |
11 |  |  |  |  |  |  |
12 |  |  |  |  |  |  | sub load {
13 | 0 |  |  | 0 | 0 |  | my ($class, $config) = @_;
14 |  |  |  |  |  |  |
15 | 0 | 0 | 0 |  |  |  | unless (ref($config) && ref($config) eq "HASH") {
16 | 0 |  |  |  |  |  | logger->warn("could not initialize database connection: no database configuration");
17 | 0 |  |  |  |  |  | return;
18 |  |  |  |  |  |  | }
19 |  |  |  |  |  |  |
20 |  |  |  |  |  |  | # we can load multiple databases
21 | 0 |  |  |  |  |  | my $handles = {};
22 |  |  |  |  |  |  |
23 | 0 |  |  |  |  |  | foreach my $key (keys %{$config}) {
| 0 |  |  |  |  |  |
24 | 0 |  |  |  |  |  | my $subconfig = $config->{$key};
25 |  |  |  |  |  |  |
26 | 0 | 0 | 0 |  |  |  | unless (ref($subconfig) && ref($subconfig) eq "HASH" && $subconfig->{'driver'}) {
|  |  | 0 |  |  |  |
27 | 0 |  |  |  |  |  | logger->warn("could not initialize database connection '${key}': no database driver configuration");
28 | 0 |  |  |  |  |  | return;
29 |  |  |  |  |  |  | }
30 |  |  |  |  |  |  |
31 | 0 |  |  |  |  |  | my $module = $subconfig->{'driver'};
32 |  |  |  |  |  |  |
33 |  |  |  |  |  |  | try {
34 | 0 |  |  | 0 |  |  | Module::Load::load($module);
35 |  |  |  |  |  |  | } catch {
36 | 0 | 0 |  | 0 |  |  | my $error = (defined($_) ? $_ : "unknown");
37 | 0 |  |  |  |  |  | logger->fatal("could not initialize database connection '${key}': not able to load ${module}: ${error}");
38 | 0 |  |  |  |  |  | croak;
39 | 0 |  |  |  |  |  | };
40 |  |  |  |  |  |  |
41 | 0 | 0 |  |  |  |  | unless ($module->can("handle")) {
42 | 0 |  |  |  |  |  | logger->fatal("could not initialize database connection '${key}': ${module} doesn't implement 'handle'");
43 | 0 |  |  |  |  |  | croak;
44 |  |  |  |  |  |  | }
45 |  |  |  |  |  |  |
46 |  |  |  |  |  |  | # now initialize that module
47 |  |  |  |  |  |  | try {
48 | 0 |  |  | 0 |  |  | $handles->{$key} = $module->new($subconfig->{'options'}, $key);
49 | 0 |  |  |  |  |  | logger->info("initialized database connection '${key}' with ${module}");
50 |  |  |  |  |  |  | } catch {
51 | 0 | 0 |  | 0 |  |  | my $error = (defined($_) ? $_ : "unknown");
52 | 0 |  |  |  |  |  | logger->fatal("could not initialize database connection '${key}': ${error}");
53 | 0 |  |  |  |  |  | croak;
54 | 0 |  |  |  |  |  | };
55 |  |  |  |  |  |  | }
56 |  |  |  |  |  |  |
57 | 0 |  |  |  |  |  | return $handles;
58 |  |  |  |  |  |  | }
59 |  |  |  |  |  |  |
60 |  |  |  |  |  |  | 1;
61 |  |  |  |  |  |  |
62 |  |  |  |  |  |  | =head1 NAME
63 |  |  |  |  |  |  |
64 |  |  |  |  |  |  | Prancer::Database
65 |  |  |  |  |  |  |
66 |  |  |  |  |  |  | =head1 SYNOPSIS
67 |  |  |  |  |  |  |
68 |  |  |  |  |  |  | This module enables connections to a database. NOTE: One should not use this
69 |  |  |  |  |  |  | module to connect to the database. Instead, one should use L<Prancer>.
70 |  |  |  |  |  |  |
71 |  |  |  |  |  |  | It's important to remember that when running your application in a single-
72 |  |  |  |  |  |  | threaded, single-process application server like, say, L<Twiggy>, all users of
73 |  |  |  |  |  |  | your application will use the same database connection. If you are using
74 |  |  |  |  |  |  | callbacks then this becomes very important. You will want to take care to avoid
75 |  |  |  |  |  |  | crossing transactions or to avoid expecting a database connection or
76 |  |  |  |  |  |  | transaction to be in the same state it was before a callback.
77 |  |  |  |  |  |  |
78 |  |  |  |  |  |  | To use a database connector, add something like this to your configuration
79 |  |  |  |  |  |  | file:
80 |  |  |  |  |  |  |
81 |  |  |  |  |  |  | database:
82 |  |  |  |  |  |  | connection-name:
83 |  |  |  |  |  |  | driver: Prancer::Database::Driver::DriverName
84 |  |  |  |  |  |  | options:
85 |  |  |  |  |  |  | username: test
86 |  |  |  |  |  |  | password: test
87 |  |  |  |  |  |  | database: test
88 |  |  |  |  |  |  | hostname: localhost
89 |  |  |  |  |  |  | port: 5432
90 |  |  |  |  |  |  | autocommit: true
91 |  |  |  |  |  |  | charset: utf8
92 |  |  |  |  |  |  | connection_check_threshold: 10
93 |  |  |  |  |  |  |
94 |  |  |  |  |  |  | The "connection-name" can be anything you want it to be. This will be used when
95 |  |  |  |  |  |  | requesting a connection from Prancer to determine which connection to return.
96 |  |  |  |  |  |  | If only one connection is configured it may be prudent to call it "default" as
97 |  |  |  |  |  |  | that is the name that Prancer will look for if no connection name is given.
98 |  |  |  |  |  |  | For example:
99 |  |  |  |  |  |  |
100 |  |  |  |  |  |  | my $dbh = database; # returns whatever connection is called "default"
101 |  |  |  |  |  |  | my $dbh = database('foo'); # returns the connection called "foo"
102 |  |  |  |  |  |  |
103 |  |  |  |  |  |  | =head1 OPTIONS
104 |  |  |  |  |  |  |
105 |  |  |  |  |  |  | =over 4
106 |  |  |  |  |  |  |
107 |  |  |  |  |  |  | =item database
108 |  |  |  |  |  |  |
109 |  |  |  |  |  |  | B<REQUIRED> The name of the database to connect to.
110 |  |  |  |  |  |  |
111 |  |  |  |  |  |  | =item username
112 |  |  |  |  |  |  |
113 |  |  |  |  |  |  | The username to use when connecting. If this option is not set the default is
114 |  |  |  |  |  |  | the user running the application server.
115 |  |  |  |  |  |  |
116 |  |  |  |  |  |  | =item password
117 |  |  |  |  |  |  |
118 |  |  |  |  |  |  | The password to use when connectin. If this option is not set the default is to
119 |  |  |  |  |  |  | connect with no password.
120 |  |  |  |  |  |  |
121 |  |  |  |  |  |  | =item hostname
122 |  |  |  |  |  |  |
123 |  |  |  |  |  |  | The host name of the database server. If this option is not set the default is
124 |  |  |  |  |  |  | to connect to localhost.
125 |  |  |  |  |  |  |
126 |  |  |  |  |  |  | =item port
127 |  |  |  |  |  |  |
128 |  |  |  |  |  |  | The port number on which the database server is listening. If this option is
129 |  |  |  |  |  |  | not set the default is to connect on the database's default port.
130 |  |  |  |  |  |  |
131 |  |  |  |  |  |  | =item autocommit
132 |  |  |  |  |  |  |
133 |  |  |  |  |  |  | If set to a true value -- like 1, yes, or true -- this will enable autocommit.
134 |  |  |  |  |  |  | If set to a false value -- like 0, no, or false -- this will disable
135 |  |  |  |  |  |  | autocommit. By default, autocommit is enabled.
136 |  |  |  |  |  |  |
137 |  |  |  |  |  |  | =item charset
138 |  |  |  |  |  |  |
139 |  |  |  |  |  |  | The character set to connect to the database with. If this is set to "utf8"
140 |  |  |  |  |  |  | then the database connection will attempt to make UTF8 data Just Work if
141 |  |  |  |  |  |  | available.
142 |  |  |  |  |  |  |
143 |  |  |  |  |  |  | =item connection_check_threshold
144 |  |  |  |  |  |  |
145 |  |  |  |  |  |  | This sets the number of seconds that must elapse between calls to get a
146 |  |  |  |  |  |  | database handle before performing a check to ensure that a database connection
147 |  |  |  |  |  |  | still exists and will reconnect if one does not. This handles cases where the
148 |  |  |  |  |  |  | database handle hasn't been used in a while and the underlying connection has
149 |  |  |  |  |  |  | gone away. If this is not set it will default to 30 seconds.
150 |  |  |  |  |  |  |
151 |  |  |  |  |  |  | =back
152 |  |  |  |  |  |  |
153 |  |  |  |  |  |  | =head1 SEE ALSO
154 |  |  |  |  |  |  |
155 |  |  |  |  |  |  | =over 4
156 |  |  |  |  |  |  |
157 |  |  |  |  |  |  | =item L<Prancer::Database::Driver::Pg>
158 |  |  |  |  |  |  |
159 |  |  |  |  |  |  | =back
160 |  |  |  |  |  |  |
161 |  |  |  |  |  |  | =cut
162 |  |  |  |  |  |  |