Commit | Line | Data |
18fca96a |
1 | package DBIx::Class::Schema::Loader; |
a78e3fed |
2 | |
3 | use strict; |
a4a19f3c |
4 | use warnings; |
f6148834 |
5 | use base qw/DBIx::Class::Schema Class::Data::Accessor/; |
fa994d3c |
6 | use Carp::Clan qw/^DBIx::Class/; |
996be9ee |
7 | use Class::C3; |
c9f1d7b0 |
8 | use Scalar::Util qw/ weaken /; |
3980d69c |
9 | |
a4a19f3c |
10 | # Always remember to do all digits for the version even if they're 0 |
11 | # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports |
12 | # brain damage and presumably various other packaging systems too |
0a701ff3 |
13 | our $VERSION = '0.04999_12'; |
457eb8a6 |
14 | |
59cfa251 |
15 | __PACKAGE__->mk_classaccessor('_loader_args' => {}); |
a8d229ff |
16 | __PACKAGE__->mk_classaccessors(qw/ |
17 | dump_to_dir _loader_invoked _loader loader_class naming |
18 | /); |
a78e3fed |
19 | |
20 | =head1 NAME |
21 | |
18fca96a |
22 | DBIx::Class::Schema::Loader - Dynamic definition of a DBIx::Class::Schema |
a78e3fed |
23 | |
24 | =head1 SYNOPSIS |
25 | |
707fb247 |
26 | ### use this module to generate a set of class files |
27 | |
28 | # in a script |
29 | use DBIx::Class::Schema::Loader qw/ make_schema_at /; |
30 | make_schema_at( |
31 | 'My::Schema', |
32 | { debug => 1, |
33 | dump_directory => './lib', |
34 | }, |
35 | [ 'dbi:Pg:dbname="foo"', 'myuser', 'mypassword' ], |
36 | ); |
37 | |
38 | # from the command line or a shell script with dbicdump (distributed |
39 | # with this module). Do `perldoc dbicdump` for usage. |
40 | dbicdump -o dump_directory=./lib \ |
41 | -o debug=1 \ |
42 | My::Schema \ |
43 | 'dbi:Pg:dbname=foo' \ |
44 | myuser \ |
45 | mypassword |
46 | |
47 | ### or generate and load classes at runtime |
48 | # note: this technique is not recommended |
49 | # for use in production code |
50 | |
a4a19f3c |
51 | package My::Schema; |
52 | use base qw/DBIx::Class::Schema::Loader/; |
a78e3fed |
53 | |
996be9ee |
54 | __PACKAGE__->loader_options( |
996be9ee |
55 | constraint => '^foo.*', |
56 | # debug => 1, |
a78e3fed |
57 | ); |
af6c2665 |
58 | |
707fb247 |
59 | #### in application code elsewhere: |
a78e3fed |
60 | |
a4a19f3c |
61 | use My::Schema; |
a78e3fed |
62 | |
a4a19f3c |
63 | my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs); |
64 | # -or- |
996be9ee |
65 | my $schema1 = "My::Schema"; $schema1->connection(as above); |
074e81cd |
66 | |
996be9ee |
67 | =head1 DESCRIPTION |
074e81cd |
68 | |
fbd83464 |
69 | DBIx::Class::Schema::Loader automates the definition of a |
996be9ee |
70 | L<DBIx::Class::Schema> by scanning database table definitions and |
d65cda9e |
71 | setting up the columns, primary keys, and relationships. |
a78e3fed |
72 | |
d65cda9e |
73 | DBIx::Class::Schema::Loader currently supports only the DBI storage type. |
3fe9c5d9 |
74 | It has explicit support for L<DBD::Pg>, L<DBD::mysql>, L<DBD::DB2>, |
75 | L<DBD::SQLite>, and L<DBD::Oracle>. Other DBI drivers may function to |
76 | a greater or lesser degree with this loader, depending on how much of the |
77 | DBI spec they implement, and how standard their implementation is. |
78 | |
79 | Patches to make other DBDs work correctly welcome. |
a78e3fed |
80 | |
996be9ee |
81 | See L<DBIx::Class::Schema::Loader::DBI::Writing> for notes on writing |
82 | your own vendor-specific subclass for an unsupported DBD driver. |
a78e3fed |
83 | |
3fe9c5d9 |
84 | This module requires L<DBIx::Class> 0.07006 or later, and obsoletes |
996be9ee |
85 | the older L<DBIx::Class::Loader>. |
89ecd854 |
86 | |
996be9ee |
87 | This module is designed more to get you up and running quickly against |
88 | an existing database, or to be effective for simple situations, rather |
89 | than to be what you use in the long term for a complex database/project. |
89ecd854 |
90 | |
91 | That being said, transitioning your code from a Schema generated by this |
92 | module to one that doesn't use this module should be straightforward and |
59cfa251 |
93 | painless, so don't shy away from it just for fears of the transition down |
94 | the road. |
89ecd854 |
95 | |
a78e3fed |
96 | =head1 METHODS |
97 | |
29ddb54c |
98 | =head2 loader_class |
99 | |
530e0bf6 |
100 | =over 4 |
101 | |
102 | =item Argument: $loader_class |
103 | |
104 | =back |
105 | |
29ddb54c |
106 | Set the loader class to be instantiated when L</connection> is called. |
107 | If the classname starts with "::", "DBIx::Class::Schema::Loader" is |
108 | prepended. Defaults to L<DBIx::Class::Schema/storage_type> (which must |
109 | start with "::" when using L<DBIx::Class::Schema::Loader>). |
110 | |
111 | This is mostly useful for subclassing existing loaders or in conjunction |
112 | with L</dump_to_dir>. |
113 | |
996be9ee |
114 | =head2 loader_options |
a78e3fed |
115 | |
530e0bf6 |
116 | =over 4 |
117 | |
118 | =item Argument: \%loader_options |
119 | |
120 | =back |
121 | |
996be9ee |
122 | Example in Synopsis above demonstrates a few common arguments. For |
123 | detailed information on all of the arguments, most of which are |
124 | only useful in fairly complex scenarios, see the |
125 | L<DBIx::Class::Schema::Loader::Base> documentation. |
a78e3fed |
126 | |
3fe9c5d9 |
127 | If you intend to use C<loader_options>, you must call |
128 | C<loader_options> before any connection is made, or embed the |
129 | C<loader_options> in the connection information itself as shown |
130 | below. Setting C<loader_options> after the connection has |
59cfa251 |
131 | already been made is useless. |
a78e3fed |
132 | |
996be9ee |
133 | =cut |
1031d4f6 |
134 | |
996be9ee |
135 | sub loader_options { |
136 | my $self = shift; |
137 | |
d65cda9e |
138 | my %args = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_; |
996be9ee |
139 | $self->_loader_args(\%args); |
996be9ee |
140 | |
141 | $self; |
142 | } |
143 | |
144 | sub _invoke_loader { |
145 | my $self = shift; |
146 | my $class = ref $self || $self; |
147 | |
59cfa251 |
148 | my $args = $self->_loader_args; |
149 | |
150 | # set up the schema/schema_class arguments |
151 | $args->{schema} = $self; |
152 | $args->{schema_class} = $class; |
153 | weaken($args->{schema}) if ref $self; |
154 | $args->{dump_directory} ||= $self->dump_to_dir; |
a0e0a56a |
155 | $args->{naming} = $self->naming if $self->naming; |
af6c2665 |
156 | |
996be9ee |
157 | # XXX this only works for relative storage_type, like ::DBI ... |
29ddb54c |
158 | my $impl = $self->loader_class |
3953cbee |
159 | || "DBIx::Class::Schema::Loader" . $self->storage_type; |
29ddb54c |
160 | $impl = "DBIx::Class::Schema::Loader${impl}" if $impl =~ /^::/; |
6ae3f335 |
161 | eval { $self->ensure_class_loaded($impl) }; |
162 | croak qq/Could not load storage_type loader "$impl": "$@"/ if $@; |
af6c2665 |
163 | |
b97c2c1e |
164 | $self->_loader($impl->new(%$args)); |
165 | $self->_loader->load; |
59cfa251 |
166 | $self->_loader_invoked(1); |
996be9ee |
167 | |
996be9ee |
168 | $self; |
169 | } |
170 | |
171 | =head2 connection |
172 | |
530e0bf6 |
173 | =over 4 |
174 | |
175 | =item Arguments: @args |
176 | |
177 | =item Return Value: $new_schema |
178 | |
179 | =back |
180 | |
181 | See L<DBIx::Class::Schema/connection> for basic usage. |
d65cda9e |
182 | |
29ddb54c |
183 | If the final argument is a hashref, and it contains the keys C<loader_options> |
184 | or C<loader_class>, those keys will be deleted, and their values value will be |
185 | used for the loader options or class, respectively, just as if set via the |
186 | L</loader_options> or L</loader_class> methods above. |
d65cda9e |
187 | |
188 | The actual auto-loading operation (the heart of this module) will be invoked |
189 | as soon as the connection information is defined. |
996be9ee |
190 | |
191 | =cut |
192 | |
193 | sub connection { |
d65cda9e |
194 | my $self = shift; |
195 | |
196 | if($_[-1] && ref $_[-1] eq 'HASH') { |
17ca645f |
197 | for my $option (qw/ loader_class loader_options result_base_class schema_base_class/) { |
29ddb54c |
198 | if(my $value = delete $_[-1]->{$option}) { |
199 | $self->$option($value); |
200 | } |
d65cda9e |
201 | } |
29ddb54c |
202 | pop @_ if !keys %{$_[-1]}; |
d65cda9e |
203 | } |
204 | |
205 | $self = $self->next::method(@_); |
996be9ee |
206 | |
207 | my $class = ref $self || $self; |
59cfa251 |
208 | if(!$class->_loader_invoked) { |
fa994d3c |
209 | $self->_invoke_loader |
210 | } |
996be9ee |
211 | |
212 | return $self; |
213 | } |
214 | |
215 | =head2 clone |
216 | |
530e0bf6 |
217 | See L<DBIx::Class::Schema/clone>. |
996be9ee |
218 | |
219 | =cut |
220 | |
221 | sub clone { |
222 | my $self = shift; |
223 | |
224 | my $clone = $self->next::method(@_); |
225 | |
fa994d3c |
226 | if($clone->_loader_args) { |
227 | $clone->_loader_args->{schema} = $clone; |
228 | weaken($clone->_loader_args->{schema}); |
229 | } |
996be9ee |
230 | |
231 | $clone; |
232 | } |
233 | |
234 | =head2 dump_to_dir |
235 | |
530e0bf6 |
236 | =over 4 |
237 | |
238 | =item Argument: $directory |
239 | |
240 | =back |
996be9ee |
241 | |
242 | Calling this as a class method on either L<DBIx::Class::Schema::Loader> |
707fb247 |
243 | or any derived schema class will cause all schemas to dump |
996be9ee |
244 | manual versions of themselves to the named directory when they are |
245 | loaded. In order to be effective, this must be set before defining a |
246 | connection on this schema class or any derived object (as the loading |
074e81cd |
247 | happens as soon as both a connection and loader_options are set, and |
248 | only once per class). |
996be9ee |
249 | |
250 | See L<DBIx::Class::Schema::Loader::Base/dump_directory> for more |
251 | details on the dumping mechanism. |
252 | |
253 | This can also be set at module import time via the import option |
254 | C<dump_to_dir:/foo/bar> to L<DBIx::Class::Schema::Loader>, where |
255 | C</foo/bar> is the target directory. |
256 | |
257 | Examples: |
258 | |
259 | # My::Schema isa DBIx::Class::Schema::Loader, and has connection info |
260 | # hardcoded in the class itself: |
261 | perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1 |
262 | |
263 | # Same, but no hard-coded connection, so we must provide one: |
264 | perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)' |
265 | |
266 | # Or as a class method, as long as you get it done *before* defining a |
267 | # connection on this schema class or any derived object: |
268 | use My::Schema; |
269 | My::Schema->dump_to_dir('/foo/bar'); |
270 | My::Schema->connection(........); |
271 | |
272 | # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all |
273 | # derived schemas |
274 | use My::Schema; |
275 | use My::OtherSchema; |
276 | DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar'); |
277 | My::Schema->connection(.......); |
278 | My::OtherSchema->connection(.......); |
279 | |
280 | # Another alternative to the above: |
281 | use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |; |
282 | use My::Schema; |
283 | use My::OtherSchema; |
284 | My::Schema->connection(.......); |
285 | My::OtherSchema->connection(.......); |
286 | |
287 | =cut |
288 | |
289 | sub import { |
290 | my $self = shift; |
a8d229ff |
291 | |
996be9ee |
292 | return if !@_; |
a8d229ff |
293 | |
294 | my $cpkg = (caller)[0]; |
295 | |
996be9ee |
296 | foreach my $opt (@_) { |
297 | if($opt =~ m{^dump_to_dir:(.*)$}) { |
298 | $self->dump_to_dir($1) |
299 | } |
300 | elsif($opt eq 'make_schema_at') { |
301 | no strict 'refs'; |
996be9ee |
302 | *{"${cpkg}::make_schema_at"} = \&make_schema_at; |
303 | } |
a8d229ff |
304 | elsif($opt eq 'naming') { |
305 | no strict 'refs'; |
306 | *{"${cpkg}::naming"} = sub { $self->naming(@_) }; |
307 | } |
996be9ee |
308 | } |
309 | } |
310 | |
311 | =head2 make_schema_at |
312 | |
530e0bf6 |
313 | =over 4 |
314 | |
707fb247 |
315 | =item Arguments: $schema_class_name, \%loader_options, \@connect_info |
530e0bf6 |
316 | |
707fb247 |
317 | =item Return Value: $schema_class_name |
530e0bf6 |
318 | |
319 | =back |
320 | |
707fb247 |
321 | This function creates a DBIx::Class schema from an existing RDBMS |
322 | schema. With the C<dump_directory> option, generates a set of |
323 | DBIx::Class classes from an existing database schema read from the |
324 | given dsn. Without a C<dump_directory>, creates schema classes in |
325 | memory at runtime without generating on-disk class files. |
996be9ee |
326 | |
707fb247 |
327 | For a complete list of supported loader_options, see |
328 | L<DBIx::Class::Schema::Loader::Base> |
483987b9 |
329 | |
707fb247 |
330 | This function can be imported in the usual way, as illustrated in |
331 | these Examples: |
996be9ee |
332 | |
5223f24a |
333 | # Simple example, creates as a new class 'New::Schema::Name' in |
334 | # memory in the running perl interpreter. |
996be9ee |
335 | use DBIx::Class::Schema::Loader qw/ make_schema_at /; |
336 | make_schema_at( |
337 | 'New::Schema::Name', |
59cfa251 |
338 | { debug => 1 }, |
996be9ee |
339 | [ 'dbi:Pg:dbname="foo"','postgres' ], |
340 | ); |
341 | |
707fb247 |
342 | # Inside a script, specifying a dump directory in which to write |
343 | # class files |
996be9ee |
344 | use DBIx::Class::Schema::Loader qw/ make_schema_at /; |
345 | make_schema_at( |
346 | 'New::Schema::Name', |
59cfa251 |
347 | { debug => 1, dump_directory => './lib' }, |
996be9ee |
348 | [ 'dbi:Pg:dbname="foo"','postgres' ], |
349 | ); |
350 | |
351 | =cut |
352 | |
353 | sub make_schema_at { |
354 | my ($target, $opts, $connect_info) = @_; |
355 | |
483987b9 |
356 | { |
357 | no strict 'refs'; |
358 | @{$target . '::ISA'} = qw/DBIx::Class::Schema::Loader/; |
359 | } |
360 | |
361 | $target->loader_options($opts); |
362 | $target->connection(@$connect_info); |
996be9ee |
363 | } |
364 | |
b97c2c1e |
365 | =head2 rescan |
366 | |
530e0bf6 |
367 | =over 4 |
368 | |
369 | =item Return Value: @new_monikers |
370 | |
371 | =back |
372 | |
b97c2c1e |
373 | Re-scans the database for newly added tables since the initial |
374 | load, and adds them to the schema at runtime, including relationships, |
375 | etc. Does not process drops or changes. |
376 | |
a60b5b8d |
377 | Returns a list of the new monikers added. |
378 | |
b97c2c1e |
379 | =cut |
380 | |
a60b5b8d |
381 | sub rescan { my $self = shift; $self->_loader->rescan($self) } |
b97c2c1e |
382 | |
a8d229ff |
383 | =head2 naming |
384 | |
385 | =over 4 |
386 | |
387 | =item Arguments: \%opts | $ver |
388 | |
389 | =back |
390 | |
391 | Controls the naming options for backward compatibility, see |
392 | L<DBIx::Class::Schema::Loader::Base/naming> for details. |
393 | |
394 | To upgrade a dynamic schema, use: |
395 | |
396 | __PACKAGE__->naming('current'); |
397 | |
398 | Can be imported into your dump script and called as a function as well: |
399 | |
400 | naming('v4'); |
996be9ee |
401 | |
996be9ee |
402 | =head1 KNOWN ISSUES |
403 | |
404 | =head2 Multiple Database Schemas |
405 | |
406 | Currently the loader is limited to working within a single schema |
707fb247 |
407 | (using the underlying RDBMS's definition of "schema"). If you have a |
408 | multi-schema database with inter-schema relationships (which is easy |
409 | to do in PostgreSQL or DB2 for instance), you currently can only |
410 | automatically load the tables of one schema, and relationships to |
411 | tables in other schemas will be silently ignored. |
996be9ee |
412 | |
413 | At some point in the future, an intelligent way around this might be |
414 | devised, probably by allowing the C<db_schema> option to be an |
d65cda9e |
415 | arrayref of schemas to load. |
89ecd854 |
416 | |
996be9ee |
417 | In "normal" L<DBIx::Class::Schema> usage, manually-defined |
418 | source classes and relationships have no problems crossing vendor schemas. |
89ecd854 |
419 | |
be80bba7 |
420 | =head1 ACKNOWLEDGEMENTS |
a78e3fed |
421 | |
be80bba7 |
422 | Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent |
423 | in a bug report or suggestion. |
fbd83464 |
424 | |
8a6b44ef |
425 | Based on L<DBIx::Class::Loader> by Sebastian Riedel |
a78e3fed |
426 | |
427 | Based upon the work of IKEBE Tomohiro |
428 | |
be80bba7 |
429 | =head1 AUTHOR |
a78e3fed |
430 | |
be80bba7 |
431 | blblack: Brandon Black <blblack@gmail.com> |
432 | |
433 | =head1 CONTRIBUTORS |
434 | |
435 | ilmarii: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> |
436 | |
437 | arcanez: Justin Hunter <justin.d.hunter@gmail.com> |
438 | |
439 | ash: Ash Berlin <ash@cpan.org> |
440 | |
441 | Caelum: Rafael Kitover <rkitover@cpan.org> |
442 | |
443 | TSUNODA Kazuya <drk@drk7.jp> |
444 | |
445 | Robert Bohne <rbo@openserv.org> |
446 | |
1f625792 |
447 | ribasushi: Peter Rabbitson <rabbit+dbic@rabbit.us> |
448 | |
fdd8ff16 |
449 | gugu: Andrey Kostenko <a.kostenko@rambler-co.ru> |
450 | |
be80bba7 |
451 | ... and lots of other folks. If we forgot you, please write the current |
452 | maintainer or RT. |
a78e3fed |
453 | |
9cc8e7e1 |
454 | =head1 COPYRIGHT & LICENSE |
455 | |
456 | Copyright (c) 2006 - 2009 by the aforementioned |
457 | L<DBIx::Class::Schema::Loader/AUTHOR> and |
458 | L<DBIx::Class::Schema::Loader/CONTRIBUTORS>. |
a78e3fed |
459 | |
460 | This library is free software; you can redistribute it and/or modify it under |
461 | the same terms as Perl itself. |
462 | |
463 | =head1 SEE ALSO |
464 | |
996be9ee |
465 | L<DBIx::Class>, L<DBIx::Class::Manual::ExampleSchema> |
a78e3fed |
466 | |
467 | =cut |
468 | |
469 | 1; |