1NAME 2 DBIx::Class::Schema::Loader - Create a DBIx::Class::Schema based on a 3 database 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 { loader_class => 'MyLoader' } # optionally 17 ], 18 ); 19 20 # from the command line or a shell script with dbicdump (distributed 21 # with this module). Do `perldoc dbicdump` for usage. 22 dbicdump -o dump_directory=./lib \ 23 -o components='["InflateColumn::DateTime"]' \ 24 -o debug=1 \ 25 My::Schema \ 26 'dbi:Pg:dbname=foo' \ 27 myuser \ 28 mypassword 29 30 ### or generate and load classes at runtime 31 # note: this technique is not recommended 32 # for use in production code 33 34 package My::Schema; 35 use base qw/DBIx::Class::Schema::Loader/; 36 37 __PACKAGE__->loader_options( 38 constraint => '^foo.*', 39 # debug => 1, 40 ); 41 42 #### in application code elsewhere: 43 44 use My::Schema; 45 46 my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs); 47 # -or- 48 my $schema1 = "My::Schema"; $schema1->connection(as above); 49 50DESCRIPTION 51 DBIx::Class::Schema::Loader automates the definition of a 52 DBIx::Class::Schema by scanning database table definitions and setting 53 up the columns, primary keys, unique constraints and relationships. 54 55 See dbicdump for the "dbicdump" utility. 56 57 DBIx::Class::Schema::Loader currently supports only the DBI storage 58 type. It has explicit support for DBD::Pg, DBD::mysql, DBD::DB2, 59 DBD::Firebird, DBD::InterBase, DBD::Informix, DBD::SQLAnywhere, 60 DBD::SQLite, DBD::Sybase (for Sybase ASE and MSSSQL), DBD::ODBC (for 61 MSSQL, MSAccess, Firebird and SQL Anywhere) DBD::ADO (for MSSQL and 62 MSAccess) and DBD::Oracle. Other DBI drivers may function to a greater 63 or lesser degree with this loader, depending on how much of the DBI spec 64 they implement, and how standard their implementation is. 65 66 Patches to make other DBDs work correctly welcome. 67 68 See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your 69 own vendor-specific subclass for an unsupported DBD driver. 70 71 This module requires DBIx::Class 0.08127 or later, and obsoletes the 72 older DBIx::Class::Loader. 73 74 See DBIx::Class::Schema::Loader::Base for available options. 75 76METHODS 77 loader 78 The loader object, as class data on your Schema. For methods available 79 see DBIx::Class::Schema::Loader::Base and 80 DBIx::Class::Schema::Loader::DBI. 81 82 loader_class 83 Argument: $loader_class 84 85 Set the loader class to be instantiated when "connection" is called. If 86 the classname starts with "::", "DBIx::Class::Schema::Loader" is 87 prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must 88 start with "::" when using DBIx::Class::Schema::Loader). 89 90 This is mostly useful for subclassing existing loaders or in conjunction 91 with "dump_to_dir". 92 93 loader_options 94 Argument: \%loader_options 95 96 Example in Synopsis above demonstrates a few common arguments. For 97 detailed information on all of the arguments, most of which are only 98 useful in fairly complex scenarios, see the 99 DBIx::Class::Schema::Loader::Base documentation. 100 101 If you intend to use "loader_options", you must call "loader_options" 102 before any connection is made, or embed the "loader_options" in the 103 connection information itself as shown below. Setting "loader_options" 104 after the connection has already been made is useless. 105 106 connection 107 Arguments: @args 108 Return Value: $new_schema 109 110 See "connection" in DBIx::Class::Schema for basic usage. 111 112 If the final argument is a hashref, and it contains the keys 113 "loader_options" or "loader_class", those keys will be deleted, and 114 their values value will be used for the loader options or class, 115 respectively, just as if set via the "loader_options" or "loader_class" 116 methods above. 117 118 The actual auto-loading operation (the heart of this module) will be 119 invoked as soon as the connection information is defined. 120 121 clone 122 See "clone" in DBIx::Class::Schema. 123 124 dump_to_dir 125 Argument: $directory 126 127 Calling this as a class method on either DBIx::Class::Schema::Loader or 128 any derived schema class will cause all schemas to dump manual versions 129 of themselves to the named directory when they are loaded. In order to 130 be effective, this must be set before defining a connection on this 131 schema class or any derived object (as the loading happens as soon as 132 both a connection and loader_options are set, and only once per class). 133 134 See "dump_directory" in DBIx::Class::Schema::Loader::Base for more 135 details on the dumping mechanism. 136 137 This can also be set at module import time via the import option 138 "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar" 139 is the target directory. 140 141 Examples: 142 143 # My::Schema isa DBIx::Class::Schema::Loader, and has connection info 144 # hardcoded in the class itself: 145 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1 146 147 # Same, but no hard-coded connection, so we must provide one: 148 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)' 149 150 # Or as a class method, as long as you get it done *before* defining a 151 # connection on this schema class or any derived object: 152 use My::Schema; 153 My::Schema->dump_to_dir('/foo/bar'); 154 My::Schema->connection(........); 155 156 # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all 157 # derived schemas 158 use My::Schema; 159 use My::OtherSchema; 160 DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar'); 161 My::Schema->connection(.......); 162 My::OtherSchema->connection(.......); 163 164 # Another alternative to the above: 165 use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |; 166 use My::Schema; 167 use My::OtherSchema; 168 My::Schema->connection(.......); 169 My::OtherSchema->connection(.......); 170 171 make_schema_at 172 Arguments: $schema_class_name, \%loader_options, \@connect_info 173 Return Value: $schema_class_name 174 175 This function creates a DBIx::Class schema from an existing RDBMS 176 schema. With the "dump_directory" option, generates a set of DBIx::Class 177 classes from an existing database schema read from the given dsn. 178 Without a "dump_directory", creates schema classes in memory at runtime 179 without generating on-disk class files. 180 181 For a complete list of supported loader_options, see 182 DBIx::Class::Schema::Loader::Base 183 184 The last hashref in the "\@connect_info" can specify the "loader_class". 185 186 This function can be imported in the usual way, as illustrated in these 187 Examples: 188 189 # Simple example, creates as a new class 'New::Schema::Name' in 190 # memory in the running perl interpreter. 191 use DBIx::Class::Schema::Loader qw/ make_schema_at /; 192 make_schema_at( 193 'New::Schema::Name', 194 { debug => 1 }, 195 [ 'dbi:Pg:dbname="foo"','postgres','', 196 { loader_class => 'MyLoader' } # optionally 197 ], 198 ); 199 200 # Inside a script, specifying a dump directory in which to write 201 # class files 202 use DBIx::Class::Schema::Loader qw/ make_schema_at /; 203 make_schema_at( 204 'New::Schema::Name', 205 { debug => 1, dump_directory => './lib' }, 206 [ 'dbi:Pg:dbname="foo"','postgres','', 207 { loader_class => 'MyLoader' } # optionally 208 ], 209 ); 210 211 The last hashref in the "\@connect_info" is checked for loader arguments 212 such as "loader_options" and "loader_class", see "connection" for more 213 details. 214 215 rescan 216 Return Value: @new_monikers 217 218 Re-scans the database for newly added tables since the initial load, and 219 adds them to the schema at runtime, including relationships, etc. Does 220 not process drops or changes. 221 222 Returns a list of the new monikers added. 223 224 naming 225 Arguments: \%opts | $ver 226 227 Controls the naming options for backward compatibility, see "naming" in 228 DBIx::Class::Schema::Loader::Base for details. 229 230 To upgrade a dynamic schema, use: 231 232 __PACKAGE__->naming('current'); 233 234 Can be imported into your dump script and called as a function as well: 235 236 naming('v4'); 237 238 use_namespaces 239 Arguments: 1|0 240 241 Controls the use_namespaces options for backward compatibility, see 242 "use_namespaces" in DBIx::Class::Schema::Loader::Base for details. 243 244 To upgrade a dynamic schema, use: 245 246 __PACKAGE__->use_namespaces(1); 247 248 Can be imported into your dump script and called as a function as well: 249 250 use_namespaces(1); 251 252KNOWN ISSUES 253 Multiple Database Schemas 254 See "db_schema" in DBIx::Class::Schema::Loader::Base. 255 256ACKNOWLEDGEMENTS 257 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent 258 in a bug report or suggestion. 259 260 Based on DBIx::Class::Loader by Sebastian Riedel 261 262 Based upon the work of IKEBE Tomohiro 263 264AUTHOR 265 blblack: Brandon Black <blblack@gmail.com> 266 267CONTRIBUTORS 268 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> 269 270 arcanez: Justin Hunter <justin.d.hunter@gmail.com> 271 272 ash: Ash Berlin <ash@cpan.org> 273 274 btilly: Ben Tilly <btilly@gmail.com> 275 276 Caelum: Rafael Kitover <rkitover@cpan.org> 277 278 TSUNODA Kazuya <drk@drk7.jp> 279 280 rbo: Robert Bohne <rbo@cpan.org> 281 282 ribasushi: Peter Rabbitson <ribasushi@cpan.org> 283 284 gugu: Andrey Kostenko <a.kostenko@rambler-co.ru> 285 286 jhannah: Jay Hannah <jay@jays.net> 287 288 jnap: John Napiorkowski <jjn1056@yahoo.com> 289 290 rbuels: Robert Buels <rbuels@gmail.com> 291 292 timbunce: Tim Bunce <timb@cpan.org> 293 294 mst: Matt S. Trout <mst@shadowcatsystems.co.uk> 295 296 mstratman: Mark A. Stratman <stratman@gmail.com> 297 298 kane: Jos Boumans <kane@cpan.org> 299 300 waawaamilk: Nigel McNie <nigel@mcnie.name> 301 302 acmoore: Andrew Moore <amoore@cpan.org> 303 304 bphillips: Brian Phillips <bphillips@cpan.org> 305 306 schwern: Michael G. Schwern <mschwern@cpan.org> 307 308 SineSwiper: Brendan Byrd <byrd.b@insightcom.com> 309 310 hobbs: Andrew Rodland <arodland@cpan.org> 311 312 domm: Thomas Klausner <domm@plix.at> 313 314 spb: Stephen Bennett <spb@exherbo.org> 315 316 Matias E. Fernandez <mfernandez@pisco.ch> 317 318 alnewkirk: Al Newkirk <awncorp@cpan.org> 319 320 angelixd: Paul C. Mantz <pcmantz@cpan.org> 321 322 andrewalker: André Walker <andre@andrewalker.net> 323 324 ... and lots of other folks. If we forgot you, please write the current 325 maintainer or RT. 326 327COPYRIGHT & LICENSE 328 Copyright (c) 2006 - 2009 by the aforementioned "AUTHOR" in 329 DBIx::Class::Schema::Loader and "CONTRIBUTORS" in 330 DBIx::Class::Schema::Loader. 331 332 This library is free software; you can redistribute it and/or modify it 333 under the same terms as Perl itself. 334 335SEE ALSO 336 DBIx::Class, DBIx::Class::Manual::Intro, DBIx::Class::Tutorial, 337 DBIx::Class::Schema::Loader::Base 338 339