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