File Coverage

blib/lib/Dancer/Plugin/DBIC.pm
Criterion Covered Total %
statement 23 23 100.0
branch n/a
condition n/a
subroutine 8 8 100.0
pod n/a
total 31 31 100.0


line stmt bran cond sub pod time code
1             package Dancer::Plugin::DBIC;
2              
3             our $VERSION = '0.2102'; # VERSION
4              
5 6     6   782082 use strict;
  6         12  
  6         160  
6 6     6   21 use warnings;
  6         6  
  6         118  
7 6     6   2628 use utf8;
  6         78  
  6         21  
8 6     6   2286 use Dancer::Plugin;
  6         102742  
  6         350  
9 6     6   1991 use Module::Load;
  6         3803  
  6         25  
10 6     6   2548 use DBICx::Sugar;
  6         45970  
  6         764  
11              
12             sub _schema {
13 18     18   1678336 my ($self, $name) = plugin_args(@_);
14 18         90 DBICx::Sugar::config( plugin_setting );
15 18         464 return DBICx::Sugar::schema($name);
16             };
17              
18             sub _rset {
19 14     14   1112758 my ($self, $rset_name) = plugin_args(@_);
20 14         72 return DBICx::Sugar::schema->resultset($rset_name);
21             }
22              
23             register schema => \&_schema;
24             register resultset => \&_rset;
25             register rset => \&_rset;
26             register_plugin;
27              
28             # ABSTRACT: DBIx::Class interface for Dancer applications
29              
30              
31             1;
32              
33             __END__
34              
35             =pod
36              
37             =encoding UTF-8
38              
39             =head1 NAME
40              
41             Dancer::Plugin::DBIC - DBIx::Class interface for Dancer applications
42              
43             =head1 VERSION
44              
45             version 0.2102
46              
47             =head1 SYNOPSIS
48              
49             use Dancer;
50             use Dancer::Plugin::DBIC qw(schema resultset rset);
51              
52             get '/users/:user_id' => sub {
53             my $user = schema('default')->resultset('User')->find(param 'user_id');
54              
55             # If you are accessing the 'default' schema, then all the following
56             # are equivalent to the above:
57             $user = schema->resultset('User')->find(param 'user_id');
58             $user = resultset('User')->find(param 'user_id');
59             $user = rset('User')->find(param 'user_id');
60              
61             template user_profile => {
62             user => $user
63             };
64             };
65              
66             dance;
67              
68             =head1 DESCRIPTION
69              
70             This plugin makes it very easy to create L<Dancer> applications that interface
71             with databases.
72             It automatically exports the keyword C<schema> which returns a
73             L<DBIx::Class::Schema> object.
74             You just need to configure your database connection information.
75             For performance, schema objects are cached in memory
76             and are lazy loaded the first time they are accessed.
77              
78             This plugin is now just a thin wrapper around L<DBICx::Sugar>.
79              
80             =head1 CONFIGURATION
81              
82             Configuration can be done in your L<Dancer> config file.
83              
84             =head2 simple example
85              
86             Here is a simple example. It defines one database named C<default>:
87              
88             plugins:
89             DBIC:
90             default:
91             dsn: dbi:SQLite:dbname=myapp.db
92             schema_class: MyApp::Schema
93              
94             =head2 multiple schemas
95              
96             In this example, there are 2 databases configured named C<default> and C<foo>:
97              
98             plugins:
99             DBIC:
100             default:
101             dsn: dbi:SQLite:dbname=myapp.db
102             schema_class: MyApp::Schema
103             foo:
104             dsn: dbi:Pg:dbname=foo
105             schema_class: Foo::Schema
106             user: bob
107             password: secret
108             options:
109             RaiseError: 1
110             PrintError: 1
111              
112             Each database configured must at least have a dsn option.
113             The dsn option should be the L<DBI> driver connection string.
114             All other options are optional.
115              
116             If you only have one schema configured, or one of them is named
117             C<default>, you can call C<schema> without an argument to get the only
118             or C<default> schema, respectively.
119              
120             If a schema_class option is not provided, then L<DBIx::Class::Schema::Loader>
121             will be used to dynamically load the schema by introspecting the database
122             corresponding to the dsn value.
123             You need L<DBIx::Class::Schema::Loader> installed for this to work.
124              
125             WARNING: Dynamic loading is not recommended for production environments.
126             It is almost always better to provide a schema_class option.
127              
128             The schema_class option should be the name of your L<DBIx::Class::Schema> class.
129             See L</"SCHEMA GENERATION">
130             Optionally, a database configuration may have user, password, and options
131             parameters as described in the documentation for C<connect()> in L<DBI>.
132              
133             =head2 connect_info
134              
135             Alternatively, you may also declare your connection information inside an
136             array named C<connect_info>:
137              
138             plugins:
139             DBIC:
140             default:
141             schema_class: MyApp::Schema
142             connect_info:
143             - dbi:Pg:dbname=foo
144             - bob
145             - secret
146             -
147             RaiseError: 1
148             PrintError: 1
149              
150             =head2 replicated
151              
152             You can also add database read slaves to your configuration with the
153             C<replicated> config option.
154             This will automatically make your read queries go to a slave and your write
155             queries go to the master.
156             Keep in mind that this will require additional dependencies:
157             L<DBIx::Class::Optional::Dependencies#Storage::Replicated>
158             See L<DBIx::Class::Storage::DBI::Replicated> for more details.
159             Here is an example configuration that adds two read slaves:
160              
161             plugins:
162             DBIC:
163             default:
164             schema_class: MyApp::Schema
165             dsn: dbi:Pg:dbname=master
166             replicated:
167             balancer_type: ::Random # optional
168             balancer_args: # optional
169             auto_validate_every: 5 # optional
170             master_read_weight:1 # optional
171             # pool_type and pool_args are also allowed and are also optional
172             replicants:
173             -
174             - dbi:Pg:dbname=slave1
175             - user1
176             - password1
177             -
178             quote_names: 1
179             pg_enable_utf8: 1
180             -
181             - dbi:Pg:dbname=slave2
182             - user2
183             - password2
184             -
185             quote_names: 1
186             pg_enable_utf8: 1
187              
188             =head2 alias
189              
190             Schema aliases allow you to reference the same underlying database by multiple
191             names.
192             For example:
193              
194             plugins:
195             DBIC:
196             default:
197             dsn: dbi:Pg:dbname=master
198             schema_class: MyApp::Schema
199             slave1:
200             alias: default
201              
202             Now you can access the default schema with C<schema()>, C<schema('default')>,
203             or C<schema('slave1')>.
204             This can come in handy if, for example, you have master/slave replication in
205             your production environment but only a single database in your development
206             environment.
207             You can continue to reference C<schema('slave1')> in your code in both
208             environments by simply creating a schema alias in your development.yml config
209             file, as shown above.
210              
211             =head1 FUNCTIONS
212              
213             =head2 schema
214              
215             my $user = schema->resultset('User')->find('bob');
216              
217             The C<schema> keyword returns a L<DBIx::Class::Schema> object ready for you to
218             use.
219             If you have configured only one database, then you can simply call C<schema>
220             with no arguments.
221             If you have configured multiple databases,
222             you can still call C<schema> with no arguments if there is a database
223             named C<default> in the configuration.
224             With no argument, the C<default> schema is returned.
225             Otherwise, you B<must> provide C<schema()> with the name of the database:
226              
227             my $user = schema('foo')->resultset('User')->find('bob');
228              
229             =head2 resultset
230              
231             This is a convenience method that will save you some typing.
232             Use this B<only> when accessing the C<default> schema.
233              
234             my $user = resultset('User')->find('bob');
235              
236             is equivalent to:
237              
238             my $user = schema->resultset('User')->find('bob');
239              
240             =head2 rset
241              
242             my $user = rset('User')->find('bob');
243              
244             This is simply an alias for C<resultset>.
245              
246             =head1 SCHEMA GENERATION
247              
248             Setting the schema_class option and having proper DBIx::Class classes
249             is the recommended approach for performance and stability.
250             You can use the L<dbicdump> command line tool provided by
251             L<DBIx::Class::Schema::Loader> to help you.
252             For example, if your app were named Foo, then you could run the following
253             from the root of your project directory:
254              
255             dbicdump -o dump_directory=./lib Foo::Schema dbi:SQLite:/path/to/foo.db
256              
257             For this example, your C<schema_class> setting would be C<'Foo::Schema'>.
258              
259             =head1 SEE ALSO
260              
261             =over 4
262              
263             =item *
264              
265             L<DBICx::Sugar>
266              
267             =back
268              
269             =head1 CONTRIBUTORS
270              
271             =over 4
272              
273             =item *
274              
275             Alexis Sukrieh <sukria@sukria.net>
276              
277             =item *
278              
279             Dagfinn Ilmari MannsÃ¥ker <L<https://github.com/ilmari>>
280              
281             =item *
282              
283             David Precious <davidp@preshweb.co.uk>
284              
285             =item *
286              
287             Fabrice Gabolde <L<https://github.com/fgabolde>>
288              
289             =item *
290              
291             Franck Cuny <franck@lumberjaph.net>
292              
293             =item *
294              
295             Steven Humphrey <L<https://github.com/shumphrey>>
296              
297             =item *
298              
299             Yanick Champoux <L<https://github.com/yanick>>
300              
301             =back
302              
303             =head1 AUTHORS
304              
305             =over 4
306              
307             =item *
308              
309             Al Newkirk <awncorp@cpan.org>
310              
311             =item *
312              
313             Naveed Massjouni <naveed@vt.edu>
314              
315             =back
316              
317             =head1 COPYRIGHT AND LICENSE
318              
319             This software is copyright (c) 2010 by awncorp.
320              
321             This is free software; you can redistribute it and/or modify it under
322             the same terms as the Perl 5 programming language system itself.
323              
324             =cut