| 1 |
NAME |
| 2 |
|
| 3 |
DBICx::Sugar - Just some syntax sugar for DBIx::Class |
| 4 |
|
| 5 |
VERSION |
| 6 |
|
| 7 |
version 0.0200 |
| 8 |
|
| 9 |
SYNOPSIS |
| 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 |
|
| 20 |
DESCRIPTION |
| 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 |
|
| 26 |
CONFIGURATION |
| 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 |
|
| 158 |
FUNCTIONS |
| 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 |
|
| 209 |
SCHEMA 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 |
|
| 221 |
CONTRIBUTORS |
| 222 |
|
| 223 |
* Henk van Oers <https://github.com/hvoers> |
| 224 |
|
| 225 |
AUTHOR |
| 226 |
|
| 227 |
Naveed Massjouni <[email protected]> |
| 228 |
|
| 229 |
COPYRIGHT 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 |
|