1NAME 2 DBIx::Class::Schema::Loader - Dynamic definition of a 3 DBIx::Class::Schema 4 5SYNOPSIS 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 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 39 #### in application code elsewhere: 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 47DESCRIPTION 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, DBD::Sybase (for Sybase ASE and MSSSQL), DBD::ODBC (for 55 MSSQL) and DBD::Oracle. Other DBI drivers may function to a greater or 56 lesser degree with this loader, depending on how much of the DBI spec 57 they implement, and how standard their implementation is. 58 59 Patches to make other DBDs work correctly welcome. 60 61 See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your 62 own vendor-specific subclass for an unsupported DBD driver. 63 64 This module requires DBIx::Class 0.07006 or later, and obsoletes the 65 older DBIx::Class::Loader. 66 67 This module is designed more to get you up and running quickly against 68 an existing database, or to be effective for simple situations, rather 69 than to be what you use in the long term for a complex database/project. 70 71 That being said, transitioning your code from a Schema generated by this 72 module to one that doesn't use this module should be straightforward and 73 painless, so don't shy away from it just for fears of the transition 74 down the road. 75 76METHODS 77 loader_class 78 Argument: $loader_class 79 80 Set the loader class to be instantiated when "connection" is called. If 81 the classname starts with "::", "DBIx::Class::Schema::Loader" is 82 prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must 83 start with "::" when using DBIx::Class::Schema::Loader). 84 85 This is mostly useful for subclassing existing loaders or in conjunction 86 with "dump_to_dir". 87 88 loader_options 89 Argument: \%loader_options 90 91 Example in Synopsis above demonstrates a few common arguments. For 92 detailed information on all of the arguments, most of which are only 93 useful in fairly complex scenarios, see the 94 DBIx::Class::Schema::Loader::Base documentation. 95 96 If you intend to use "loader_options", you must call "loader_options" 97 before any connection is made, or embed the "loader_options" in the 98 connection information itself as shown below. Setting "loader_options" 99 after the connection has already been made is useless. 100 101 connection 102 Arguments: @args 103 Return Value: $new_schema 104 105 See "connection" in DBIx::Class::Schema for basic usage. 106 107 If the final argument is a hashref, and it contains the keys 108 "loader_options" or "loader_class", those keys will be deleted, and 109 their values value will be used for the loader options or class, 110 respectively, just as if set via the "loader_options" or "loader_class" 111 methods above. 112 113 The actual auto-loading operation (the heart of this module) will be 114 invoked as soon as the connection information is defined. 115 116 clone 117 See "clone" in DBIx::Class::Schema. 118 119 dump_to_dir 120 Argument: $directory 121 122 Calling this as a class method on either DBIx::Class::Schema::Loader or 123 any derived schema class will cause all schemas to dump manual versions 124 of themselves to the named directory when they are loaded. In order to 125 be effective, this must be set before defining a connection on this 126 schema class or any derived object (as the loading happens as soon as 127 both a connection and loader_options are set, and only once per class). 128 129 See "dump_directory" in DBIx::Class::Schema::Loader::Base for more 130 details on the dumping mechanism. 131 132 This can also be set at module import time via the import option 133 "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar" 134 is the target directory. 135 136 Examples: 137 138 # My::Schema isa DBIx::Class::Schema::Loader, and has connection info 139 # hardcoded in the class itself: 140 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1 141 142 # Same, but no hard-coded connection, so we must provide one: 143 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)' 144 145 # Or as a class method, as long as you get it done *before* defining a 146 # connection on this schema class or any derived object: 147 use My::Schema; 148 My::Schema->dump_to_dir('/foo/bar'); 149 My::Schema->connection(........); 150 151 # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all 152 # derived schemas 153 use My::Schema; 154 use My::OtherSchema; 155 DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar'); 156 My::Schema->connection(.......); 157 My::OtherSchema->connection(.......); 158 159 # Another alternative to the above: 160 use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |; 161 use My::Schema; 162 use My::OtherSchema; 163 My::Schema->connection(.......); 164 My::OtherSchema->connection(.......); 165 166 make_schema_at 167 Arguments: $schema_class_name, \%loader_options, \@connect_info 168 Return Value: $schema_class_name 169 170 This function creates a DBIx::Class schema from an existing RDBMS 171 schema. With the "dump_directory" option, generates a set of DBIx::Class 172 classes from an existing database schema read from the given dsn. 173 Without a "dump_directory", creates schema classes in memory at runtime 174 without generating on-disk class files. 175 176 For a complete list of supported loader_options, see 177 DBIx::Class::Schema::Loader::Base 178 179 This function can be imported in the usual way, as illustrated in these 180 Examples: 181 182 # Simple example, creates as a new class 'New::Schema::Name' in 183 # memory in the running perl interpreter. 184 use DBIx::Class::Schema::Loader qw/ make_schema_at /; 185 make_schema_at( 186 'New::Schema::Name', 187 { debug => 1 }, 188 [ 'dbi:Pg:dbname="foo"','postgres' ], 189 ); 190 191 # Inside a script, specifying a dump directory in which to write 192 # class files 193 use DBIx::Class::Schema::Loader qw/ make_schema_at /; 194 make_schema_at( 195 'New::Schema::Name', 196 { debug => 1, dump_directory => './lib' }, 197 [ 'dbi:Pg:dbname="foo"','postgres' ], 198 ); 199 200 rescan 201 Return Value: @new_monikers 202 203 Re-scans the database for newly added tables since the initial load, and 204 adds them to the schema at runtime, including relationships, etc. Does 205 not process drops or changes. 206 207 Returns a list of the new monikers added. 208 209 naming 210 Arguments: \%opts | $ver 211 212 Controls the naming options for backward compatibility, see "naming" in 213 DBIx::Class::Schema::Loader::Base for details. 214 215 To upgrade a dynamic schema, use: 216 217 __PACKAGE__->naming('current'); 218 219 Can be imported into your dump script and called as a function as well: 220 221 naming('v4'); 222 223 use_namespaces 224 Arguments: 1|0 225 226 Controls the use_namespaces options for backward compatibility, see 227 "use_namespaces" in DBIx::Class::Schema::Loader::Base for details. 228 229 To upgrade a dynamic schema, use: 230 231 __PACKAGE__->use_namespaces(1); 232 233 Can be imported into your dump script and called as a function as well: 234 235 use_namespaces(1); 236 237KNOWN ISSUES 238 Multiple Database Schemas 239 Currently the loader is limited to working within a single schema (using 240 the underlying RDBMS's definition of "schema"). If you have a 241 multi-schema database with inter-schema relationships (which is easy to 242 do in PostgreSQL or DB2 for instance), you currently can only 243 automatically load the tables of one schema, and relationships to tables 244 in other schemas will be silently ignored. 245 246 At some point in the future, an intelligent way around this might be 247 devised, probably by allowing the "db_schema" option to be an arrayref 248 of schemas to load. 249 250 In "normal" DBIx::Class::Schema usage, manually-defined source classes 251 and relationships have no problems crossing vendor schemas. 252 253ACKNOWLEDGEMENTS 254 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent 255 in a bug report or suggestion. 256 257 Based on DBIx::Class::Loader by Sebastian Riedel 258 259 Based upon the work of IKEBE Tomohiro 260 261AUTHOR 262 blblack: Brandon Black <blblack@gmail.com> 263 264CONTRIBUTORS 265 ilmari: Dagfinn Ilmari Manns�ker <ilmari@ilmari.org> 266 267 arcanez: Justin Hunter <justin.d.hunter@gmail.com> 268 269 ash: Ash Berlin <ash@cpan.org> 270 271 Caelum: Rafael Kitover <rkitover@cpan.org> 272 273 TSUNODA Kazuya <drk@drk7.jp> 274 275 rbo: Robert Bohne <rbo@cpan.org> 276 277 ribasushi: Peter Rabbitson <ribasushi@cpan.org> 278 279 gugu: Andrey Kostenko <a.kostenko@rambler-co.ru> 280 281 jhannah: Jay Hannah <jay@jays.net> 282 283 rbuels: Robert Buels <rmb32@cornell.edu> 284 285 timbunce: Tim Bunce <timb@cpan.org> 286 287 mst: Matt S. Trout <mst@shadowcatsystems.co.uk> 288 289 kane: Jos Boumans <kane@cpan.org> 290 291 waawaamilk: Nigel McNie <nigel@mcnie.name> 292 293 acmoore: Andrew Moore <amoore@cpan.org> 294 295 bphillips: Brian Phillips <bphillips@cpan.org> 296 297 schwern: Michael G. Schwern <mschwern@cpan.org> 298 299 hobbs: Andrew Rodland <arodland@cpan.org> 300 301 ... and lots of other folks. If we forgot you, please write the current 302 maintainer or RT. 303 304COPYRIGHT & LICENSE 305 Copyright (c) 2006 - 2009 by the aforementioned "AUTHOR" in 306 DBIx::Class::Schema::Loader and "CONTRIBUTORS" in 307 DBIx::Class::Schema::Loader. 308 309 This library is free software; you can redistribute it and/or modify it 310 under the same terms as Perl itself. 311 312SEE ALSO 313 DBIx::Class, DBIx::Class::Manual::ExampleSchema 314 315