lib/DBIx/Class.pm

   1 package DBIx::Class;
   2
   3 use strict;
   4 use warnings;
   5
   6 our $VERSION;
   7 # Always remember to do all digits for the version even if they're 0
   8 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
   9 # brain damage and presumably various other packaging systems too
  10
  11 # $VERSION declaration must stay up here, ahead of any other package
  12 # declarations, as to not confuse various modules attempting to determine
  13 # this ones version, whether that be s.c.o. or Module::Metadata, etc
  14 $VERSION = '0.08204';
  15
  16 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
  17
  18 BEGIN {
  19   package # hide from pause
  20     DBIx::Class::_ENV_;
  21
  22   use Config;
  23
  24   use constant {
  25
  26     # but of course
  27     BROKEN_FORK => ($^O eq 'MSWin32') ? 1 : 0,
  28
  29     HAS_ITHREADS => $Config{useithreads} ? 1 : 0,
  30
  31     # ::Runmode would only be loaded by DBICTest, which in turn implies t/
  32     DBICTEST => eval { DBICTest::RunMode->is_author } ? 1 : 0,
  33
  34     # During 5.13 dev cycle HELEMs started to leak on copy
  35     PEEPEENESS =>
  36       # request for all tests would force "non-leaky" illusion and vice-versa
  37       defined $ENV{DBICTEST_ALL_LEAKS}                                              ? !$ENV{DBICTEST_ALL_LEAKS}
  38       # otherwise confess that this perl is busted ONLY on smokers
  39     : eval { DBICTest::RunMode->is_smoker } && ($] >= 5.013005 and $] <= 5.013006)  ? 1
  40       # otherwise we are good
  41                                                                                     : 0
  42     ,
  43
  44     # There was a brief period of p5p insanity when $@ was invisible in a DESTROY
  45     INVISIBLE_DOLLAR_AT => ($] >= 5.013001 and $] <= 5.013007) ? 1 : 0,
  46
  47   };
  48
  49   if ($] < 5.009_005) {
  50     require MRO::Compat;
  51     constant->import( OLD_MRO => 1 );
  52   }
  53   else {
  54     require mro;
  55     constant->import( OLD_MRO => 0 );
  56   }
  57 }
  58
  59 use mro 'c3';
  60
  61 use DBIx::Class::Optional::Dependencies;
  62
  63 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
  64 use DBIx::Class::StartupCheck;
  65
  66 __PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
  67 __PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny|^Class::Accessor::Grouped|^Context::Preserve');
  68
  69 sub mk_classdata {
  70   shift->mk_classaccessor(@_);
  71 }
  72
  73 sub mk_classaccessor {
  74   my $self = shift;
  75   $self->mk_group_accessors('inherited', $_[0]);
  76   $self->set_inherited(@_) if @_ > 1;
  77 }
  78
  79 sub component_base_class { 'DBIx::Class' }
  80
  81 sub MODIFY_CODE_ATTRIBUTES {
  82   my ($class,$code,@attrs) = @_;
  83   $class->mk_classdata('__attr_cache' => {})
  84     unless $class->can('__attr_cache');
  85   $class->__attr_cache->{$code} = [@attrs];
  86   return ();
  87 }
  88
  89 sub _attr_cache {
  90   my $self = shift;
  91   my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
  92
  93   return {
  94     %$cache,
  95     %{ $self->maybe::next::method || {} },
  96   };
  97 }
  98
  99 1;
 100
 101 =head1 NAME
 102
 103 DBIx::Class - Extensible and flexible object <-> relational mapper.
 104
 105 =head1 GETTING HELP/SUPPORT
 106
 107 The community can be found via:
 108
 109 =over
 110
 111 =item * IRC: irc.perl.org#dbix-class
 112
 113 =for html
 114 <a href="http://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
 115
 116 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
 117
 118 =item * Twitter L<http://www.twitter.com/dbix_class>
 119
 120 =item * Web Site: L<http://www.dbix-class.org/>
 121
 122 =item * RT Bug Tracker: L<https://rt.cpan.org/Dist/Display.html?Queue=DBIx-Class>
 123
 124 =back
 125
 126 The project is maintained in a git repository, accessible from the following sources:
 127
 128 =over
 129
 130 =item * git: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
 131
 132 =item * gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
 133
 134 =item * github mirror: L<https://github.com/dbsrgits/DBIx-Class>
 135
 136 =item * authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/DBIx-Class.git>
 137
 138 =back
 139
 140 =head1 SYNOPSIS
 141
 142 Create a schema class called MyApp/Schema.pm:
 143
 144   package MyApp::Schema;
 145   use base qw/DBIx::Class::Schema/;
 146
 147   __PACKAGE__->load_namespaces();
 148
 149   1;
 150
 151 Create a result class to represent artists, who have many CDs, in
 152 MyApp/Schema/Result/Artist.pm:
 153
 154 See L<DBIx::Class::ResultSource> for docs on defining result classes.
 155
 156   package MyApp::Schema::Result::Artist;
 157   use base qw/DBIx::Class::Core/;
 158
 159   __PACKAGE__->table('artist');
 160   __PACKAGE__->add_columns(qw/ artistid name /);
 161   __PACKAGE__->set_primary_key('artistid');
 162   __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');
 163
 164   1;
 165
 166 A result class to represent a CD, which belongs to an artist, in
 167 MyApp/Schema/Result/CD.pm:
 168
 169   package MyApp::Schema::Result::CD;
 170   use base qw/DBIx::Class::Core/;
 171
 172   __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
 173   __PACKAGE__->table('cd');
 174   __PACKAGE__->add_columns(qw/ cdid artistid title year /);
 175   __PACKAGE__->set_primary_key('cdid');
 176   __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
 177
 178   1;
 179
 180 Then you can use these classes in your application's code:
 181
 182   # Connect to your database.
 183   use MyApp::Schema;
 184   my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
 185
 186   # Query for all artists and put them in an array,
 187   # or retrieve them as a result set object.
 188   # $schema->resultset returns a DBIx::Class::ResultSet
 189   my @all_artists = $schema->resultset('Artist')->all;
 190   my $all_artists_rs = $schema->resultset('Artist');
 191
 192   # Output all artists names
 193   # $artist here is a DBIx::Class::Row, which has accessors
 194   # for all its columns. Rows are also subclasses of your Result class.
 195   foreach $artist (@all_artists) {
 196     print $artist->name, "\n";
 197   }
 198
 199   # Create a result set to search for artists.
 200   # This does not query the DB.
 201   my $johns_rs = $schema->resultset('Artist')->search(
 202     # Build your WHERE using an SQL::Abstract structure:
 203     { name => { like => 'John%' } }
 204   );
 205
 206   # Execute a joined query to get the cds.
 207   my @all_john_cds = $johns_rs->search_related('cds')->all;
 208
 209   # Fetch the next available row.
 210   my $first_john = $johns_rs->next;
 211
 212   # Specify ORDER BY on the query.
 213   my $first_john_cds_by_title_rs = $first_john->cds(
 214     undef,
 215     { order_by => 'title' }
 216   );
 217
 218   # Create a result set that will fetch the artist data
 219   # at the same time as it fetches CDs, using only one query.
 220   my $millennium_cds_rs = $schema->resultset('CD')->search(
 221     { year => 2000 },
 222     { prefetch => 'artist' }
 223   );
 224
 225   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
 226   my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
 227
 228   # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
 229   # create() is the same as new() then insert().
 230   my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
 231   $new_cd->artist($cd->artist);
 232   $new_cd->insert; # Auto-increment primary key filled in after INSERT
 233   $new_cd->title('Fork');
 234
 235   $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
 236
 237   # change the year of all the millennium CDs at once
 238   $millennium_cds_rs->update({ year => 2002 });
 239
 240 =head1 DESCRIPTION
 241
 242 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
 243 (with a compatibility layer as a springboard for porting) and a resultset API
 244 that allows abstract encapsulation of database operations. It aims to make
 245 representing queries in your code as perl-ish as possible while still
 246 providing access to as many of the capabilities of the database as possible,
 247 including retrieving related records from multiple tables in a single query,
 248 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
 249
 250 DBIx::Class can handle multi-column primary and foreign keys, complex
 251 queries and database-level paging, and does its best to only query the
 252 database in order to return something you've directly asked for. If a
 253 resultset is used as an iterator it only fetches rows off the statement
 254 handle as requested in order to minimise memory usage. It has auto-increment
 255 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
 256 known to be used in production on at least the first four, and is fork-
 257 and thread-safe out of the box (although
 258 L<your DBD may not be|DBI/Threads and Thread Safety>).
 259
 260 This project is still under rapid development, so large new features may be
 261 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
 262 Failing test cases are *always* welcome and point releases are put out rapidly
 263 as bugs are found and fixed.
 264
 265 We do our best to maintain full backwards compatibility for published
 266 APIs, since DBIx::Class is used in production in many organisations,
 267 and even backwards incompatible changes to non-published APIs will be fixed
 268 if they're reported and doing so doesn't cost the codebase anything.
 269
 270 The test suite is quite substantial, and several developer releases
 271 are generally made to CPAN before the branch for the next release is
 272 merged back to trunk for a major release.
 273
 274 =head1 WHERE TO GO NEXT
 275
 276 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
 277 the modules where you will find documentation.
 278
 279 =head1 AUTHOR
 280
 281 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
 282
 283 (I mostly consider myself "project founder" these days but the AUTHOR heading
 284 is traditional :)
 285
 286 =head1 CONTRIBUTORS
 287
 288 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
 289
 290 acca: Alexander Kuznetsov <acca@cpan.org>
 291
 292 aherzog: Adam Herzog <adam@herzogdesigns.com>
 293
 294 Alexander Keusch <cpan@keusch.at>
 295
 296 alexrj: Alessandro Ranellucci <aar@cpan.org>
 297
 298 alnewkirk: Al Newkirk <we@ana.im>
 299
 300 amiri: Amiri Barksdale <amiri@metalabel.com>
 301
 302 amoore: Andrew Moore <amoore@cpan.org>
 303
 304 andyg: Andy Grundman <andy@hybridized.org>
 305
 306 ank: Andres Kievsky
 307
 308 arc: Aaron Crane <arc@cpan.org>
 309
 310 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
 311
 312 ash: Ash Berlin <ash@cpan.org>
 313
 314 bert: Norbert Csongradi <bert@cpan.org>
 315
 316 blblack: Brandon L. Black <blblack@gmail.com>
 317
 318 bluefeet: Aran Deltac <bluefeet@cpan.org>
 319
 320 bphillips: Brian Phillips <bphillips@cpan.org>
 321
 322 boghead: Bryan Beeley <cpan@beeley.org>
 323
 324 brd: Brad Davis <brd@FreeBSD.org>
 325
 326 bricas: Brian Cassidy <bricas@cpan.org>
 327
 328 brunov: Bruno Vecchi <vecchi.b@gmail.com>
 329
 330 caelum: Rafael Kitover <rkitover@cpan.org>
 331
 332 caldrin: Maik Hentsche <maik.hentsche@amd.com>
 333
 334 castaway: Jess Robinson
 335
 336 claco: Christopher H. Laco
 337
 338 clkao: CL Kao
 339
 340 da5id: David Jack Olrik <djo@cpan.org>
 341
 342 debolaz: Anders Nor Berle <berle@cpan.org>
 343
 344 dew: Dan Thomas <dan@godders.org>
 345
 346 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
 347
 348 dnm: Justin Wheeler <jwheeler@datademons.com>
 349
 350 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
 351
 352 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
 353
 354 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
 355
 356 edenc: Eden Cardim <edencardim@gmail.com>
 357
 358 felliott: Fitz Elliott <fitz.elliott@gmail.com>
 359
 360 freetime: Bill Moseley <moseley@hank.org>
 361
 362 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
 363
 364 goraxe: Gordon Irving <goraxe@cpan.org>
 365
 366 gphat: Cory G Watson <gphat@cpan.org>
 367
 368 Grant Street Group L<http://www.grantstreet.com/>
 369
 370 groditi: Guillermo Roditi <groditi@cpan.org>
 371
 372 Haarg: Graham Knop <haarg@haarg.org>
 373
 374 hobbs: Andrew Rodland <arodland@cpan.org>
 375
 376 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
 377
 378 initself: Mike Baas <mike@initselftech.com>
 379
 380 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
 381
 382 jawnsy: Jonathan Yu <jawnsy@cpan.org>
 383
 384 jasonmay: Jason May <jason.a.may@gmail.com>
 385
 386 jesper: Jesper Krogh
 387
 388 jgoulah: John Goulah <jgoulah@cpan.org>
 389
 390 jguenther: Justin Guenther <jguenther@cpan.org>
 391
 392 jhannah: Jay Hannah <jay@jays.net>
 393
 394 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
 395
 396 jon: Jon Schutz <jjschutz@cpan.org>
 397
 398 jshirley: J. Shirley <jshirley@gmail.com>
 399
 400 kaare: Kaare Rasmussen
 401
 402 konobi: Scott McWhirter
 403
 404 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
 405
 406 lukes: Luke Saunders <luke.saunders@gmail.com>
 407
 408 marcus: Marcus Ramberg <mramberg@cpan.org>
 409
 410 mattlaw: Matt Lawrence
 411
 412 mattp: Matt Phillips <mattp@cpan.org>
 413
 414 michaelr: Michael Reddick <michael.reddick@gmail.com>
 415
 416 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
 417
 418 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
 419
 420 mstratman: Mark A. Stratman <stratman@gmail.com>
 421
 422 ned: Neil de Carteret
 423
 424 nigel: Nigel Metheringham <nigelm@cpan.org>
 425
 426 ningu: David Kamholz <dkamholz@cpan.org>
 427
 428 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
 429
 430 norbi: Norbert Buchmuller <norbi@nix.hu>
 431
 432 nuba: Nuba Princigalli <nuba@cpan.org>
 433
 434 Numa: Dan Sully <daniel@cpan.org>
 435
 436 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
 437
 438 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
 439
 440 paulm: Paul Makepeace
 441
 442 penguin: K J Cheetham
 443
 444 perigrin: Chris Prather <chris@prather.org>
 445
 446 peter: Peter Collingbourne <peter@pcc.me.uk>
 447
 448 Peter Valdemar ME<oslash>rch <peter@morch.com>
 449
 450 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
 451
 452 plu: Johannes Plunien <plu@cpan.org>
 453
 454 Possum: Daniel LeWarne <possum@cpan.org>
 455
 456 quicksilver: Jules Bean
 457
 458 rafl: Florian Ragwitz <rafl@debian.org>
 459
 460 rainboxx: Matthias Dietrich <perl@rb.ly>
 461
 462 rbo: Robert Bohne <rbo@cpan.org>
 463
 464 rbuels: Robert Buels <rmb32@cornell.edu>
 465
 466 rdj: Ryan D Johnson <ryan@innerfence.com>
 467
 468 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
 469
 470 rjbs: Ricardo Signes <rjbs@cpan.org>
 471
 472 robkinyon: Rob Kinyon <rkinyon@cpan.org>
 473
 474 Robert Olson <bob@rdolson.org>
 475
 476 Roman: Roman Filippov <romanf@cpan.org>
 477
 478 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
 479
 480 sc_: Just Another Perl Hacker
 481
 482 scotty: Scotty Allen <scotty@scottyallen.com>
 483
 484 semifor: Marc Mims <marc@questright.com>
 485
 486 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
 487
 488 solomon: Jared Johnson <jaredj@nmgi.com>
 489
 490 spb: Stephen Bennett <stephen@freenode.net>
 491
 492 Squeeks <squeek@cpan.org>
 493
 494 sszabo: Stephan Szabo <sszabo@bigpanda.com>
 495
 496 talexb: Alex Beamish <talexb@gmail.com>
 497
 498 tamias: Ronald J Kimball <rjk@tamias.net>
 499
 500 teejay : Aaron Trevena <teejay@cpan.org>
 501
 502 Todd Lipcon
 503
 504 Tom Hukins
 505
 506 tonvoon: Ton Voon <tonvoon@cpan.org>
 507
 508 triode: Pete Gamache <gamache@cpan.org>
 509
 510 typester: Daisuke Murase <typester@cpan.org>
 511
 512 victori: Victor Igumnov <victori@cpan.org>
 513
 514 wdh: Will Hawes
 515
 516 wesm: Wes Malone <wes@mitsi.com>
 517
 518 willert: Sebastian Willert <willert@cpan.org>
 519
 520 wreis: Wallace Reis <wreis@cpan.org>
 521
 522 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
 523
 524 yrlnry: Mark Jason Dominus <mjd@plover.com>
 525
 526 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
 527
 528 =head1 COPYRIGHT
 529
 530 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
 531 as listed above.
 532
 533 =head1 LICENSE
 534
 535 This library is free software and may be distributed under the same terms
 536 as perl itself.
 537
 538 =cut