README
1NAME
2
3 Dancer2::Plugin::DBIC - DBIx::Class interface for Dancer2 applications
4
5VERSION
6
7 version 0.0100
8
9SYNOPSIS
10
11 use Dancer2;
12 use Dancer2::Plugin::DBIC;
13
14 get '/users/:user_id' => sub {
15 my $user = schema('default')->resultset('User')->find(param 'user_id');
16
17 # If you are accessing the 'default' schema, then all the following
18 # are equivalent to the above:
19 $user = schema->resultset('User')->find(param 'user_id');
20 $user = resultset('User')->find(param 'user_id');
21 $user = rset('User')->find(param 'user_id');
22
23 template user_profile => {
24 user => $user
25 };
26 };
27
28 dance;
29
30DESCRIPTION
31
32 This plugin makes it very easy to create Dancer2 applications that
33 interface with databases. It automatically exports the keyword schema
34 which returns a DBIx::Class::Schema object. It also exports the
35 keywords resultset and rset. You just need to configure your database
36 connection information. For performance, schema objects are cached in
37 memory and are lazy loaded the first time they are accessed.
38
39 This plugin is a thin wrapper around DBICx::Sugar.
40
41CONFIGURATION
42
43 Configuration can be done in your Dancer2 config file. This is a
44 minimal example. It defines one database named default:
45
46 plugins:
47 DBIC:
48 default:
49 dsn: dbi:SQLite:dbname=some.db
50
51 In this example, there are 2 databases configured named default and
52 foo:
53
54 plugins:
55 DBIC:
56 default:
57 dsn: dbi:SQLite:dbname=some.db
58 schema_class: MyApp::Schema
59 foo:
60 dsn: dbi:mysql:foo
61 schema_class: Foo::Schema
62 user: bob
63 password: secret
64 options:
65 RaiseError: 1
66 PrintError: 1
67
68 Each database configured must at least have a dsn option. The dsn
69 option should be the DBI driver connection string. All other options
70 are optional.
71
72 If you only have one schema configured, or one of them is named
73 default, you can call schema without an argument to get the only or
74 default schema, respectively.
75
76 If a schema_class option is not provided, then
77 DBIx::Class::Schema::Loader will be used to dynamically load the schema
78 by introspecting the database corresponding to the dsn value. Remember
79 that you need DBIx::Class::Schema::Loader installed to take advantage
80 of that.
81
82 The schema_class option, should be a proper Perl package name that
83 Dancer2::Plugin::DBIC will use as a DBIx::Class::Schema class.
84 Optionally, a database configuration may have user, password, and
85 options parameters as described in the documentation for connect() in
86 DBI.
87
88 You may also declare your connection information in the following
89 format (which may look more familiar to DBIC users):
90
91 plugins:
92 DBIC:
93 default:
94 connect_info:
95 - dbi:mysql:foo
96 - bob
97 - secret
98 -
99 RaiseError: 1
100 PrintError: 1
101
102FUNCTIONS
103
104 schema
105
106 my $user = schema->resultset('User')->find('bob');
107
108 The schema keyword returns a DBIx::Class::Schema object ready for you
109 to use. If you have configured only one database, then you can simply
110 call schema with no arguments. If you have configured multiple
111 databases, you can still call schema with no arguments if there is a
112 database named default in the configuration. With no argument, the
113 default schema is returned. Otherwise, you must provide schema() with
114 the name of the database:
115
116 my $user = schema('foo')->resultset('User')->find('bob');
117
118 resultset
119
120 This is a convenience method that will save you some typing. Use this
121 only when accessing the default schema.
122
123 my $user = resultset('User')->find('bob');
124
125 is equivalent to:
126
127 my $user = schema->resultset('User')->find('bob');
128
129 rset
130
131 my $user = rset('User')->find('bob');
132
133 This is simply an alias for resultset.
134
135SCHEMA GENERATION
136
137 There are two approaches for generating schema classes. You may
138 generate your own DBIx::Class classes and set the corresponding
139 schema_class setting in your configuration as shown above. This is the
140 recommended approach for performance and stability.
141
142 It is also possible to have schema classes dynamically generated if you
143 omit the schema_class configuration setting. This requires you to have
144 DBIx::Class::Schema::Loader installed. The v7 naming scheme will be
145 used for naming the auto generated classes. See "naming" in
146 DBIx::Class::Schema::Loader::Base for more information about naming.
147
148 For generating your own schema classes, you can use the dbicdump
149 command line tool provided by DBIx::Class::Schema::Loader to help you.
150 For example, if your app were named Foo, then you could run the
151 following from the root of your project directory:
152
153 dbicdump -o dump_directory=./lib Foo::Schema dbi:SQLite:/path/to/foo.db
154
155 For that example, your schema_class setting would be Foo::Schema.
156
157SEE ALSO
158
159 * DBICx::Sugar
160
161CONTRIBUTORS
162
163 * Alexis Sukrieh <sukria@sukria.net>
164
165 * Dagfinn Ilmari Mannsåker <https://github.com/ilmari>
166
167 * David Precious <davidp@preshweb.co.uk>
168
169 * ennio <https://github.com/scriplit>
170
171 * Fabrice Gabolde <https://github.com/fgabolde>
172
173 * Franck Cuny <franck@lumberjaph.net>
174
175 * Steven Humphrey <https://github.com/shumphrey>
176
177 * Yanick Champoux <https://github.com/yanick>
178
179AUTHOR
180
181 Naveed Massjouni <naveed@vt.edu>
182
183COPYRIGHT AND LICENSE
184
185 This software is copyright (c) 2013 by Naveed Massjouni.
186
187 This is free software; you can redistribute it and/or modify it under
188 the same terms as the Perl 5 programming language system itself.
189
190