Commit | Line | Data |
18fca96a |
1 | package DBIx::Class::Schema::Loader; |
a78e3fed |
2 | |
3 | use strict; |
a4a19f3c |
4 | use warnings; |
8a6b44ef |
5 | use base qw/DBIx::Class::Schema/; |
6 | use base qw/Class::Data::Accessor/; |
fa994d3c |
7 | use Carp::Clan qw/^DBIx::Class/; |
457eb8a6 |
8 | use UNIVERSAL::require; |
996be9ee |
9 | use Class::C3; |
c9f1d7b0 |
10 | use Scalar::Util qw/ weaken /; |
3980d69c |
11 | |
a4a19f3c |
12 | # Always remember to do all digits for the version even if they're 0 |
13 | # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports |
14 | # brain damage and presumably various other packaging systems too |
520107ef |
15 | our $VERSION = '0.03006'; |
457eb8a6 |
16 | |
996be9ee |
17 | __PACKAGE__->mk_classaccessor('dump_to_dir'); |
457eb8a6 |
18 | __PACKAGE__->mk_classaccessor('loader'); |
996be9ee |
19 | __PACKAGE__->mk_classaccessor('_loader_args'); |
a78e3fed |
20 | |
21 | =head1 NAME |
22 | |
18fca96a |
23 | DBIx::Class::Schema::Loader - Dynamic definition of a DBIx::Class::Schema |
a78e3fed |
24 | |
25 | =head1 SYNOPSIS |
26 | |
a4a19f3c |
27 | package My::Schema; |
28 | use base qw/DBIx::Class::Schema::Loader/; |
a78e3fed |
29 | |
996be9ee |
30 | __PACKAGE__->loader_options( |
31 | relationships => 1, |
32 | constraint => '^foo.*', |
33 | # debug => 1, |
a78e3fed |
34 | ); |
af6c2665 |
35 | |
a4a19f3c |
36 | # in seperate application code ... |
a78e3fed |
37 | |
a4a19f3c |
38 | use My::Schema; |
a78e3fed |
39 | |
a4a19f3c |
40 | my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs); |
41 | # -or- |
996be9ee |
42 | my $schema1 = "My::Schema"; $schema1->connection(as above); |
074e81cd |
43 | |
996be9ee |
44 | =head1 DESCRIPTION |
074e81cd |
45 | |
fbd83464 |
46 | DBIx::Class::Schema::Loader automates the definition of a |
996be9ee |
47 | L<DBIx::Class::Schema> by scanning database table definitions and |
d65cda9e |
48 | setting up the columns, primary keys, and relationships. |
a78e3fed |
49 | |
d65cda9e |
50 | DBIx::Class::Schema::Loader currently supports only the DBI storage type. |
51 | It has explicit support for L<DBD::Pg>, L<DBD::mysql>, L<DBD::DB2>, and |
52 | L<DBD::SQLite>. Other DBI drivers may function to a greater or lesser |
53 | degree with this loader, depending on how much of the DBI spec they |
54 | implement, and how standard their implementation is. Patches to make |
55 | other DBDs work correctly welcome. |
a78e3fed |
56 | |
996be9ee |
57 | See L<DBIx::Class::Schema::Loader::DBI::Writing> for notes on writing |
58 | your own vendor-specific subclass for an unsupported DBD driver. |
a78e3fed |
59 | |
996be9ee |
60 | This module requires L<DBIx::Class> 0.06 or later, and obsoletes |
61 | the older L<DBIx::Class::Loader>. |
89ecd854 |
62 | |
996be9ee |
63 | This module is designed more to get you up and running quickly against |
64 | an existing database, or to be effective for simple situations, rather |
65 | than to be what you use in the long term for a complex database/project. |
89ecd854 |
66 | |
67 | That being said, transitioning your code from a Schema generated by this |
68 | module to one that doesn't use this module should be straightforward and |
996be9ee |
69 | painless (as long as you're not using any methods that are now deprecated |
70 | in this document), so don't shy away from it just for fears of the |
71 | transition down the road. |
89ecd854 |
72 | |
a78e3fed |
73 | =head1 METHODS |
74 | |
996be9ee |
75 | =head2 loader_options |
a78e3fed |
76 | |
996be9ee |
77 | Example in Synopsis above demonstrates a few common arguments. For |
78 | detailed information on all of the arguments, most of which are |
79 | only useful in fairly complex scenarios, see the |
80 | L<DBIx::Class::Schema::Loader::Base> documentation. |
a78e3fed |
81 | |
d65cda9e |
82 | This method is *required* at this time, for backwards compatibility |
83 | reasons. If you do not wish to change any options, just call it |
84 | with an empty argument list during schema class initialization. |
85 | |
fa994d3c |
86 | Setting these options explicitly via this method B<after> calling |
87 | C<connection> is deprecated and will stop working in version 0.04000. |
88 | For now the code merely warns about this condition. |
89 | |
90 | The preferred way of doing things is to either call C<loader_options> |
91 | before any connection is made, or embed the C<loader_options> in |
92 | the connection information itself as shown below. |
a78e3fed |
93 | |
996be9ee |
94 | =cut |
1031d4f6 |
95 | |
996be9ee |
96 | sub loader_options { |
97 | my $self = shift; |
98 | |
d65cda9e |
99 | my %args = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_; |
1031d4f6 |
100 | |
996be9ee |
101 | my $class = ref $self || $self; |
102 | $args{schema} = $self; |
103 | $args{schema_class} = $class; |
c9f1d7b0 |
104 | weaken($args{schema}) if ref $self; |
105 | |
996be9ee |
106 | $self->_loader_args(\%args); |
d65cda9e |
107 | if($self->storage && !$class->loader) { |
fa994d3c |
108 | warn "Do not set loader_options after specifying the connection info," |
109 | . " this will be unsupported in 0.04000"; |
d65cda9e |
110 | $self->_invoke_loader; |
111 | } |
996be9ee |
112 | |
113 | $self; |
114 | } |
115 | |
116 | sub _invoke_loader { |
117 | my $self = shift; |
118 | my $class = ref $self || $self; |
119 | |
120 | $self->_loader_args->{dump_directory} ||= $self->dump_to_dir; |
af6c2665 |
121 | |
996be9ee |
122 | # XXX this only works for relative storage_type, like ::DBI ... |
123 | my $impl = "DBIx::Class::Schema::Loader" . $self->storage_type; |
a78e3fed |
124 | $impl->require or |
996be9ee |
125 | croak qq/Could not load storage_type loader "$impl": / . |
3385ac62 |
126 | qq/"$UNIVERSAL::require::ERROR"/; |
af6c2665 |
127 | |
996be9ee |
128 | # XXX in the future when we get rid of ->loader, the next two |
129 | # lines can be replaced by "$impl->new(%{$self->_loader_args})->load;" |
130 | $class->loader($impl->new(%{$self->_loader_args})); |
2a4b8262 |
131 | $class->loader->load; |
996be9ee |
132 | |
996be9ee |
133 | $self; |
134 | } |
135 | |
136 | =head2 connection |
137 | |
d65cda9e |
138 | See L<DBIx::Class::Schema> for basic usage. |
139 | |
140 | If the final argument is a hashref, and it contains a key C<loader_options>, |
141 | that key will be deleted, and its value will be used for the loader options, |
142 | just as if set via the L</loader_options> method above. |
143 | |
144 | The actual auto-loading operation (the heart of this module) will be invoked |
145 | as soon as the connection information is defined. |
996be9ee |
146 | |
147 | =cut |
148 | |
149 | sub connection { |
d65cda9e |
150 | my $self = shift; |
151 | |
152 | if($_[-1] && ref $_[-1] eq 'HASH') { |
153 | if(my $loader_opts = delete $_[-1]->{loader_options}) { |
154 | $self->loader_options($loader_opts); |
fd64d90d |
155 | pop @_ if !keys %{$_[-1]}; |
d65cda9e |
156 | } |
157 | } |
158 | |
159 | $self = $self->next::method(@_); |
996be9ee |
160 | |
161 | my $class = ref $self || $self; |
fa994d3c |
162 | if($self->_loader_args && !$class->loader) { |
163 | $self->_invoke_loader |
164 | } |
165 | else { |
166 | warn "loader_options should be set before connecting the " |
167 | . "schema, see the DBIx::Class::Schema::Loader docs"; |
168 | } |
996be9ee |
169 | |
170 | return $self; |
171 | } |
172 | |
173 | =head2 clone |
174 | |
074e81cd |
175 | See L<DBIx::Class::Schema>. |
996be9ee |
176 | |
177 | =cut |
178 | |
179 | sub clone { |
180 | my $self = shift; |
181 | |
182 | my $clone = $self->next::method(@_); |
183 | |
fa994d3c |
184 | if($clone->_loader_args) { |
185 | $clone->_loader_args->{schema} = $clone; |
186 | weaken($clone->_loader_args->{schema}); |
187 | } |
996be9ee |
188 | |
189 | $clone; |
190 | } |
191 | |
192 | =head2 dump_to_dir |
193 | |
194 | Argument: directory name. |
195 | |
196 | Calling this as a class method on either L<DBIx::Class::Schema::Loader> |
197 | or any derived schema class will cause all affected schemas to dump |
198 | manual versions of themselves to the named directory when they are |
199 | loaded. In order to be effective, this must be set before defining a |
200 | connection on this schema class or any derived object (as the loading |
074e81cd |
201 | happens as soon as both a connection and loader_options are set, and |
202 | only once per class). |
996be9ee |
203 | |
204 | See L<DBIx::Class::Schema::Loader::Base/dump_directory> for more |
205 | details on the dumping mechanism. |
206 | |
207 | This can also be set at module import time via the import option |
208 | C<dump_to_dir:/foo/bar> to L<DBIx::Class::Schema::Loader>, where |
209 | C</foo/bar> is the target directory. |
210 | |
211 | Examples: |
212 | |
213 | # My::Schema isa DBIx::Class::Schema::Loader, and has connection info |
214 | # hardcoded in the class itself: |
215 | perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1 |
216 | |
217 | # Same, but no hard-coded connection, so we must provide one: |
218 | perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)' |
219 | |
220 | # Or as a class method, as long as you get it done *before* defining a |
221 | # connection on this schema class or any derived object: |
222 | use My::Schema; |
223 | My::Schema->dump_to_dir('/foo/bar'); |
224 | My::Schema->connection(........); |
225 | |
226 | # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all |
227 | # derived schemas |
228 | use My::Schema; |
229 | use My::OtherSchema; |
230 | DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar'); |
231 | My::Schema->connection(.......); |
232 | My::OtherSchema->connection(.......); |
233 | |
234 | # Another alternative to the above: |
235 | use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |; |
236 | use My::Schema; |
237 | use My::OtherSchema; |
238 | My::Schema->connection(.......); |
239 | My::OtherSchema->connection(.......); |
240 | |
241 | =cut |
242 | |
243 | sub import { |
244 | my $self = shift; |
245 | return if !@_; |
246 | foreach my $opt (@_) { |
247 | if($opt =~ m{^dump_to_dir:(.*)$}) { |
248 | $self->dump_to_dir($1) |
249 | } |
250 | elsif($opt eq 'make_schema_at') { |
251 | no strict 'refs'; |
252 | my $cpkg = (caller)[0]; |
253 | *{"${cpkg}::make_schema_at"} = \&make_schema_at; |
254 | } |
255 | } |
256 | } |
257 | |
258 | =head2 make_schema_at |
259 | |
260 | This simple function allows one to create a Loader-based schema |
261 | in-memory on the fly without any on-disk class files of any |
262 | kind. When used with the C<dump_directory> option, you can |
8f9d7ce5 |
263 | use this to generate a rough draft manual schema from a dsn |
996be9ee |
264 | without the intermediate step of creating a physical Loader-based |
265 | schema class. |
266 | |
483987b9 |
267 | The return value is the input class name. |
268 | |
996be9ee |
269 | This function can be exported/imported by the normal means, as |
270 | illustrated in these Examples: |
271 | |
5223f24a |
272 | # Simple example, creates as a new class 'New::Schema::Name' in |
273 | # memory in the running perl interpreter. |
996be9ee |
274 | use DBIx::Class::Schema::Loader qw/ make_schema_at /; |
275 | make_schema_at( |
276 | 'New::Schema::Name', |
277 | { relationships => 1, debug => 1 }, |
278 | [ 'dbi:Pg:dbname="foo"','postgres' ], |
279 | ); |
280 | |
281 | # Complex: dump loaded schema to disk, all from the commandline: |
5223f24a |
282 | perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib -e 'make_schema_at("New::Schema::Name", { relationships => 1 }, [ "dbi:Pg:dbname=foo","postgres" ])' |
996be9ee |
283 | |
284 | # Same, but inside a script, and using a different way to specify the |
285 | # dump directory: |
286 | use DBIx::Class::Schema::Loader qw/ make_schema_at /; |
287 | make_schema_at( |
288 | 'New::Schema::Name', |
289 | { relationships => 1, debug => 1, dump_directory => './lib' }, |
290 | [ 'dbi:Pg:dbname="foo"','postgres' ], |
291 | ); |
292 | |
293 | =cut |
294 | |
295 | sub make_schema_at { |
296 | my ($target, $opts, $connect_info) = @_; |
297 | |
483987b9 |
298 | { |
299 | no strict 'refs'; |
300 | @{$target . '::ISA'} = qw/DBIx::Class::Schema::Loader/; |
301 | } |
302 | |
303 | $target->loader_options($opts); |
304 | $target->connection(@$connect_info); |
996be9ee |
305 | } |
306 | |
307 | =head1 EXAMPLE |
308 | |
309 | Using the example in L<DBIx::Class::Manual::ExampleSchema> as a basis |
310 | replace the DB::Main with the following code: |
311 | |
312 | package DB::Main; |
313 | |
314 | use base qw/DBIx::Class::Schema::Loader/; |
315 | |
316 | __PACKAGE__->loader_options( |
317 | relationships => 1, |
318 | debug => 1, |
319 | ); |
320 | __PACKAGE__->connection('dbi:SQLite:example.db'); |
321 | |
322 | 1; |
323 | |
324 | and remove the Main directory tree (optional). Every thing else |
325 | should work the same |
326 | |
327 | =head1 DEPRECATED METHODS |
328 | |
329 | You don't need to read anything in this section unless you're upgrading |
330 | code that was written against pre-0.03 versions of this module. This |
331 | version is intended to be backwards-compatible with pre-0.03 code, but |
332 | will issue warnings about your usage of deprecated features/methods. |
333 | |
d65cda9e |
334 | B<All of these deprecated methods will dissappear in version 0.04000>, |
335 | and converting code that uses these methods should be trivial. |
336 | |
996be9ee |
337 | =head2 load_from_connection |
338 | |
339 | This deprecated method is now roughly an alias for L</loader_options>. |
340 | |
996be9ee |
341 | For now, using this method will invoke the legacy behavior for |
342 | backwards compatibility, and merely emit a warning about upgrading |
343 | your code. |
344 | |
345 | It also reverts the default inflection scheme to |
346 | use L<Lingua::EN::Inflect> just like pre-0.03 versions of this |
347 | module did. |
348 | |
349 | You can force these legacy inflections with the |
d65cda9e |
350 | option L<DBIx::Class::Schema::Loader::Base/legacy_default_inflections>, |
351 | even after switch over to the preferred L</loader_options> way of doing |
352 | things. That option will not go away until at least 0.05. |
996be9ee |
353 | |
354 | See the source of this method for more details. |
355 | |
356 | =cut |
357 | |
358 | sub load_from_connection { |
359 | my ($self, %args) = @_; |
8f9d7ce5 |
360 | |
361 | my $cmds_ver = $Catalyst::Model::DBIC::Schema::VERSION; |
362 | if($cmds_ver) { |
363 | if($cmds_ver < 0.14) { |
364 | warn 'You should upgrade your installation of' |
365 | . ' Catalyst::Model::DBIC::Schema to 0.14 or higher, then:'; |
366 | } |
367 | warn 'You should regenerate your Model files, which may eliminate' |
368 | . ' the following deprecation warning:'; |
369 | } |
d65cda9e |
370 | warn 'load_from_connection deprecated, and will dissappear in 0.04000, ' |
371 | . 'please [re-]read the [new] DBIx::Class::Schema::Loader ' |
372 | . 'documentation'; |
996be9ee |
373 | |
374 | # Support the old connect_info / dsn / etc args... |
375 | $args{connect_info} = [ |
376 | delete $args{dsn}, |
377 | delete $args{user}, |
378 | delete $args{password}, |
379 | delete $args{options}, |
380 | ] if $args{dsn}; |
381 | |
382 | $self->connection(@{delete $args{connect_info}}) |
383 | if $args{connect_info}; |
384 | |
385 | $self->loader_options('legacy_default_inflections' => 1, %args); |
a78e3fed |
386 | } |
387 | |
457eb8a6 |
388 | =head2 loader |
389 | |
390 | This is an accessor in the generated Schema class for accessing |
996be9ee |
391 | the L<DBIx::Class::Schema::Loader::Base> -based loader object |
457eb8a6 |
392 | that was used during construction. See the |
996be9ee |
393 | L<DBIx::Class::Schema::Loader::Base> docs for more information |
457eb8a6 |
394 | on the available loader methods there. |
395 | |
996be9ee |
396 | This accessor is deprecated. Do not use it. Anything you can |
397 | get from C<loader>, you can get via the normal L<DBIx::Class::Schema> |
398 | methods, and your code will be more robust and forward-thinking |
399 | for doing so. |
400 | |
401 | If you're already using C<loader> in your code, make an effort |
402 | to get rid of it. If you think you've found a situation where it |
8f9d7ce5 |
403 | is necessary, let me know and we'll see what we can do to remedy |
996be9ee |
404 | that situation. |
405 | |
406 | In some future version, this accessor *will* disappear. It was |
407 | apparently quite a design/API mistake to ever have exposed it to |
408 | user-land in the first place, all things considered. |
409 | |
410 | =head1 KNOWN ISSUES |
411 | |
412 | =head2 Multiple Database Schemas |
413 | |
414 | Currently the loader is limited to working within a single schema |
415 | (using the database vendors' definition of "schema"). If you |
416 | have a multi-schema database with inter-schema relationships (which |
8f9d7ce5 |
417 | is easy to do in PostgreSQL or DB2 for instance), you only get to |
996be9ee |
418 | automatically load the tables of one schema, and any relationships |
419 | to tables in other schemas will be silently ignored. |
420 | |
421 | At some point in the future, an intelligent way around this might be |
422 | devised, probably by allowing the C<db_schema> option to be an |
d65cda9e |
423 | arrayref of schemas to load. |
89ecd854 |
424 | |
996be9ee |
425 | In "normal" L<DBIx::Class::Schema> usage, manually-defined |
426 | source classes and relationships have no problems crossing vendor schemas. |
89ecd854 |
427 | |
a78e3fed |
428 | =head1 AUTHOR |
429 | |
f654c972 |
430 | Brandon Black, C<blblack@gmail.com> |
fbd83464 |
431 | |
8a6b44ef |
432 | Based on L<DBIx::Class::Loader> by Sebastian Riedel |
a78e3fed |
433 | |
434 | Based upon the work of IKEBE Tomohiro |
435 | |
436 | =head1 THANK YOU |
437 | |
d65cda9e |
438 | Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent |
439 | in a bug report or suggestion. |
a78e3fed |
440 | |
441 | =head1 LICENSE |
442 | |
443 | This library is free software; you can redistribute it and/or modify it under |
444 | the same terms as Perl itself. |
445 | |
446 | =head1 SEE ALSO |
447 | |
996be9ee |
448 | L<DBIx::Class>, L<DBIx::Class::Manual::ExampleSchema> |
a78e3fed |
449 | |
450 | =cut |
451 | |
452 | 1; |