README
1NAME
2
3 DBICx::Sugar - Just some syntax sugar for DBIx::Class
4
5VERSION
6
7 version 0.0200
8
9SYNOPSIS
10
11 use DBICx::Sugar qw(schema resultset rset);
12
13 # all of the following are equivalent:
14
15 $user = schema('default')->resultset('User')->find('bob');
16 $user = schema->resultset('User')->find('bob');
17 $user = resultset('User')->find('bob');
18 $user = rset('User')->find('bob');
19
20DESCRIPTION
21
22 Just some syntax sugar for your DBIx::Class applications. This was
23 originally created to remove code duplication between
24 Dancer::Plugin::DBIC and Dancer2::Plugin::DBIC.
25
26CONFIGURATION
27
28 Configuration can be automatically parsed from a `config.yaml` or
29 `config.yml` file in the current working directory, or it can be
30 explicitly set with the config function:
31
32 DBICx::Sugar::config({ default => { dsn => ... } });
33
34 If you want the config to be autoloaded from a yaml config file, just
35 make sure to put your config data under a top level dbicx_sugar key.
36
37 simple example
38
39 Here is a simple example. It defines one database named default:
40
41 dbicx_sugar:
42 default:
43 dsn: dbi:SQLite:dbname=myapp.db
44 schema_class: MyApp::Schema
45
46 multiple schemas
47
48 In this example, there are 2 databases configured named default and
49 foo:
50
51 dbicx_sugar:
52 default:
53 dsn: dbi:SQLite:dbname=myapp.db
54 schema_class: MyApp::Schema
55 foo:
56 dsn: dbi:Pg:dbname=foo
57 schema_class: Foo::Schema
58 user: bob
59 password: secret
60 options:
61 RaiseError: 1
62 PrintError: 1
63
64 Each database configured must at least have a dsn option. The dsn
65 option should be the DBI driver connection string. All other options
66 are optional.
67
68 If you only have one schema configured, or one of them is named
69 default, you can call schema without an argument to get the only or
70 default schema, respectively.
71
72 If a schema_class option is not provided, then
73 DBIx::Class::Schema::Loader will be used to dynamically load the schema
74 by introspecting the database corresponding to the dsn value. You need
75 DBIx::Class::Schema::Loader installed for this to work.
76
77 WARNING: Dynamic loading is not recommended for production
78 environments. It is almost always better to provide a schema_class
79 option.
80
81 The schema_class option should be the name of your DBIx::Class::Schema
82 class. See "SCHEMA GENERATION" Optionally, a database configuration may
83 have user, password, and options parameters as described in the
84 documentation for connect() in DBI.
85
86 connect_info
87
88 Alternatively, you may also declare your connection information inside
89 an array named connect_info:
90
91 dbicx_sugar:
92 default:
93 schema_class: MyApp::Schema
94 connect_info:
95 - dbi:Pg:dbname=foo
96 - bob
97 - secret
98 -
99 RaiseError: 1
100 PrintError: 1
101
102 replicated
103
104 You can also add database read slaves to your configuration with the
105 replicated config option. This will automatically make your read
106 queries go to a slave and your write queries go to the master. Keep in
107 mind that this will require additional dependencies:
108 DBIx::Class::Optional::Dependencies#Storage::Replicated See
109 DBIx::Class::Storage::DBI::Replicated for more details. Here is an
110 example configuration that adds two read slaves:
111
112 dbicx_sugar:
113 default:
114 schema_class: MyApp::Schema
115 dsn: dbi:Pg:dbname=master
116 replicated:
117 balancer_type: ::Random # optional
118 balancer_args: # optional
119 auto_validate_every: 5 # optional
120 master_read_weight:1 # optional
121 # pool_type and pool_args are also allowed and are also optional
122 replicants:
123 -
124 - dbi:Pg:dbname=slave1
125 - user1
126 - password1
127 -
128 quote_names: 1
129 pg_enable_utf8: 1
130 -
131 - dbi:Pg:dbname=slave2
132 - user2
133 - password2
134 -
135 quote_names: 1
136 pg_enable_utf8: 1
137
138 alias
139
140 Schema aliases allow you to reference the same underlying database by
141 multiple names. For example:
142
143 dbicx_sugar:
144 default:
145 dsn: dbi:Pg:dbname=master
146 schema_class: MyApp::Schema
147 slave1:
148 alias: default
149
150 Now you can access the default schema with schema(), schema('default'),
151 or schema('slave1'). This can come in handy if, for example, you have
152 master/slave replication in your production environment but only a
153 single database in your development environment. You can continue to
154 reference schema('slave1') in your code in both environments by simply
155 creating a schema alias in your development.yml config file, as shown
156 above.
157
158FUNCTIONS
159
160 schema
161
162 my $user = schema->resultset('User')->find('bob');
163
164 Returns a DBIx::Class::Schema object ready for you to use. For
165 performance, schema objects are cached in memory and are lazy loaded
166 the first time they are accessed. If you have configured only one
167 database, then you can simply call schema with no arguments. If you
168 have configured multiple databases, you can still call schema with no
169 arguments if there is a database named default in the configuration.
170 With no argument, the default schema is returned. Otherwise, you must
171 provide schema() with the name of the database:
172
173 my $user = schema('foo')->resultset('User')->find('bob');
174
175 resultset
176
177 This is a convenience method that will save you some typing. Use this
178 only when accessing the default schema.
179
180 my $user = resultset('User')->find('bob');
181
182 is equivalent to:
183
184 my $user = schema->resultset('User')->find('bob');
185
186 rset
187
188 my $user = rset('User')->find('bob');
189
190 This is simply an alias for resultset.
191
192 get_config
193
194 Returns the current configuration, like config does, but does not look
195 for a config file.
196
197 Use this for introspection, eg:
198
199 my $dbix_sugar_is_configured = get_config ? 1 : 0 ;
200
201 add_schema_to_config
202
203 This function does not touch the existing config. It can be used if
204 some other part of your app has configured DBICx::Sugar but did not
205 know about the part that uses an extra schema.
206
207 add_schema_to_config('schema_name', { dsn => ... });
208
209SCHEMA GENERATION
210
211 Setting the schema_class option and having proper DBIx::Class classes
212 is the recommended approach for performance and stability. You can use
213 the dbicdump command line tool provided by DBIx::Class::Schema::Loader
214 to help you. For example, if your app were named Foo, then you could
215 run the following from the root of your project directory:
216
217 dbicdump -o dump_directory=./lib Foo::Schema dbi:SQLite:/path/to/foo.db
218
219 For this example, your schema_class setting would be 'Foo::Schema'.
220
221CONTRIBUTORS
222
223 * Henk van Oers <https://github.com/hvoers>
224
225AUTHOR
226
227 Naveed Massjouni <naveed@vt.edu>
228
229COPYRIGHT AND LICENSE
230
231 This software is copyright (c) 2015 by Naveed Massjouni.
232
233 This is free software; you can redistribute it and/or modify it under
234 the same terms as the Perl 5 programming language system itself.
235
236