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