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