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