README.pod
1=head1 NAME
2
3Mojolicious::Plugin::Database - "proper" handling of DBI based connections in Mojolicious
4
5=head1 SYNOPSIS
6
7Provides "sane" handling of DBI connections so problems with pre-forking (Hypnotoad, etc.) will not occur.
8
9 use Mojolicious::Plugin::Database;
10
11 sub startup {
12 my $self = shift;
13
14 $self->plugin('database', {
15 dsn => 'dbi:Pg:dbname=foo',
16 username => 'myusername',
17 password => 'mypassword',
18 options => { 'pg_enable_utf8' => 1, AutoCommit => 0 },
19 helper => 'db',
20 });
21
22 # or if you require multiple databases at the same time
23 $self->plugin('database', {
24 databases => {
25 'db1' => {
26 dsn => 'dbi:Pg:dbname=foo',
27 username => 'myusername',
28 password => 'mypassword',
29 },
30 'db2' => {
31 dsn => 'dbi:MySQL:dbname=bar',
32 username => 'othername',
33 password => 'otherpassword',
34 },
35 },
36 });
37 }
38
39=head1 CONFIGURATION
40
41=head2 CONNECTING TO A SINGLE DATABASE
42
43When connecting to a single database, the following configuration options are recognised:
44
45=over 4
46
47=item 'dsn' should contain the DSN string required by DBI
48
49=item 'username' the username that should be used to authenticate
50
51=item 'password' the password that should be used to authenticate
52
53=item 'options' options to pass to the DBD driver
54
55=item 'helper' the name of the helper to associate with this database (default: db)
56
57=back
58
59The only required option is 'dsn', every other option is optional.
60
61=head2 CONNECTING TO MULTIPLE DATABASES
62
63When you have the need to connect to multiple databases (or different RDBMS types), the following options are recognised:
64
65=over 4
66
67=item 'databases' A hash reference whose key is the helper name, and the value is another hash reference containing connection options.
68
69=back
70
71=head1 METHODS/HELPERS
72
73A helper is created with a name you specified (or 'db' by default) that can be used to get the active DBI connection. When using multiple databases, you also get multiple helpers.
74
75=head1 AUTHOR
76
77Ben van Staveren, C<< <madcat at cpan.org> >>
78
79=head1 BUGS/CONTRIBUTING
80
81Please report any bugs or feature requests to through the web interface at L<https://github.com/benvanstaveren/mojolicious-plugin-database/issues>.
82If you want to contribute changes or otherwise involve yourself in development, feel free to fork the Git repository from L<https://github.com/benvanstaveren/mojolicious-plugin-database/>.
83
84
85=head1 SUPPORT
86
87You can find documentation for this module with the perldoc command.
88
89 perldoc Mojolicious::Plugin::Database
90
91
92You can also look for information at:
93
94=over 4
95
96=item * AnnoCPAN: Annotated CPAN documentation
97
98L<http://annocpan.org/dist/Mojolicious-Plugin-Database>
99
100=item * CPAN Ratings
101
102L<http://cpanratings.perl.org/d/Mojolicious-Plugin-Database>
103
104=item * Search CPAN
105
106L<http://search.cpan.org/dist/Mojolicious-Plugin-Database/>
107
108=back
109
110=head1 ACKNOWLEDGEMENTS
111
112Based on a small example by sri and his request if someone could please write a plugin for this stuff.
113
114alabamapaul (github) for fixing the tests to work on Windows.
115
116Babatope Aloba for pointing out it'd be really useful to be able to connect to multiple databases at once.
117
118=head1 LICENSE AND COPYRIGHT
119
120Copyright 2011-2015 Ben van Staveren.
121
122This program is free software; you can redistribute it and/or modify it
123under the terms of either: the GNU General Public License as published
124by the Free Software Foundation; or the Artistic License.
125
126See http://dev.perl.org/licenses/ for more information.
127
128