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