lib/DBIx/Class.pm

   1 package DBIx::Class;
   2
   3 use strict;
   4 use warnings;
   5
   6 use MRO::Compat;
   7
   8 use vars qw($VERSION);
   9 use base qw/DBIx::Class::Componentised Class::Accessor::Grouped/;
  10 use DBIx::Class::StartupCheck;
  11
  12 sub mk_classdata {
  13   shift->mk_classaccessor(@_);
  14 }
  15
  16 sub mk_classaccessor {
  17   my $self = shift;
  18   $self->mk_group_accessors('inherited', $_[0]);
  19   $self->set_inherited(@_) if @_ > 1;
  20 }
  21
  22 sub component_base_class { 'DBIx::Class' }
  23
  24 # Always remember to do all digits for the version even if they're 0
  25 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
  26 # brain damage and presumably various other packaging systems too
  27
  28 $VERSION = '0.08111';
  29
  30 $VERSION = eval $VERSION; # numify for warning-free dev releases
  31
  32 # what version of sqlt do we require if deploy() without a ddl_dir is invoked
  33 # when changing also adjust the corresponding author_require in Makefile.PL
  34 my $minimum_sqlt_version = '0.11002';
  35
  36 sub MODIFY_CODE_ATTRIBUTES {
  37   my ($class,$code,@attrs) = @_;
  38   $class->mk_classdata('__attr_cache' => {})
  39     unless $class->can('__attr_cache');
  40   $class->__attr_cache->{$code} = [@attrs];
  41   return ();
  42 }
  43
  44 sub _attr_cache {
  45   my $self = shift;
  46   my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
  47   my $rest = eval { $self->next::method };
  48   return $@ ? $cache : { %$cache, %$rest };
  49 }
  50
  51 # SQLT version handling
  52 {
  53   my $_sqlt_version_ok;     # private
  54   my $_sqlt_version_error;  # private
  55
  56   sub _sqlt_version_ok {
  57     if (!defined $_sqlt_version_ok) {
  58       eval "use SQL::Translator $minimum_sqlt_version";
  59       if ($@) {
  60         $_sqlt_version_ok = 0;
  61         $_sqlt_version_error = $@;
  62       }
  63       else {
  64         $_sqlt_version_ok = 1;
  65       }
  66     }
  67     return $_sqlt_version_ok;
  68   }
  69
  70   sub _sqlt_version_error {
  71     shift->_sqlt_version_ok unless defined $_sqlt_version_ok;
  72     return $_sqlt_version_error;
  73   }
  74
  75   sub _sqlt_minimum_version { $minimum_sqlt_version };
  76 }
  77
  78 # Pretty printer for debug messages
  79 sub _pretty_print {
  80
  81   require Data::Dumper;
  82   local $Data::Dumper::Terse = 1;
  83   local $Data::Dumper::Indent = 1;
  84   local $Data::Dumper::Useqq = 1;
  85   local $Data::Dumper::Quotekeys = 0;
  86   local $Data::Dumper::Sortkeys = 1;
  87
  88   return Data::Dumper::Dumper ($_[1]);
  89 }
  90
  91
  92 1;
  93
  94 =head1 NAME
  95
  96 DBIx::Class - Extensible and flexible object <-> relational mapper.
  97
  98 =head1 GETTING HELP/SUPPORT
  99
 100 The community can be found via:
 101
 102   Mailing list: http://lists.scsys.co.uk/mailman/listinfo/dbix-class/
 103
 104   SVN: http://dev.catalyst.perl.org/repos/bast/DBIx-Class/
 105
 106   SVNWeb: http://dev.catalyst.perl.org/svnweb/bast/browse/DBIx-Class/
 107
 108   IRC: irc.perl.org#dbix-class
 109
 110 =head1 SYNOPSIS
 111
 112 Create a schema class called MyDB/Schema.pm:
 113
 114   package MyDB::Schema;
 115   use base qw/DBIx::Class::Schema/;
 116
 117   __PACKAGE__->load_namespaces();
 118
 119   1;
 120
 121 Create a result class to represent artists, who have many CDs, in
 122 MyDB/Schema/Result/Artist.pm:
 123
 124 See L<DBIx::Class::ResultSource> for docs on defining result classes.
 125
 126   package MyDB::Schema::Result::Artist;
 127   use base qw/DBIx::Class/;
 128
 129   __PACKAGE__->load_components(qw/Core/);
 130   __PACKAGE__->table('artist');
 131   __PACKAGE__->add_columns(qw/ artistid name /);
 132   __PACKAGE__->set_primary_key('artistid');
 133   __PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD');
 134
 135   1;
 136
 137 A result class to represent a CD, which belongs to an artist, in
 138 MyDB/Schema/Result/CD.pm:
 139
 140   package MyDB::Schema::Result::CD;
 141   use base qw/DBIx::Class/;
 142
 143   __PACKAGE__->load_components(qw/Core/);
 144   __PACKAGE__->table('cd');
 145   __PACKAGE__->add_columns(qw/ cdid artistid title year /);
 146   __PACKAGE__->set_primary_key('cdid');
 147   __PACKAGE__->belongs_to(artist => 'MyDB::Schema::Artist', 'artistid');
 148
 149   1;
 150
 151 Then you can use these classes in your application's code:
 152
 153   # Connect to your database.
 154   use MyDB::Schema;
 155   my $schema = MyDB::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
 156
 157   # Query for all artists and put them in an array,
 158   # or retrieve them as a result set object.
 159   # $schema->resultset returns a DBIx::Class::ResultSet
 160   my @all_artists = $schema->resultset('Artist')->all;
 161   my $all_artists_rs = $schema->resultset('Artist');
 162
 163   # Output all artists names
 164   # $artist here is a DBIx::Class::Row, which has accessors
 165   # for all its columns. Rows are also subclasses of your Result class.
 166   foreach $artist (@artists) {
 167     print $artist->name, "\n";
 168   }
 169
 170   # Create a result set to search for artists.
 171   # This does not query the DB.
 172   my $johns_rs = $schema->resultset('Artist')->search(
 173     # Build your WHERE using an SQL::Abstract structure:
 174     { name => { like => 'John%' } }
 175   );
 176
 177   # Execute a joined query to get the cds.
 178   my @all_john_cds = $johns_rs->search_related('cds')->all;
 179
 180   # Fetch the next available row.
 181   my $first_john = $johns_rs->next;
 182
 183   # Specify ORDER BY on the query.
 184   my $first_john_cds_by_title_rs = $first_john->cds(
 185     undef,
 186     { order_by => 'title' }
 187   );
 188
 189   # Create a result set that will fetch the artist data
 190   # at the same time as it fetches CDs, using only one query.
 191   my $millennium_cds_rs = $schema->resultset('CD')->search(
 192     { year => 2000 },
 193     { prefetch => 'artist' }
 194   );
 195
 196   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
 197   my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
 198
 199   # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
 200   # create() is the same as new() then insert().
 201   my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
 202   $new_cd->artist($cd->artist);
 203   $new_cd->insert; # Auto-increment primary key filled in after INSERT
 204   $new_cd->title('Fork');
 205
 206   $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
 207
 208   # change the year of all the millennium CDs at once
 209   $millennium_cds_rs->update({ year => 2002 });
 210
 211 =head1 DESCRIPTION
 212
 213 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
 214 (with a compatibility layer as a springboard for porting) and a resultset API
 215 that allows abstract encapsulation of database operations. It aims to make
 216 representing queries in your code as perl-ish as possible while still
 217 providing access to as many of the capabilities of the database as possible,
 218 including retrieving related records from multiple tables in a single query,
 219 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
 220
 221 DBIx::Class can handle multi-column primary and foreign keys, complex
 222 queries and database-level paging, and does its best to only query the
 223 database in order to return something you've directly asked for. If a
 224 resultset is used as an iterator it only fetches rows off the statement
 225 handle as requested in order to minimise memory usage. It has auto-increment
 226 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
 227 known to be used in production on at least the first four, and is fork-
 228 and thread-safe out of the box (although your DBD may not be).
 229
 230 This project is still under rapid development, so large new features may be
 231 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
 232 Failing test cases are *always* welcome and point releases are put out rapidly
 233 as bugs are found and fixed.
 234
 235 We do our best to maintain full backwards compatibility for published
 236 APIs, since DBIx::Class is used in production in many organisations,
 237 and even backwards incompatible changes to non-published APIs will be fixed
 238 if they're reported and doing so doesn't cost the codebase anything.
 239
 240 The test suite is quite substantial, and several developer releases
 241 are generally made to CPAN before the branch for the next release is
 242 merged back to trunk for a major release.
 243
 244 =head1 WHERE TO GO NEXT
 245
 246 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
 247 the modules where you will find documentation.
 248
 249 =head1 AUTHOR
 250
 251 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
 252
 253 (I mostly consider myself "project founder" these days but the AUTHOR heading
 254 is traditional :)
 255
 256 =head1 CONTRIBUTORS
 257
 258 abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
 259
 260 aherzog: Adam Herzog <adam@herzogdesigns.com>
 261
 262 andyg: Andy Grundman <andy@hybridized.org>
 263
 264 ank: Andres Kievsky
 265
 266 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
 267
 268 ash: Ash Berlin <ash@cpan.org>
 269
 270 bert: Norbert Csongradi <bert@cpan.org>
 271
 272 blblack: Brandon L. Black <blblack@gmail.com>
 273
 274 bluefeet: Aran Deltac <bluefeet@cpan.org>
 275
 276 bricas: Brian Cassidy <bricas@cpan.org>
 277
 278 brunov: Bruno Vecchi <vecchi.b@gmail.com>
 279
 280 caelum: Rafael Kitover <rkitover@cpan.org>
 281
 282 castaway: Jess Robinson
 283
 284 claco: Christopher H. Laco
 285
 286 clkao: CL Kao
 287
 288 da5id: David Jack Olrik <djo@cpan.org>
 289
 290 debolaz: Anders Nor Berle <berle@cpan.org>
 291
 292 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
 293
 294 dnm: Justin Wheeler <jwheeler@datademons.com>
 295
 296 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
 297
 298 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
 299
 300 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
 301
 302 gphat: Cory G Watson <gphat@cpan.org>
 303
 304 groditi: Guillermo Roditi <groditi@cpan.org>
 305
 306 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
 307
 308 jasonmay: Jason May <jason.a.may@gmail.com>
 309
 310 jesper: Jesper Krogh
 311
 312 jgoulah: John Goulah <jgoulah@cpan.org>
 313
 314 jguenther: Justin Guenther <jguenther@cpan.org>
 315
 316 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
 317
 318 jon: Jon Schutz <jjschutz@cpan.org>
 319
 320 jshirley: J. Shirley <jshirley@gmail.com>
 321
 322 konobi: Scott McWhirter
 323
 324 lukes: Luke Saunders <luke.saunders@gmail.com>
 325
 326 marcus: Marcus Ramberg <mramberg@cpan.org>
 327
 328 mattlaw: Matt Lawrence
 329
 330 michaelr: Michael Reddick <michael.reddick@gmail.com>
 331
 332 ned: Neil de Carteret
 333
 334 nigel: Nigel Metheringham <nigelm@cpan.org>
 335
 336 ningu: David Kamholz <dkamholz@cpan.org>
 337
 338 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
 339
 340 norbi: Norbert Buchmuller <norbi@nix.hu>
 341
 342 Numa: Dan Sully <daniel@cpan.org>
 343
 344 oyse: Øystein Torget <oystein.torget@dnv.com>
 345
 346 paulm: Paul Makepeace
 347
 348 penguin: K J Cheetham
 349
 350 perigrin: Chris Prather <chris@prather.org>
 351
 352 peter: Peter Collingbourne <peter@pcc.me.uk>
 353
 354 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
 355
 356 plu: Johannes Plunien <plu@cpan.org>
 357
 358 quicksilver: Jules Bean
 359
 360 rafl: Florian Ragwitz <rafl@debian.org>
 361
 362 rbuels: Robert Buels <rmb32@cornell.edu>
 363
 364 rdj: Ryan D Johnson <ryan@innerfence.com>
 365
 366 ribasushi: Peter Rabbitson <rabbit+dbic@rabbit.us>
 367
 368 rjbs: Ricardo Signes <rjbs@cpan.org>
 369
 370 robkinyon: Rob Kinyon <rkinyon@cpan.org>
 371
 372 sc_: Just Another Perl Hacker
 373
 374 scotty: Scotty Allen <scotty@scottyallen.com>
 375
 376 semifor: Marc Mims <marc@questright.com>
 377
 378 solomon: Jared Johnson <jaredj@nmgi.com>
 379
 380 spb: Stephen Bennett <stephen@freenode.net>
 381
 382 sszabo: Stephan Szabo <sszabo@bigpanda.com>
 383
 384 teejay : Aaron Trevena <teejay@cpan.org>
 385
 386 Todd Lipcon
 387
 388 Tom Hukins
 389
 390 typester: Daisuke Murase <typester@cpan.org>
 391
 392 victori: Victor Igumnov <victori@cpan.org>
 393
 394 wdh: Will Hawes
 395
 396 willert: Sebastian Willert <willert@cpan.org>
 397
 398 wreis: Wallace Reis <wreis@cpan.org>
 399
 400 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
 401
 402 =head1 COPYRIGHT
 403
 404 Copyright (c) 2005 - 2009 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
 405 as listed above.
 406
 407 =head1 LICENSE
 408
 409 This library is free software and may be distributed under the same terms
 410 as perl itself.
 411
 412 =cut