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