lib/DBIx/Class.pm

   1 package DBIx::Class;
   2
   3 use strict;
   4 use warnings;
   5
   6 use DBIx::Class::_TempExtlib;
   7
   8 our $VERSION;
   9 # Always remember to do all digits for the version even if they're 0
  10 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
  11 # brain damage and presumably various other packaging systems too
  12
  13 # $VERSION declaration must stay up here, ahead of any other package
  14 # declarations, as to not confuse various modules attempting to determine
  15 # this ones version, whether that be s.c.o. or Module::Metadata, etc
  16 $VERSION = '0.08901';
  17
  18 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
  19
  20 use DBIx::Class::_Util;
  21 use mro 'c3';
  22
  23 use DBIx::Class::Optional::Dependencies;
  24
  25 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
  26 use DBIx::Class::StartupCheck;
  27 use DBIx::Class::Exception;
  28
  29 __PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
  30 __PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny|^Class::Accessor::Grouped|^Context::Preserve');
  31
  32 sub mk_classdata {
  33   shift->mk_classaccessor(@_);
  34 }
  35
  36 sub mk_classaccessor {
  37   my $self = shift;
  38   $self->mk_group_accessors('inherited', $_[0]);
  39   $self->set_inherited(@_) if @_ > 1;
  40 }
  41
  42 sub component_base_class { 'DBIx::Class' }
  43
  44 sub MODIFY_CODE_ATTRIBUTES {
  45   my ($class,$code,@attrs) = @_;
  46   $class->mk_classdata('__attr_cache' => {})
  47     unless $class->can('__attr_cache');
  48   $class->__attr_cache->{$code} = [@attrs];
  49   return ();
  50 }
  51
  52 sub _attr_cache {
  53   my $self = shift;
  54   my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
  55
  56   return {
  57     %$cache,
  58     %{ $self->maybe::next::method || {} },
  59   };
  60 }
  61
  62 1;
  63
  64 __END__
  65
  66 =encoding UTF-8
  67
  68 =head1 NAME
  69
  70 DBIx::Class - Extensible and flexible object <-> relational mapper.
  71
  72 =head1 WHERE TO START READING
  73
  74 See L<DBIx::Class::Manual::DocMap> for an overview of the exhaustive documentation.
  75 To get the most out of DBIx::Class with the least confusion it is strongly
  76 recommended to read (at the very least) the
  77 L<Manuals|DBIx::Class::Manual::DocMap/Manuals> in the order presented there.
  78
  79 =head1 HOW TO GET HELP
  80
  81 Due to the complexity of its problem domain, DBIx::Class is a relatively
  82 complex framework. After you start using DBIx::Class questions will inevitably
  83 arise. If you are stuck with a problem or have doubts about a particular
  84 approach do not hesitate to contact the community with your questions. The
  85 list below is sorted by "fastest response time":
  86
  87 =over
  88
  89 =item * IRC: irc.perl.org#dbix-class
  90
  91 =for html
  92 <a href="https://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
  93
  94 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
  95
  96 =item * RT Bug Tracker: L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-Class>
  97
  98 =item * Twitter: L<https://www.twitter.com/dbix_class>
  99
 100 =item * Web Site: L<http://www.dbix-class.org/>
 101
 102 =back
 103
 104 =head1 SYNOPSIS
 105
 106 For the very impatient: L<DBIx::Class::Manual::QuickStart>
 107
 108 This code in the next step can be generated automatically from an existing
 109 database, see L<dbicdump> from the distribution C<DBIx-Class-Schema-Loader>.
 110
 111 =head2 Schema classes preparation
 112
 113 Create a schema class called F<MyApp/Schema.pm>:
 114
 115   package MyApp::Schema;
 116   use base qw/DBIx::Class::Schema/;
 117
 118   __PACKAGE__->load_namespaces();
 119
 120   1;
 121
 122 Create a result class to represent artists, who have many CDs, in
 123 F<MyApp/Schema/Result/Artist.pm>:
 124
 125 See L<DBIx::Class::ResultSource> for docs on defining result classes.
 126
 127   package MyApp::Schema::Result::Artist;
 128   use base qw/DBIx::Class::Core/;
 129
 130   __PACKAGE__->table('artist');
 131   __PACKAGE__->add_columns(qw/ artistid name /);
 132   __PACKAGE__->set_primary_key('artistid');
 133   __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');
 134
 135   1;
 136
 137 A result class to represent a CD, which belongs to an artist, in
 138 F<MyApp/Schema/Result/CD.pm>:
 139
 140   package MyApp::Schema::Result::CD;
 141   use base qw/DBIx::Class::Core/;
 142
 143   __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
 144   __PACKAGE__->table('cd');
 145   __PACKAGE__->add_columns(qw/ cdid artistid title year /);
 146   __PACKAGE__->set_primary_key('cdid');
 147   __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
 148
 149   1;
 150
 151 =head2 API usage
 152
 153 Then you can use these classes in your application's code:
 154
 155   # Connect to your database.
 156   use MyApp::Schema;
 157   my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
 158
 159   # Query for all artists and put them in an array,
 160   # or retrieve them as a result set object.
 161   # $schema->resultset returns a DBIx::Class::ResultSet
 162   my @all_artists = $schema->resultset('Artist')->all;
 163   my $all_artists_rs = $schema->resultset('Artist');
 164
 165   # Output all artists names
 166   # $artist here is a DBIx::Class::Row, which has accessors
 167   # for all its columns. Rows are also subclasses of your Result class.
 168   foreach $artist (@all_artists) {
 169     print $artist->name, "\n";
 170   }
 171
 172   # Create a result set to search for artists.
 173   # This does not query the DB.
 174   my $johns_rs = $schema->resultset('Artist')->search(
 175     # Build your WHERE using an SQL::Abstract structure:
 176     { name => { like => 'John%' } }
 177   );
 178
 179   # Execute a joined query to get the cds.
 180   my @all_john_cds = $johns_rs->search_related('cds')->all;
 181
 182   # Fetch the next available row.
 183   my $first_john = $johns_rs->next;
 184
 185   # Specify ORDER BY on the query.
 186   my $first_john_cds_by_title_rs = $first_john->cds(
 187     undef,
 188     { order_by => 'title' }
 189   );
 190
 191   # Create a result set that will fetch the artist data
 192   # at the same time as it fetches CDs, using only one query.
 193   my $millennium_cds_rs = $schema->resultset('CD')->search(
 194     { year => 2000 },
 195     { prefetch => 'artist' }
 196   );
 197
 198   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
 199   my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
 200
 201   # new() makes a Result object but doesnt insert it into the DB.
 202   # create() is the same as new() then insert().
 203   my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
 204   $new_cd->artist($cd->artist);
 205   $new_cd->insert; # Auto-increment primary key filled in after INSERT
 206   $new_cd->title('Fork');
 207
 208   $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
 209
 210   # change the year of all the millennium CDs at once
 211   $millennium_cds_rs->update({ year => 2002 });
 212
 213 =head1 DESCRIPTION
 214
 215 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
 216 (with a compatibility layer as a springboard for porting) and a resultset API
 217 that allows abstract encapsulation of database operations. It aims to make
 218 representing queries in your code as perl-ish as possible while still
 219 providing access to as many of the capabilities of the database as possible,
 220 including retrieving related records from multiple tables in a single query,
 221 C<JOIN>, C<LEFT JOIN>, C<COUNT>, C<DISTINCT>, C<GROUP BY>, C<ORDER BY> and
 222 C<HAVING> support.
 223
 224 DBIx::Class can handle multi-column primary and foreign keys, complex
 225 queries and database-level paging, and does its best to only query the
 226 database in order to return something you've directly asked for. If a
 227 resultset is used as an iterator it only fetches rows off the statement
 228 handle as requested in order to minimise memory usage. It has auto-increment
 229 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
 230 known to be used in production on at least the first four, and is fork-
 231 and thread-safe out of the box (although
 232 L<your DBD may not be|DBI/Threads and Thread Safety>).
 233
 234 This project is still under rapid development, so large new features may be
 235 marked B<experimental> - such APIs are still usable but may have edge bugs.
 236 Failing test cases are I<always> welcome and point releases are put out rapidly
 237 as bugs are found and fixed.
 238
 239 We do our best to maintain full backwards compatibility for published
 240 APIs, since DBIx::Class is used in production in many organisations,
 241 and even backwards incompatible changes to non-published APIs will be fixed
 242 if they're reported and doing so doesn't cost the codebase anything.
 243
 244 The test suite is quite substantial, and several developer releases
 245 are generally made to CPAN before the branch for the next release is
 246 merged back to trunk for a major release.
 247
 248 =head1 HOW TO CONTRIBUTE
 249
 250 Contributions are always welcome, in all usable forms (we especially
 251 welcome documentation improvements). The delivery methods include git-
 252 or unified-diff formatted patches, GitHub pull requests, or plain bug
 253 reports either via RT or the Mailing list. Contributors are generally
 254 granted full access to the official repository after their first patch
 255 passes successful review.
 256
 257 =for comment
 258 FIXME: Getty, frew and jnap need to get off their asses and finish the contrib section so we can link it here ;)
 259
 260 This project is maintained in a git repository. The code and related tools are
 261 accessible at the following locations:
 262
 263 =over
 264
 265 =item * Official repo: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
 266
 267 =item * Official gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
 268
 269 =item * GitHub mirror: L<https://github.com/dbsrgits/DBIx-Class>
 270
 271 =item * Authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/DBIx-Class.git>
 272
 273 =item * Travis-CI log: L<https://travis-ci.org/dbsrgits/dbix-class/builds>
 274
 275 =for html
 276 &#x21AA; Stable branch CI status: <img src="https://secure.travis-ci.org/dbsrgits/dbix-class.png?branch=master"></img>
 277
 278 =back
 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 andrewalker: Andre Walker <andre@andrewalker.net>
 306
 307 andyg: Andy Grundman <andy@hybridized.org>
 308
 309 ank: Andres Kievsky
 310
 311 arc: Aaron Crane <arc@cpan.org>
 312
 313 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
 314
 315 ash: Ash Berlin <ash@cpan.org>
 316
 317 bert: Norbert Csongrádi <bert@cpan.org>
 318
 319 blblack: Brandon L. Black <blblack@gmail.com>
 320
 321 bluefeet: Aran Deltac <bluefeet@cpan.org>
 322
 323 bphillips: Brian Phillips <bphillips@cpan.org>
 324
 325 boghead: Bryan Beeley <cpan@beeley.org>
 326
 327 brd: Brad Davis <brd@FreeBSD.org>
 328
 329 bricas: Brian Cassidy <bricas@cpan.org>
 330
 331 brunov: Bruno Vecchi <vecchi.b@gmail.com>
 332
 333 caelum: Rafael Kitover <rkitover@cpan.org>
 334
 335 caldrin: Maik Hentsche <maik.hentsche@amd.com>
 336
 337 castaway: Jess Robinson
 338
 339 claco: Christopher H. Laco
 340
 341 clkao: CL Kao
 342
 343 da5id: David Jack Olrik <djo@cpan.org>
 344
 345 dariusj: Darius Jokilehto <dariusjokilehto@yahoo.co.uk>
 346
 347 davewood: David Schmidt <davewood@gmx.at>
 348
 349 daxim: Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim@cpan.org>
 350
 351 debolaz: Anders Nor Berle <berle@cpan.org>
 352
 353 dew: Dan Thomas <dan@godders.org>
 354
 355 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
 356
 357 dnm: Justin Wheeler <jwheeler@datademons.com>
 358
 359 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
 360
 361 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
 362
 363 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
 364
 365 edenc: Eden Cardim <edencardim@gmail.com>
 366
 367 ether: Karen Etheridge <ether@cpan.org>
 368
 369 felliott: Fitz Elliott <fitz.elliott@gmail.com>
 370
 371 freetime: Bill Moseley <moseley@hank.org>
 372
 373 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
 374
 375 goraxe: Gordon Irving <goraxe@cpan.org>
 376
 377 gphat: Cory G Watson <gphat@cpan.org>
 378
 379 Grant Street Group L<http://www.grantstreet.com/>
 380
 381 groditi: Guillermo Roditi <groditi@cpan.org>
 382
 383 Haarg: Graham Knop <haarg@haarg.org>
 384
 385 hobbs: Andrew Rodland <arodland@cpan.org>
 386
 387 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
 388
 389 initself: Mike Baas <mike@initselftech.com>
 390
 391 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
 392
 393 jawnsy: Jonathan Yu <jawnsy@cpan.org>
 394
 395 jasonmay: Jason May <jason.a.may@gmail.com>
 396
 397 jesper: Jesper Krogh
 398
 399 jgoulah: John Goulah <jgoulah@cpan.org>
 400
 401 jguenther: Justin Guenther <jguenther@cpan.org>
 402
 403 jhannah: Jay Hannah <jay@jays.net>
 404
 405 jmac: Jason McIntosh <jmac@appleseed-sc.com>
 406
 407 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
 408
 409 jon: Jon Schutz <jjschutz@cpan.org>
 410
 411 jshirley: J. Shirley <jshirley@gmail.com>
 412
 413 kaare: Kaare Rasmussen
 414
 415 konobi: Scott McWhirter
 416
 417 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
 418
 419 lukes: Luke Saunders <luke.saunders@gmail.com>
 420
 421 marcus: Marcus Ramberg <mramberg@cpan.org>
 422
 423 mattlaw: Matt Lawrence
 424
 425 mattp: Matt Phillips <mattp@cpan.org>
 426
 427 michaelr: Michael Reddick <michael.reddick@gmail.com>
 428
 429 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
 430
 431 mithaldu: Christian Walde <walde.christian@gmail.com>
 432
 433 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
 434
 435 mstratman: Mark A. Stratman <stratman@gmail.com>
 436
 437 ned: Neil de Carteret
 438
 439 nigel: Nigel Metheringham <nigelm@cpan.org>
 440
 441 ningu: David Kamholz <dkamholz@cpan.org>
 442
 443 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
 444
 445 norbi: Norbert Buchmuller <norbi@nix.hu>
 446
 447 nuba: Nuba Princigalli <nuba@cpan.org>
 448
 449 Numa: Dan Sully <daniel@cpan.org>
 450
 451 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
 452
 453 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
 454
 455 paulm: Paul Makepeace
 456
 457 penguin: K J Cheetham
 458
 459 perigrin: Chris Prather <chris@prather.org>
 460
 461 peter: Peter Collingbourne <peter@pcc.me.uk>
 462
 463 Peter Siklósi <einon@einon.hu>
 464
 465 Peter Valdemar ME<oslash>rch <peter@morch.com>
 466
 467 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
 468
 469 plu: Johannes Plunien <plu@cpan.org>
 470
 471 Possum: Daniel LeWarne <possum@cpan.org>
 472
 473 quicksilver: Jules Bean
 474
 475 rafl: Florian Ragwitz <rafl@debian.org>
 476
 477 rainboxx: Matthias Dietrich <perl@rb.ly>
 478
 479 rbo: Robert Bohne <rbo@cpan.org>
 480
 481 rbuels: Robert Buels <rmb32@cornell.edu>
 482
 483 rdj: Ryan D Johnson <ryan@innerfence.com>
 484
 485 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
 486
 487 rjbs: Ricardo Signes <rjbs@cpan.org>
 488
 489 robkinyon: Rob Kinyon <rkinyon@cpan.org>
 490
 491 Robert Olson <bob@rdolson.org>
 492
 493 moltar: Roman Filippov <romanf@cpan.org>
 494
 495 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
 496
 497 sc_: Just Another Perl Hacker
 498
 499 scotty: Scotty Allen <scotty@scottyallen.com>
 500
 501 semifor: Marc Mims <marc@questright.com>
 502
 503 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
 504
 505 solomon: Jared Johnson <jaredj@nmgi.com>
 506
 507 spb: Stephen Bennett <stephen@freenode.net>
 508
 509 Squeeks <squeek@cpan.org>
 510
 511 sszabo: Stephan Szabo <sszabo@bigpanda.com>
 512
 513 talexb: Alex Beamish <talexb@gmail.com>
 514
 515 tamias: Ronald J Kimball <rjk@tamias.net>
 516
 517 teejay : Aaron Trevena <teejay@cpan.org>
 518
 519 Todd Lipcon
 520
 521 Tom Hukins
 522
 523 tonvoon: Ton Voon <tonvoon@cpan.org>
 524
 525 triode: Pete Gamache <gamache@cpan.org>
 526
 527 typester: Daisuke Murase <typester@cpan.org>
 528
 529 victori: Victor Igumnov <victori@cpan.org>
 530
 531 wdh: Will Hawes
 532
 533 wesm: Wes Malone <wes@mitsi.com>
 534
 535 willert: Sebastian Willert <willert@cpan.org>
 536
 537 wreis: Wallace Reis <wreis@cpan.org>
 538
 539 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
 540
 541 yrlnry: Mark Jason Dominus <mjd@plover.com>
 542
 543 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
 544
 545 Zefram: Andrew Main <zefram@fysh.org>
 546
 547 =head1 COPYRIGHT
 548
 549 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
 550 as listed above.
 551
 552 =head1 LICENSE
 553
 554 This library is free software and may be distributed under the same terms
 555 as perl itself.