Commit | Line | Data |
3fe9c5d9 |
1 | NAME |
2 | DBIx::Class::Schema::Loader - Dynamic definition of a |
3 | DBIx::Class::Schema |
4 | |
5 | SYNOPSIS |
6 | package My::Schema; |
7 | use base qw/DBIx::Class::Schema::Loader/; |
8 | |
9 | __PACKAGE__->loader_options( |
10 | constraint => '^foo.*', |
11 | # debug => 1, |
12 | ); |
13 | |
14 | # in seperate application code ... |
15 | |
16 | use My::Schema; |
17 | |
18 | my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs); |
19 | # -or- |
20 | my $schema1 = "My::Schema"; $schema1->connection(as above); |
21 | |
22 | DESCRIPTION |
23 | DBIx::Class::Schema::Loader automates the definition of a |
24 | DBIx::Class::Schema by scanning database table definitions and setting |
25 | up the columns, primary keys, and relationships. |
26 | |
27 | DBIx::Class::Schema::Loader currently supports only the DBI storage |
28 | type. It has explicit support for DBD::Pg, DBD::mysql, DBD::DB2, |
29 | DBD::SQLite, and DBD::Oracle. Other DBI drivers may function to a |
30 | greater or lesser degree with this loader, depending on how much of the |
31 | DBI spec they implement, and how standard their implementation is. |
32 | |
33 | Patches to make other DBDs work correctly welcome. |
34 | |
35 | See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your |
36 | own vendor-specific subclass for an unsupported DBD driver. |
37 | |
38 | This module requires DBIx::Class 0.07006 or later, and obsoletes the |
39 | older DBIx::Class::Loader. |
40 | |
41 | This module is designed more to get you up and running quickly against |
42 | an existing database, or to be effective for simple situations, rather |
43 | than to be what you use in the long term for a complex database/project. |
44 | |
45 | That being said, transitioning your code from a Schema generated by this |
46 | module to one that doesn't use this module should be straightforward and |
47 | painless, so don't shy away from it just for fears of the transition |
48 | down the road. |
49 | |
50 | METHODS |
9acd645d |
51 | loader_class |
d6cca7c2 |
52 | Argument: $loader_class |
53 | |
9acd645d |
54 | Set the loader class to be instantiated when "connection" is called. If |
55 | the classname starts with "::", "DBIx::Class::Schema::Loader" is |
56 | prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must |
57 | start with "::" when using DBIx::Class::Schema::Loader). |
58 | |
59 | This is mostly useful for subclassing existing loaders or in conjunction |
60 | with "dump_to_dir". |
61 | |
3fe9c5d9 |
62 | loader_options |
d6cca7c2 |
63 | Argument: \%loader_options |
64 | |
3fe9c5d9 |
65 | Example in Synopsis above demonstrates a few common arguments. For |
66 | detailed information on all of the arguments, most of which are only |
67 | useful in fairly complex scenarios, see the |
68 | DBIx::Class::Schema::Loader::Base documentation. |
69 | |
70 | If you intend to use "loader_options", you must call "loader_options" |
71 | before any connection is made, or embed the "loader_options" in the |
72 | connection information itself as shown below. Setting "loader_options" |
73 | after the connection has already been made is useless. |
74 | |
75 | connection |
d6cca7c2 |
76 | Arguments: @args |
77 | Return Value: $new_schema |
78 | |
79 | See "connection" in DBIx::Class::Schema for basic usage. |
3fe9c5d9 |
80 | |
9acd645d |
81 | If the final argument is a hashref, and it contains the keys |
82 | "loader_options" or "loader_class", those keys will be deleted, and |
83 | their values value will be used for the loader options or class, |
84 | respectively, just as if set via the "loader_options" or "loader_class" |
85 | methods above. |
3fe9c5d9 |
86 | |
87 | The actual auto-loading operation (the heart of this module) will be |
88 | invoked as soon as the connection information is defined. |
89 | |
90 | clone |
d6cca7c2 |
91 | See "clone" in DBIx::Class::Schema. |
3fe9c5d9 |
92 | |
93 | dump_to_dir |
d6cca7c2 |
94 | Argument: $directory |
3fe9c5d9 |
95 | |
96 | Calling this as a class method on either DBIx::Class::Schema::Loader or |
97 | any derived schema class will cause all affected schemas to dump manual |
98 | versions of themselves to the named directory when they are loaded. In |
99 | order to be effective, this must be set before defining a connection on |
100 | this schema class or any derived object (as the loading happens as soon |
101 | as both a connection and loader_options are set, and only once per |
102 | class). |
103 | |
104 | See "dump_directory" in DBIx::Class::Schema::Loader::Base for more |
105 | details on the dumping mechanism. |
106 | |
107 | This can also be set at module import time via the import option |
108 | "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar" |
109 | is the target directory. |
110 | |
111 | Examples: |
112 | |
113 | # My::Schema isa DBIx::Class::Schema::Loader, and has connection info |
114 | # hardcoded in the class itself: |
115 | perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1 |
116 | |
117 | # Same, but no hard-coded connection, so we must provide one: |
118 | perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)' |
119 | |
120 | # Or as a class method, as long as you get it done *before* defining a |
121 | # connection on this schema class or any derived object: |
122 | use My::Schema; |
123 | My::Schema->dump_to_dir('/foo/bar'); |
124 | My::Schema->connection(........); |
125 | |
126 | # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all |
127 | # derived schemas |
128 | use My::Schema; |
129 | use My::OtherSchema; |
130 | DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar'); |
131 | My::Schema->connection(.......); |
132 | My::OtherSchema->connection(.......); |
133 | |
134 | # Another alternative to the above: |
135 | use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |; |
136 | use My::Schema; |
137 | use My::OtherSchema; |
138 | My::Schema->connection(.......); |
139 | My::OtherSchema->connection(.......); |
140 | |
141 | make_schema_at |
d6cca7c2 |
142 | Arguments: $schema_name, \%loader_options, \@connect_info |
143 | Return Value: $schema_name |
144 | |
3fe9c5d9 |
145 | This simple function allows one to create a Loader-based schema |
146 | in-memory on the fly without any on-disk class files of any kind. When |
147 | used with the "dump_directory" option, you can use this to generate a |
148 | rough draft manual schema from a dsn without the intermediate step of |
149 | creating a physical Loader-based schema class. |
150 | |
151 | The return value is the input class name. |
152 | |
153 | This function can be exported/imported by the normal means, as |
154 | illustrated in these Examples: |
155 | |
156 | # Simple example, creates as a new class 'New::Schema::Name' in |
157 | # memory in the running perl interpreter. |
158 | use DBIx::Class::Schema::Loader qw/ make_schema_at /; |
159 | make_schema_at( |
160 | 'New::Schema::Name', |
161 | { debug => 1 }, |
162 | [ 'dbi:Pg:dbname="foo"','postgres' ], |
163 | ); |
164 | |
165 | # Complex: dump loaded schema to disk, all from the commandline: |
166 | perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib -e 'make_schema_at("New::Schema::Name", { debug => 1 }, [ "dbi:Pg:dbname=foo","postgres" ])' |
167 | |
168 | # Same, but inside a script, and using a different way to specify the |
169 | # dump directory: |
170 | use DBIx::Class::Schema::Loader qw/ make_schema_at /; |
171 | make_schema_at( |
172 | 'New::Schema::Name', |
173 | { debug => 1, dump_directory => './lib' }, |
174 | [ 'dbi:Pg:dbname="foo"','postgres' ], |
175 | ); |
176 | |
177 | rescan |
d6cca7c2 |
178 | Return Value: @new_monikers |
179 | |
3fe9c5d9 |
180 | Re-scans the database for newly added tables since the initial load, and |
181 | adds them to the schema at runtime, including relationships, etc. Does |
182 | not process drops or changes. |
183 | |
184 | Returns a list of the new monikers added. |
185 | |
186 | EXAMPLE |
187 | Using the example in DBIx::Class::Manual::ExampleSchema as a basis |
188 | replace the DB::Main with the following code: |
189 | |
190 | package DB::Main; |
191 | |
192 | use base qw/DBIx::Class::Schema::Loader/; |
193 | |
194 | __PACKAGE__->loader_options( |
195 | debug => 1, |
196 | ); |
197 | __PACKAGE__->connection('dbi:SQLite:example.db'); |
198 | |
199 | 1; |
200 | |
201 | and remove the Main directory tree (optional). Every thing else should |
202 | work the same |
203 | |
204 | KNOWN ISSUES |
205 | Multiple Database Schemas |
206 | Currently the loader is limited to working within a single schema (using |
207 | the database vendors' definition of "schema"). If you have a |
208 | multi-schema database with inter-schema relationships (which is easy to |
209 | do in PostgreSQL or DB2 for instance), you only get to automatically |
210 | load the tables of one schema, and any relationships to tables in other |
211 | schemas will be silently ignored. |
212 | |
213 | At some point in the future, an intelligent way around this might be |
214 | devised, probably by allowing the "db_schema" option to be an arrayref |
215 | of schemas to load. |
216 | |
217 | In "normal" DBIx::Class::Schema usage, manually-defined source classes |
218 | and relationships have no problems crossing vendor schemas. |
219 | |
220 | AUTHOR |
221 | Brandon Black, "blblack@gmail.com" |
222 | |
223 | Based on DBIx::Class::Loader by Sebastian Riedel |
224 | |
225 | Based upon the work of IKEBE Tomohiro |
226 | |
227 | THANK YOU |
228 | Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent |
229 | in a bug report or suggestion. |
230 | |
231 | LICENSE |
232 | This library is free software; you can redistribute it and/or modify it |
233 | under the same terms as Perl itself. |
234 | |
235 | SEE ALSO |
236 | DBIx::Class, DBIx::Class::Manual::ExampleSchema |
237 | |