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