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