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 Csongradi <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 felliott: Fitz Elliott <fitz.elliott@gmail.com>
 402
 403 freetime: Bill Moseley <moseley@hank.org>
 404
 405 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
 406
 407 goraxe: Gordon Irving <goraxe@cpan.org>
 408
 409 gphat: Cory G Watson <gphat@cpan.org>
 410
 411 Grant Street Group L<http://www.grantstreet.com/>
 412
 413 groditi: Guillermo Roditi <groditi@cpan.org>
 414
 415 Haarg: Graham Knop <haarg@haarg.org>
 416
 417 hobbs: Andrew Rodland <arodland@cpan.org>
 418
 419 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
 420
 421 initself: Mike Baas <mike@initselftech.com>
 422
 423 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
 424
 425 jawnsy: Jonathan Yu <jawnsy@cpan.org>
 426
 427 jasonmay: Jason May <jason.a.may@gmail.com>
 428
 429 jesper: Jesper Krogh
 430
 431 jgoulah: John Goulah <jgoulah@cpan.org>
 432
 433 jguenther: Justin Guenther <jguenther@cpan.org>
 434
 435 jhannah: Jay Hannah <jay@jays.net>
 436
 437 jmac: Jason McIntosh <jmac@appleseed-sc.com>
 438
 439 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
 440
 441 jon: Jon Schutz <jjschutz@cpan.org>
 442
 443 jshirley: J. Shirley <jshirley@gmail.com>
 444
 445 kaare: Kaare Rasmussen
 446
 447 konobi: Scott McWhirter
 448
 449 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
 450
 451 lukes: Luke Saunders <luke.saunders@gmail.com>
 452
 453 marcus: Marcus Ramberg <mramberg@cpan.org>
 454
 455 mattlaw: Matt Lawrence
 456
 457 mattp: Matt Phillips <mattp@cpan.org>
 458
 459 michaelr: Michael Reddick <michael.reddick@gmail.com>
 460
 461 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
 462
 463 mithaldu: Christian Walde <walde.christian@gmail.com>
 464
 465 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
 466
 467 mstratman: Mark A. Stratman <stratman@gmail.com>
 468
 469 ned: Neil de Carteret
 470
 471 nigel: Nigel Metheringham <nigelm@cpan.org>
 472
 473 ningu: David Kamholz <dkamholz@cpan.org>
 474
 475 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
 476
 477 norbi: Norbert Buchmuller <norbi@nix.hu>
 478
 479 nuba: Nuba Princigalli <nuba@cpan.org>
 480
 481 Numa: Dan Sully <daniel@cpan.org>
 482
 483 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
 484
 485 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
 486
 487 paulm: Paul Makepeace
 488
 489 penguin: K J Cheetham
 490
 491 perigrin: Chris Prather <chris@prather.org>
 492
 493 peter: Peter Collingbourne <peter@pcc.me.uk>
 494
 495 Peter Valdemar ME<oslash>rch <peter@morch.com>
 496
 497 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
 498
 499 plu: Johannes Plunien <plu@cpan.org>
 500
 501 Possum: Daniel LeWarne <possum@cpan.org>
 502
 503 quicksilver: Jules Bean
 504
 505 rafl: Florian Ragwitz <rafl@debian.org>
 506
 507 rainboxx: Matthias Dietrich <perl@rb.ly>
 508
 509 rbo: Robert Bohne <rbo@cpan.org>
 510
 511 rbuels: Robert Buels <rmb32@cornell.edu>
 512
 513 rdj: Ryan D Johnson <ryan@innerfence.com>
 514
 515 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
 516
 517 rjbs: Ricardo Signes <rjbs@cpan.org>
 518
 519 robkinyon: Rob Kinyon <rkinyon@cpan.org>
 520
 521 Robert Olson <bob@rdolson.org>
 522
 523 moltar: Roman Filippov <romanf@cpan.org>
 524
 525 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
 526
 527 sc_: Just Another Perl Hacker
 528
 529 scotty: Scotty Allen <scotty@scottyallen.com>
 530
 531 semifor: Marc Mims <marc@questright.com>
 532
 533 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
 534
 535 solomon: Jared Johnson <jaredj@nmgi.com>
 536
 537 spb: Stephen Bennett <stephen@freenode.net>
 538
 539 Squeeks <squeek@cpan.org>
 540
 541 sszabo: Stephan Szabo <sszabo@bigpanda.com>
 542
 543 talexb: Alex Beamish <talexb@gmail.com>
 544
 545 tamias: Ronald J Kimball <rjk@tamias.net>
 546
 547 teejay : Aaron Trevena <teejay@cpan.org>
 548
 549 Todd Lipcon
 550
 551 Tom Hukins
 552
 553 tonvoon: Ton Voon <tonvoon@cpan.org>
 554
 555 triode: Pete Gamache <gamache@cpan.org>
 556
 557 typester: Daisuke Murase <typester@cpan.org>
 558
 559 victori: Victor Igumnov <victori@cpan.org>
 560
 561 wdh: Will Hawes
 562
 563 wesm: Wes Malone <wes@mitsi.com>
 564
 565 willert: Sebastian Willert <willert@cpan.org>
 566
 567 wreis: Wallace Reis <wreis@cpan.org>
 568
 569 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
 570
 571 yrlnry: Mark Jason Dominus <mjd@plover.com>
 572
 573 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
 574
 575 =head1 COPYRIGHT
 576
 577 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
 578 as listed above.
 579
 580 =head1 LICENSE
 581
 582 This library is free software and may be distributed under the same terms
 583 as perl itself.