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 |
52 | Set the loader class to be instantiated when "connection" is called. If |
53 | the classname starts with "::", "DBIx::Class::Schema::Loader" is |
54 | prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must |
55 | start with "::" when using DBIx::Class::Schema::Loader). |
56 | |
57 | This is mostly useful for subclassing existing loaders or in conjunction |
58 | with "dump_to_dir". |
59 | |
3fe9c5d9 |
60 | loader_options |
61 | Example in Synopsis above demonstrates a few common arguments. For |
62 | detailed information on all of the arguments, most of which are only |
63 | useful in fairly complex scenarios, see the |
64 | DBIx::Class::Schema::Loader::Base documentation. |
65 | |
66 | If you intend to use "loader_options", you must call "loader_options" |
67 | before any connection is made, or embed the "loader_options" in the |
68 | connection information itself as shown below. Setting "loader_options" |
69 | after the connection has already been made is useless. |
70 | |
71 | connection |
72 | See DBIx::Class::Schema for basic usage. |
73 | |
9acd645d |
74 | If the final argument is a hashref, and it contains the keys |
75 | "loader_options" or "loader_class", those keys will be deleted, and |
76 | their values value will be used for the loader options or class, |
77 | respectively, just as if set via the "loader_options" or "loader_class" |
78 | methods above. |
3fe9c5d9 |
79 | |
80 | The actual auto-loading operation (the heart of this module) will be |
81 | invoked as soon as the connection information is defined. |
82 | |
83 | clone |
84 | See DBIx::Class::Schema. |
85 | |
86 | dump_to_dir |
87 | Argument: directory name. |
88 | |
89 | Calling this as a class method on either DBIx::Class::Schema::Loader or |
90 | any derived schema class will cause all affected schemas to dump manual |
91 | versions of themselves to the named directory when they are loaded. In |
92 | order to be effective, this must be set before defining a connection on |
93 | this schema class or any derived object (as the loading happens as soon |
94 | as both a connection and loader_options are set, and only once per |
95 | class). |
96 | |
97 | See "dump_directory" in DBIx::Class::Schema::Loader::Base for more |
98 | details on the dumping mechanism. |
99 | |
100 | This can also be set at module import time via the import option |
101 | "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar" |
102 | is the target directory. |
103 | |
104 | Examples: |
105 | |
106 | # My::Schema isa DBIx::Class::Schema::Loader, and has connection info |
107 | # hardcoded in the class itself: |
108 | perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1 |
109 | |
110 | # Same, but no hard-coded connection, so we must provide one: |
111 | perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)' |
112 | |
113 | # Or as a class method, as long as you get it done *before* defining a |
114 | # connection on this schema class or any derived object: |
115 | use My::Schema; |
116 | My::Schema->dump_to_dir('/foo/bar'); |
117 | My::Schema->connection(........); |
118 | |
119 | # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all |
120 | # derived schemas |
121 | use My::Schema; |
122 | use My::OtherSchema; |
123 | DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar'); |
124 | My::Schema->connection(.......); |
125 | My::OtherSchema->connection(.......); |
126 | |
127 | # Another alternative to the above: |
128 | use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |; |
129 | use My::Schema; |
130 | use My::OtherSchema; |
131 | My::Schema->connection(.......); |
132 | My::OtherSchema->connection(.......); |
133 | |
134 | make_schema_at |
135 | This simple function allows one to create a Loader-based schema |
136 | in-memory on the fly without any on-disk class files of any kind. When |
137 | used with the "dump_directory" option, you can use this to generate a |
138 | rough draft manual schema from a dsn without the intermediate step of |
139 | creating a physical Loader-based schema class. |
140 | |
141 | The return value is the input class name. |
142 | |
143 | This function can be exported/imported by the normal means, as |
144 | illustrated in these Examples: |
145 | |
146 | # Simple example, creates as a new class 'New::Schema::Name' in |
147 | # memory in the running perl interpreter. |
148 | use DBIx::Class::Schema::Loader qw/ make_schema_at /; |
149 | make_schema_at( |
150 | 'New::Schema::Name', |
151 | { debug => 1 }, |
152 | [ 'dbi:Pg:dbname="foo"','postgres' ], |
153 | ); |
154 | |
155 | # Complex: dump loaded schema to disk, all from the commandline: |
156 | 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" ])' |
157 | |
158 | # Same, but inside a script, and using a different way to specify the |
159 | # dump directory: |
160 | use DBIx::Class::Schema::Loader qw/ make_schema_at /; |
161 | make_schema_at( |
162 | 'New::Schema::Name', |
163 | { debug => 1, dump_directory => './lib' }, |
164 | [ 'dbi:Pg:dbname="foo"','postgres' ], |
165 | ); |
166 | |
167 | rescan |
168 | Re-scans the database for newly added tables since the initial load, and |
169 | adds them to the schema at runtime, including relationships, etc. Does |
170 | not process drops or changes. |
171 | |
172 | Returns a list of the new monikers added. |
173 | |
174 | EXAMPLE |
175 | Using the example in DBIx::Class::Manual::ExampleSchema as a basis |
176 | replace the DB::Main with the following code: |
177 | |
178 | package DB::Main; |
179 | |
180 | use base qw/DBIx::Class::Schema::Loader/; |
181 | |
182 | __PACKAGE__->loader_options( |
183 | debug => 1, |
184 | ); |
185 | __PACKAGE__->connection('dbi:SQLite:example.db'); |
186 | |
187 | 1; |
188 | |
189 | and remove the Main directory tree (optional). Every thing else should |
190 | work the same |
191 | |
192 | KNOWN ISSUES |
193 | Multiple Database Schemas |
194 | Currently the loader is limited to working within a single schema (using |
195 | the database vendors' definition of "schema"). If you have a |
196 | multi-schema database with inter-schema relationships (which is easy to |
197 | do in PostgreSQL or DB2 for instance), you only get to automatically |
198 | load the tables of one schema, and any relationships to tables in other |
199 | schemas will be silently ignored. |
200 | |
201 | At some point in the future, an intelligent way around this might be |
202 | devised, probably by allowing the "db_schema" option to be an arrayref |
203 | of schemas to load. |
204 | |
205 | In "normal" DBIx::Class::Schema usage, manually-defined source classes |
206 | and relationships have no problems crossing vendor schemas. |
207 | |
208 | AUTHOR |
209 | Brandon Black, "blblack@gmail.com" |
210 | |
211 | Based on DBIx::Class::Loader by Sebastian Riedel |
212 | |
213 | Based upon the work of IKEBE Tomohiro |
214 | |
215 | THANK YOU |
216 | Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent |
217 | in a bug report or suggestion. |
218 | |
219 | LICENSE |
220 | This library is free software; you can redistribute it and/or modify it |
221 | under the same terms as Perl itself. |
222 | |
223 | SEE ALSO |
224 | DBIx::Class, DBIx::Class::Manual::ExampleSchema |
225 | |