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