1DBICx::Sugar(3)       User Contributed Perl Documentation      DBICx::Sugar(3)
2
3
4

NAME

6       DBICx::Sugar - Just some syntax sugar for DBIx::Class
7

VERSION

9       version 0.0200
10

SYNOPSIS

12           use DBICx::Sugar qw(schema resultset rset);
13
14           # all of the following are equivalent:
15
16           $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

DESCRIPTION

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

CONFIGURATION

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
31           DBICx::Sugar::config({ default => { dsn => ... } });
32
33       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
36   simple example
37       Here is a simple example. It defines one database named "default":
38
39           dbicx_sugar:
40             default:
41               dsn: dbi:SQLite:dbname=myapp.db
42               schema_class: MyApp::Schema
43
44   multiple schemas
45       In this example, there are 2 databases configured named "default" and
46       "foo":
47
48           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
61       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
65       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
69       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
74       WARNING: Dynamic loading is not recommended for production
75       environments.  It is almost always better to provide a schema_class
76       option.
77
78       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
83   connect_info
84       Alternatively, you may also declare your connection information inside
85       an array named "connect_info":
86
87           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
98   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
107           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
133   alias
134       Schema aliases allow you to reference the same underlying database by
135       multiple names.  For example:
136
137           dbicx_sugar:
138             default:
139               dsn: dbi:Pg:dbname=master
140               schema_class: MyApp::Schema
141             slave1:
142               alias: default
143
144       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

FUNCTIONS

153   schema
154           my $user = schema->resultset('User')->find('bob');
155
156       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
165           my $user = schema('foo')->resultset('User')->find('bob');
166
167   resultset
168       This is a convenience method that will save you some typing.  Use this
169       only when accessing the "default" schema.
170
171           my $user = resultset('User')->find('bob');
172
173       is equivalent to:
174
175           my $user = schema->resultset('User')->find('bob');
176
177   rset
178           my $user = rset('User')->find('bob');
179
180       This is simply an alias for "resultset".
181
182   get_config
183       Returns the current configuration, like config does, but does not look
184       for a config file.
185
186       Use this for introspection, eg:
187
188           my $dbix_sugar_is_configured = get_config ? 1 : 0 ;
189
190   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
195           add_schema_to_config('schema_name', { dsn => ... });
196

SCHEMA GENERATION

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
204           dbicdump -o dump_directory=./lib Foo::Schema dbi:SQLite:/path/to/foo.db
205
206       For this example, your "schema_class" setting would be 'Foo::Schema'.
207

CONTRIBUTORS

209       •   Henk van Oers <<https://github.com/hvoers>>
210

AUTHOR

212       Naveed Massjouni <naveed@vt.edu>
213
215       This software is copyright (c) 2015 by Naveed Massjouni.
216
217       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.
219
220
221
222perl v5.34.0                      2022-01-21                   DBICx::Sugar(3)
Impressum