1 package Dancer2::Plugin::DBIC;
3 our $VERSION = '0.0100'; # VERSION
12 my ($dsl, $name, $cfg) = @_;
14 # ugly switch needed to support plugin2 plugins which use this plugin
15 # whilst still working for plugin1
16 if ( $dsl->app->can('with_plugin') ) {
17 $config = $dsl->config;
20 $config = plugin_setting;
22 DBICx::Sugar::config( $config );
23 return DBICx::Sugar::schema($name, $cfg);
27 my ($dsl, $rset_name) = @_;
28 return schema($dsl)->resultset($rset_name);
31 register schema => \&_schema;
32 register resultset => \&_rset;
33 register rset => \&_rset;
36 # ABSTRACT: DBIx::Class interface for Dancer2 applications
49 Dancer2::Plugin::DBIC - DBIx::Class interface for Dancer2 applications
58 use Dancer2::Plugin::DBIC;
60 get '/users/:user_id' => sub {
61 my $user = schema('default')->resultset('User')->find(param 'user_id');
63 # If you are accessing the 'default' schema, then all the following
64 # are equivalent to the above:
65 $user = schema->resultset('User')->find(param 'user_id');
66 $user = resultset('User')->find(param 'user_id');
67 $user = rset('User')->find(param 'user_id');
69 template user_profile => {
78 This plugin makes it very easy to create L<Dancer2> applications that interface
80 It automatically exports the keyword C<schema> which returns a
81 L<DBIx::Class::Schema> object.
82 It also exports the keywords C<resultset> and C<rset>.
83 You just need to configure your database connection information.
84 For performance, schema objects are cached in memory
85 and are lazy loaded the first time they are accessed.
87 This plugin is a thin wrapper around L<DBICx::Sugar>.
91 Configuration can be done in your L<Dancer2> config file.
92 This is a minimal example. It defines one database named C<default>:
97 dsn: dbi:SQLite:dbname=some.db
99 In this example, there are 2 databases configured named C<default> and C<foo>:
104 dsn: dbi:SQLite:dbname=some.db
105 schema_class: MyApp::Schema
108 schema_class: Foo::Schema
115 Each database configured must at least have a dsn option.
116 The dsn option should be the L<DBI> driver connection string.
117 All other options are optional.
119 If you only have one schema configured, or one of them is named
120 C<default>, you can call C<schema> without an argument to get the only
121 or C<default> schema, respectively.
123 If a schema_class option is not provided, then L<DBIx::Class::Schema::Loader>
124 will be used to dynamically load the schema by introspecting the database
125 corresponding to the dsn value.
126 Remember that you need L<DBIx::Class::Schema::Loader> installed to take
129 The schema_class option, should be a proper Perl package name that
130 Dancer2::Plugin::DBIC will use as a L<DBIx::Class::Schema> class.
131 Optionally, a database configuration may have user, password, and options
132 parameters as described in the documentation for C<connect()> in L<DBI>.
134 You may also declare your connection information in the following format
135 (which may look more familiar to DBIC users):
152 my $user = schema->resultset('User')->find('bob');
154 The C<schema> keyword returns a L<DBIx::Class::Schema> object ready for you to
156 If you have configured only one database, then you can simply call C<schema>
158 If you have configured multiple databases,
159 you can still call C<schema> with no arguments if there is a database
160 named C<default> in the configuration.
161 With no argument, the C<default> schema is returned.
162 Otherwise, you B<must> provide C<schema()> with the name of the database:
164 my $user = schema('foo')->resultset('User')->find('bob');
168 This is a convenience method that will save you some typing.
169 Use this B<only> when accessing the C<default> schema.
171 my $user = resultset('User')->find('bob');
175 my $user = schema->resultset('User')->find('bob');
179 my $user = rset('User')->find('bob');
181 This is simply an alias for C<resultset>.
183 =head1 SCHEMA GENERATION
185 There are two approaches for generating schema classes.
186 You may generate your own L<DBIx::Class> classes and set
187 the corresponding C<schema_class> setting in your configuration as shown above.
188 This is the recommended approach for performance and stability.
190 It is also possible to have schema classes dynamically generated
191 if you omit the C<schema_class> configuration setting.
192 This requires you to have L<DBIx::Class::Schema::Loader> installed.
193 The C<v7> naming scheme will be used for naming the auto generated classes.
194 See L<DBIx::Class::Schema::Loader::Base/naming> for more information about
197 For generating your own schema classes,
198 you can use the L<dbicdump> command line tool provided by
199 L<DBIx::Class::Schema::Loader> to help you.
200 For example, if your app were named Foo, then you could run the following
201 from the root of your project directory:
203 dbicdump -o dump_directory=./lib Foo::Schema dbi:SQLite:/path/to/foo.db
205 For that example, your C<schema_class> setting would be C<Foo::Schema>.
223 Alexis Sukrieh <sukria@sukria.net>
227 Dagfinn Ilmari Mannsåker <L<https://github.com/ilmari>>
231 David Precious <davidp@preshweb.co.uk>
235 ennio <L<https://github.com/scriplit>>
239 Fabrice Gabolde <L<https://github.com/fgabolde>>
243 Franck Cuny <franck@lumberjaph.net>
247 Steven Humphrey <L<https://github.com/shumphrey>>
251 Yanick Champoux <L<https://github.com/yanick>>
257 Naveed Massjouni <naveed@vt.edu>
259 =head1 COPYRIGHT AND LICENSE
261 This software is copyright (c) 2013 by Naveed Massjouni.
263 This is free software; you can redistribute it and/or modify it under
264 the same terms as the Perl 5 programming language system itself.