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.08250';
  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
  45   if ($] < 5.009_005) {
  46     require MRO::Compat;
  47     constant->import( OLD_MRO => 1 );
  48   }
  49   else {
  50     require mro;
  51     constant->import( OLD_MRO => 0 );
  52   }
  53 }
  54
  55 use mro 'c3';
  56
  57 use DBIx::Class::Optional::Dependencies;
  58
  59 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
  60 use DBIx::Class::StartupCheck;
  61 use DBIx::Class::Exception;
  62
  63 __PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
  64 __PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny|^Class::Accessor::Grouped|^Context::Preserve');
  65
  66 sub mk_classdata {
  67   shift->mk_classaccessor(@_);
  68 }
  69
  70 sub mk_classaccessor {
  71   my $self = shift;
  72   $self->mk_group_accessors('inherited', $_[0]);
  73   $self->set_inherited(@_) if @_ > 1;
  74 }
  75
  76 sub component_base_class { 'DBIx::Class' }
  77
  78 sub MODIFY_CODE_ATTRIBUTES {
  79   my ($class,$code,@attrs) = @_;
  80   $class->mk_classdata('__attr_cache' => {})
  81     unless $class->can('__attr_cache');
  82   $class->__attr_cache->{$code} = [@attrs];
  83   return ();
  84 }
  85
  86 sub _attr_cache {
  87   my $self = shift;
  88   my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
  89
  90   return {
  91     %$cache,
  92     %{ $self->maybe::next::method || {} },
  93   };
  94 }
  95
  96 1;
  97
  98 __END__
  99
 100 =encoding UTF-8
 101
 102 =head1 NAME
 103
 104 DBIx::Class - Extensible and flexible object <-> relational mapper.
 105
 106 =head1 WHERE TO START READING
 107
 108 See L<DBIx::Class::Manual::DocMap> for an overview of the exhaustive documentation.
 109 To get the most out of DBIx::Class with the least confusion it is strongly
 110 recommended to read (at the very least) the
 111 L<Manuals|DBIx::Class::Manual::DocMap/Manuals> in the order presented there.
 112
 113 =head1 HOW TO GET HELP
 114
 115 Due to the complexity of its problem domain, DBIx::Class is a relatively
 116 complex framework. After you start using DBIx::Class questions will inevitably
 117 arise. If you are stuck with a problem or have doubts about a particular
 118 approach do not hesitate to contact the community with your questions. The
 119 list below is sorted by "fastest response time":
 120
 121 =over
 122
 123 =item * IRC: irc.perl.org#dbix-class
 124
 125 =for html
 126 <a href="https://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
 127
 128 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
 129
 130 =item * RT Bug Tracker: L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-Class>
 131
 132 =item * Twitter: L<https://www.twitter.com/dbix_class>
 133
 134 =item * Web Site: L<http://www.dbix-class.org/>
 135
 136 =back
 137
 138 =head1 SYNOPSIS
 139
 140 =head2 Schema classes preparation
 141
 142 Create a schema class called F<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 F<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 F<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 =head2 API usage
 181
 182 Then you can use these classes in your application's code:
 183
 184   # Connect to your database.
 185   use MyApp::Schema;
 186   my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
 187
 188   # Query for all artists and put them in an array,
 189   # or retrieve them as a result set object.
 190   # $schema->resultset returns a DBIx::Class::ResultSet
 191   my @all_artists = $schema->resultset('Artist')->all;
 192   my $all_artists_rs = $schema->resultset('Artist');
 193
 194   # Output all artists names
 195   # $artist here is a DBIx::Class::Row, which has accessors
 196   # for all its columns. Rows are also subclasses of your Result class.
 197   foreach $artist (@all_artists) {
 198     print $artist->name, "\n";
 199   }
 200
 201   # Create a result set to search for artists.
 202   # This does not query the DB.
 203   my $johns_rs = $schema->resultset('Artist')->search(
 204     # Build your WHERE using an SQL::Abstract structure:
 205     { name => { like => 'John%' } }
 206   );
 207
 208   # Execute a joined query to get the cds.
 209   my @all_john_cds = $johns_rs->search_related('cds')->all;
 210
 211   # Fetch the next available row.
 212   my $first_john = $johns_rs->next;
 213
 214   # Specify ORDER BY on the query.
 215   my $first_john_cds_by_title_rs = $first_john->cds(
 216     undef,
 217     { order_by => 'title' }
 218   );
 219
 220   # Create a result set that will fetch the artist data
 221   # at the same time as it fetches CDs, using only one query.
 222   my $millennium_cds_rs = $schema->resultset('CD')->search(
 223     { year => 2000 },
 224     { prefetch => 'artist' }
 225   );
 226
 227   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
 228   my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
 229
 230   # new() makes a Result object but doesnt insert it into the DB.
 231   # create() is the same as new() then insert().
 232   my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
 233   $new_cd->artist($cd->artist);
 234   $new_cd->insert; # Auto-increment primary key filled in after INSERT
 235   $new_cd->title('Fork');
 236
 237   $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
 238
 239   # change the year of all the millennium CDs at once
 240   $millennium_cds_rs->update({ year => 2002 });
 241
 242 =head1 DESCRIPTION
 243
 244 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
 245 (with a compatibility layer as a springboard for porting) and a resultset API
 246 that allows abstract encapsulation of database operations. It aims to make
 247 representing queries in your code as perl-ish as possible while still
 248 providing access to as many of the capabilities of the database as possible,
 249 including retrieving related records from multiple tables in a single query,
 250 C<JOIN>, C<LEFT JOIN>, C<COUNT>, C<DISTINCT>, C<GROUP BY>, C<ORDER BY> and
 251 C<HAVING> support.
 252
 253 DBIx::Class can handle multi-column primary and foreign keys, complex
 254 queries and database-level paging, and does its best to only query the
 255 database in order to return something you've directly asked for. If a
 256 resultset is used as an iterator it only fetches rows off the statement
 257 handle as requested in order to minimise memory usage. It has auto-increment
 258 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
 259 known to be used in production on at least the first four, and is fork-
 260 and thread-safe out of the box (although
 261 L<your DBD may not be|DBI/Threads and Thread Safety>).
 262
 263 This project is still under rapid development, so large new features may be
 264 marked B<experimental> - such APIs are still usable but may have edge bugs.
 265 Failing test cases are I<always> welcome and point releases are put out rapidly
 266 as bugs are found and fixed.
 267
 268 We do our best to maintain full backwards compatibility for published
 269 APIs, since DBIx::Class is used in production in many organisations,
 270 and even backwards incompatible changes to non-published APIs will be fixed
 271 if they're reported and doing so doesn't cost the codebase anything.
 272
 273 The test suite is quite substantial, and several developer releases
 274 are generally made to CPAN before the branch for the next release is
 275 merged back to trunk for a major release.
 276
 277 =head1 HOW TO CONTRIBUTE
 278
 279 Contributions are always welcome, in all usable forms (we especially
 280 welcome documentation improvements). The delivery methods include git-
 281 or unified-diff formatted patches, GitHub pull requests, or plain bug
 282 reports either via RT or the Mailing list. Contributors are generally
 283 granted full access to the official repository after their first patch
 284 passes successful review.
 285
 286 =for comment
 287 FIXME: Getty, frew and jnap need to get off their asses and finish the contrib section so we can link it here ;)
 288
 289 This project is maintained in a git repository. The code and related tools are
 290 accessible at the following locations:
 291
 292 =over
 293
 294 =item * Official repo: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
 295
 296 =item * Official gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
 297
 298 =item * GitHub mirror: L<https://github.com/dbsrgits/DBIx-Class>
 299
 300 =item * Authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/DBIx-Class.git>
 301
 302 =item * Travis-CI log: L<https://travis-ci.org/dbsrgits/dbix-class/builds>
 303
 304 =for html
 305 &#x21AA; Stable branch CI status: <img src="https://secure.travis-ci.org/dbsrgits/dbix-class.png?branch=master"></img>
 306
 307 =back
 308
 309 =head1 AUTHOR
 310
 311 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
 312
 313 (I mostly consider myself "project founder" these days but the AUTHOR heading
 314 is traditional :)
 315
 316 =head1 CONTRIBUTORS
 317
 318 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
 319
 320 acca: Alexander Kuznetsov <acca@cpan.org>
 321
 322 aherzog: Adam Herzog <adam@herzogdesigns.com>
 323
 324 Alexander Keusch <cpan@keusch.at>
 325
 326 alexrj: Alessandro Ranellucci <aar@cpan.org>
 327
 328 alnewkirk: Al Newkirk <we@ana.im>
 329
 330 amiri: Amiri Barksdale <amiri@metalabel.com>
 331
 332 amoore: Andrew Moore <amoore@cpan.org>
 333
 334 andrewalker: Andre Walker <andre@andrewalker.net>
 335
 336 andyg: Andy Grundman <andy@hybridized.org>
 337
 338 ank: Andres Kievsky
 339
 340 arc: Aaron Crane <arc@cpan.org>
 341
 342 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
 343
 344 ash: Ash Berlin <ash@cpan.org>
 345
 346 bert: Norbert Csongradi <bert@cpan.org>
 347
 348 blblack: Brandon L. Black <blblack@gmail.com>
 349
 350 bluefeet: Aran Deltac <bluefeet@cpan.org>
 351
 352 bphillips: Brian Phillips <bphillips@cpan.org>
 353
 354 boghead: Bryan Beeley <cpan@beeley.org>
 355
 356 brd: Brad Davis <brd@FreeBSD.org>
 357
 358 bricas: Brian Cassidy <bricas@cpan.org>
 359
 360 brunov: Bruno Vecchi <vecchi.b@gmail.com>
 361
 362 caelum: Rafael Kitover <rkitover@cpan.org>
 363
 364 caldrin: Maik Hentsche <maik.hentsche@amd.com>
 365
 366 castaway: Jess Robinson
 367
 368 claco: Christopher H. Laco
 369
 370 clkao: CL Kao
 371
 372 da5id: David Jack Olrik <djo@cpan.org>
 373
 374 dariusj: Darius Jokilehto <dariusjokilehto@yahoo.co.uk>
 375
 376 davewood: David Schmidt <davewood@gmx.at>
 377
 378 daxim: Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim@cpan.org>
 379
 380 debolaz: Anders Nor Berle <berle@cpan.org>
 381
 382 dew: Dan Thomas <dan@godders.org>
 383
 384 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
 385
 386 dnm: Justin Wheeler <jwheeler@datademons.com>
 387
 388 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
 389
 390 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
 391
 392 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
 393
 394 edenc: Eden Cardim <edencardim@gmail.com>
 395
 396 felliott: Fitz Elliott <fitz.elliott@gmail.com>
 397
 398 freetime: Bill Moseley <moseley@hank.org>
 399
 400 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
 401
 402 goraxe: Gordon Irving <goraxe@cpan.org>
 403
 404 gphat: Cory G Watson <gphat@cpan.org>
 405
 406 Grant Street Group L<http://www.grantstreet.com/>
 407
 408 groditi: Guillermo Roditi <groditi@cpan.org>
 409
 410 Haarg: Graham Knop <haarg@haarg.org>
 411
 412 hobbs: Andrew Rodland <arodland@cpan.org>
 413
 414 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
 415
 416 initself: Mike Baas <mike@initselftech.com>
 417
 418 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
 419
 420 jawnsy: Jonathan Yu <jawnsy@cpan.org>
 421
 422 jasonmay: Jason May <jason.a.may@gmail.com>
 423
 424 jesper: Jesper Krogh
 425
 426 jgoulah: John Goulah <jgoulah@cpan.org>
 427
 428 jguenther: Justin Guenther <jguenther@cpan.org>
 429
 430 jhannah: Jay Hannah <jay@jays.net>
 431
 432 jmac: Jason McIntosh <jmac@appleseed-sc.com>
 433
 434 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
 435
 436 jon: Jon Schutz <jjschutz@cpan.org>
 437
 438 jshirley: J. Shirley <jshirley@gmail.com>
 439
 440 kaare: Kaare Rasmussen
 441
 442 konobi: Scott McWhirter
 443
 444 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
 445
 446 lukes: Luke Saunders <luke.saunders@gmail.com>
 447
 448 marcus: Marcus Ramberg <mramberg@cpan.org>
 449
 450 mattlaw: Matt Lawrence
 451
 452 mattp: Matt Phillips <mattp@cpan.org>
 453
 454 michaelr: Michael Reddick <michael.reddick@gmail.com>
 455
 456 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
 457
 458 mithaldu: Christian Walde <walde.christian@gmail.com>
 459
 460 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
 461
 462 mstratman: Mark A. Stratman <stratman@gmail.com>
 463
 464 ned: Neil de Carteret
 465
 466 nigel: Nigel Metheringham <nigelm@cpan.org>
 467
 468 ningu: David Kamholz <dkamholz@cpan.org>
 469
 470 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
 471
 472 norbi: Norbert Buchmuller <norbi@nix.hu>
 473
 474 nuba: Nuba Princigalli <nuba@cpan.org>
 475
 476 Numa: Dan Sully <daniel@cpan.org>
 477
 478 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
 479
 480 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
 481
 482 paulm: Paul Makepeace
 483
 484 penguin: K J Cheetham
 485
 486 perigrin: Chris Prather <chris@prather.org>
 487
 488 peter: Peter Collingbourne <peter@pcc.me.uk>
 489
 490 Peter Valdemar ME<oslash>rch <peter@morch.com>
 491
 492 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
 493
 494 plu: Johannes Plunien <plu@cpan.org>
 495
 496 Possum: Daniel LeWarne <possum@cpan.org>
 497
 498 quicksilver: Jules Bean
 499
 500 rafl: Florian Ragwitz <rafl@debian.org>
 501
 502 rainboxx: Matthias Dietrich <perl@rb.ly>
 503
 504 rbo: Robert Bohne <rbo@cpan.org>
 505
 506 rbuels: Robert Buels <rmb32@cornell.edu>
 507
 508 rdj: Ryan D Johnson <ryan@innerfence.com>
 509
 510 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
 511
 512 rjbs: Ricardo Signes <rjbs@cpan.org>
 513
 514 robkinyon: Rob Kinyon <rkinyon@cpan.org>
 515
 516 Robert Olson <bob@rdolson.org>
 517
 518 moltar: Roman Filippov <romanf@cpan.org>
 519
 520 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
 521
 522 sc_: Just Another Perl Hacker
 523
 524 scotty: Scotty Allen <scotty@scottyallen.com>
 525
 526 semifor: Marc Mims <marc@questright.com>
 527
 528 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
 529
 530 solomon: Jared Johnson <jaredj@nmgi.com>
 531
 532 spb: Stephen Bennett <stephen@freenode.net>
 533
 534 Squeeks <squeek@cpan.org>
 535
 536 sszabo: Stephan Szabo <sszabo@bigpanda.com>
 537
 538 talexb: Alex Beamish <talexb@gmail.com>
 539
 540 tamias: Ronald J Kimball <rjk@tamias.net>
 541
 542 teejay : Aaron Trevena <teejay@cpan.org>
 543
 544 Todd Lipcon
 545
 546 Tom Hukins
 547
 548 tonvoon: Ton Voon <tonvoon@cpan.org>
 549
 550 triode: Pete Gamache <gamache@cpan.org>
 551
 552 typester: Daisuke Murase <typester@cpan.org>
 553
 554 victori: Victor Igumnov <victori@cpan.org>
 555
 556 wdh: Will Hawes
 557
 558 wesm: Wes Malone <wes@mitsi.com>
 559
 560 willert: Sebastian Willert <willert@cpan.org>
 561
 562 wreis: Wallace Reis <wreis@cpan.org>
 563
 564 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
 565
 566 yrlnry: Mark Jason Dominus <mjd@plover.com>
 567
 568 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
 569
 570 =head1 COPYRIGHT
 571
 572 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
 573 as listed above.
 574
 575 =head1 LICENSE
 576
 577 This library is free software and may be distributed under the same terms
 578 as perl itself.