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