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