Added note about prefetch and has_many related objects
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class.pm
CommitLineData
ea2e61bf 1package DBIx::Class;
2
5d283305 3use strict;
4use warnings;
5
329d7385 6use MRO::Compat;
7
5d283305 8use vars qw($VERSION);
48a76fcf 9use base qw/Class::C3::Componentised Class::Accessor::Grouped/;
11736b4c 10use DBIx::Class::StartupCheck;
3e110410 11
ade0fe3b 12sub mk_classdata {
77d518d1 13 shift->mk_classaccessor(@_);
14}
15
16sub mk_classaccessor {
17 my $self = shift;
ade0fe3b 18 $self->mk_group_accessors('inherited', $_[0]);
77d518d1 19 $self->set_inherited(@_) if @_ > 1;
3e110410 20}
3c0068c1 21
7411204b 22sub component_base_class { 'DBIx::Class' }
227d4dee 23
95da6f35 24# Always remember to do all digits for the version even if they're 0
25# i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
26# brain damage and presumably various other packaging systems too
57cf1a59 27$VERSION = '0.08114';
748ab0dc 28
29$VERSION = eval $VERSION; # numify for warning-free dev releases
b8777a0d 30
f0750722 31sub MODIFY_CODE_ATTRIBUTES {
b5d2c57f 32 my ($class,$code,@attrs) = @_;
33 $class->mk_classdata('__attr_cache' => {})
34 unless $class->can('__attr_cache');
35 $class->__attr_cache->{$code} = [@attrs];
36 return ();
f0750722 37}
38
da95b45f 39sub _attr_cache {
b5d2c57f 40 my $self = shift;
41 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
42 my $rest = eval { $self->next::method };
43 return $@ ? $cache : { %$cache, %$rest };
da95b45f 44}
45
ea2e61bf 461;
34d52be2 47
75d07914 48=head1 NAME
34d52be2 49
7e4b2f59 50DBIx::Class - Extensible and flexible object <-> relational mapper.
34d52be2 51
3b1c2bbd 52=head1 GETTING HELP/SUPPORT
53
54The community can be found via:
55
56 Mailing list: http://lists.scsys.co.uk/mailman/listinfo/dbix-class/
57
58 SVN: http://dev.catalyst.perl.org/repos/bast/DBIx-Class/
59
60 SVNWeb: http://dev.catalyst.perl.org/svnweb/bast/browse/DBIx-Class/
61
62 IRC: irc.perl.org#dbix-class
63
34d52be2 64=head1 SYNOPSIS
65
bd077b47 66Create a schema class called MyDB/Schema.pm:
34d52be2 67
bd077b47 68 package MyDB::Schema;
a0638a7b 69 use base qw/DBIx::Class::Schema/;
34d52be2 70
f0bb26f3 71 __PACKAGE__->load_namespaces();
daec44b8 72
a0638a7b 73 1;
daec44b8 74
30e1753a 75Create a result class to represent artists, who have many CDs, in
f0bb26f3 76MyDB/Schema/Result/Artist.pm:
daec44b8 77
30e1753a 78See L<DBIx::Class::ResultSource> for docs on defining result classes.
79
f0bb26f3 80 package MyDB::Schema::Result::Artist;
a0638a7b 81 use base qw/DBIx::Class/;
daec44b8 82
bd077b47 83 __PACKAGE__->load_components(qw/Core/);
a0638a7b 84 __PACKAGE__->table('artist');
85 __PACKAGE__->add_columns(qw/ artistid name /);
86 __PACKAGE__->set_primary_key('artistid');
f0bb26f3 87 __PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD');
daec44b8 88
a0638a7b 89 1;
daec44b8 90
30e1753a 91A result class to represent a CD, which belongs to an artist, in
f0bb26f3 92MyDB/Schema/Result/CD.pm:
39fe0e65 93
f0bb26f3 94 package MyDB::Schema::Result::CD;
a0638a7b 95 use base qw/DBIx::Class/;
39fe0e65 96
bd077b47 97 __PACKAGE__->load_components(qw/Core/);
a0638a7b 98 __PACKAGE__->table('cd');
bd077b47 99 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
a0638a7b 100 __PACKAGE__->set_primary_key('cdid');
bd077b47 101 __PACKAGE__->belongs_to(artist => 'MyDB::Schema::Artist', 'artistid');
39fe0e65 102
a0638a7b 103 1;
39fe0e65 104
a0638a7b 105Then you can use these classes in your application's code:
39fe0e65 106
a0638a7b 107 # Connect to your database.
bd077b47 108 use MyDB::Schema;
109 my $schema = MyDB::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
a0638a7b 110
111 # Query for all artists and put them in an array,
112 # or retrieve them as a result set object.
30e1753a 113 # $schema->resultset returns a DBIx::Class::ResultSet
2053ab2a 114 my @all_artists = $schema->resultset('Artist')->all;
115 my $all_artists_rs = $schema->resultset('Artist');
126042ee 116
30e1753a 117 # Output all artists names
4e8ffded 118 # $artist here is a DBIx::Class::Row, which has accessors
16ccb4fe 119 # for all its columns. Rows are also subclasses of your Result class.
30e1753a 120 foreach $artist (@artists) {
121 print $artist->name, "\n";
122 }
123
a0638a7b 124 # Create a result set to search for artists.
86beca1d 125 # This does not query the DB.
2053ab2a 126 my $johns_rs = $schema->resultset('Artist')->search(
6576ef54 127 # Build your WHERE using an SQL::Abstract structure:
2053ab2a 128 { name => { like => 'John%' } }
a0638a7b 129 );
39fe0e65 130
2053ab2a 131 # Execute a joined query to get the cds.
a0638a7b 132 my @all_john_cds = $johns_rs->search_related('cds')->all;
448c8424 133
f0bb26f3 134 # Fetch the next available row.
a0638a7b 135 my $first_john = $johns_rs->next;
448c8424 136
2053ab2a 137 # Specify ORDER BY on the query.
a0638a7b 138 my $first_john_cds_by_title_rs = $first_john->cds(
139 undef,
140 { order_by => 'title' }
141 );
448c8424 142
bd077b47 143 # Create a result set that will fetch the artist data
2053ab2a 144 # at the same time as it fetches CDs, using only one query.
884559b1 145 my $millennium_cds_rs = $schema->resultset('CD')->search(
a0638a7b 146 { year => 2000 },
147 { prefetch => 'artist' }
148 );
448c8424 149
880a1a0c 150 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
bd077b47 151 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
076652e8 152
264f1571 153 # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
154 # create() is the same as new() then insert().
884559b1 155 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
f183eccd 156 $new_cd->artist($cd->artist);
f183eccd 157 $new_cd->insert; # Auto-increment primary key filled in after INSERT
f183eccd 158 $new_cd->title('Fork');
159
884559b1 160 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
f183eccd 161
bd077b47 162 # change the year of all the millennium CDs at once
163 $millennium_cds_rs->update({ year => 2002 });
f183eccd 164
165=head1 DESCRIPTION
166
167This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
bd077b47 168(with a compatibility layer as a springboard for porting) and a resultset API
f183eccd 169that allows abstract encapsulation of database operations. It aims to make
170representing queries in your code as perl-ish as possible while still
a0638a7b 171providing access to as many of the capabilities of the database as possible,
f183eccd 172including retrieving related records from multiple tables in a single query,
bd077b47 173JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
f183eccd 174
175DBIx::Class can handle multi-column primary and foreign keys, complex
176queries and database-level paging, and does its best to only query the
75d07914 177database in order to return something you've directly asked for. If a
178resultset is used as an iterator it only fetches rows off the statement
179handle as requested in order to minimise memory usage. It has auto-increment
2053ab2a 180support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
181known to be used in production on at least the first four, and is fork-
75d07914 182and thread-safe out of the box (although your DBD may not be).
f183eccd 183
dfccde48 184This project is still under rapid development, so large new features may be
185marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
186Failing test cases are *always* welcome and point releases are put out rapidly
187as bugs are found and fixed.
188
189We do our best to maintain full backwards compatibility for published
190APIs, since DBIx::Class is used in production in many organisations,
191and even backwards incompatible changes to non-published APIs will be fixed
192if they're reported and doing so doesn't cost the codebase anything.
193
264f1571 194The test suite is quite substantial, and several developer releases
195are generally made to CPAN before the branch for the next release is
196merged back to trunk for a major release.
f183eccd 197
f183eccd 198=head1 WHERE TO GO NEXT
199
2ca930b4 200L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
201the modules where you will find documentation.
076652e8 202
3942ab4d 203=head1 AUTHOR
34d52be2 204
266bdcc3 205mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
34d52be2 206
dfccde48 207(I mostly consider myself "project founder" these days but the AUTHOR heading
208is traditional :)
209
3942ab4d 210=head1 CONTRIBUTORS
211
266bdcc3 212abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
84e3c114 213
6d84db2c 214aherzog: Adam Herzog <adam@herzogdesigns.com>
215
266bdcc3 216andyg: Andy Grundman <andy@hybridized.org>
3942ab4d 217
266bdcc3 218ank: Andres Kievsky
3942ab4d 219
624764ae 220arcanez: Justin Hunter <justin.d.hunter@gmail.com>
221
ce4c07df 222ash: Ash Berlin <ash@cpan.org>
223
3d5bd2af 224bert: Norbert Csongradi <bert@cpan.org>
225
967a4c40 226blblack: Brandon L. Black <blblack@gmail.com>
3942ab4d 227
62eb8fe8 228bluefeet: Aran Deltac <bluefeet@cpan.org>
229
bcb8f3ed 230bricas: Brian Cassidy <bricas@cpan.org>
231
3d7e3e05 232brunov: Bruno Vecchi <vecchi.b@gmail.com>
233
281719d2 234caelum: Rafael Kitover <rkitover@cpan.org>
235
d3b0e369 236castaway: Jess Robinson
3942ab4d 237
266bdcc3 238claco: Christopher H. Laco
ccb9c9b1 239
266bdcc3 240clkao: CL Kao
3942ab4d 241
e21dfd6a 242da5id: David Jack Olrik <djo@cpan.org>
18360aed 243
13de943d 244debolaz: Anders Nor Berle <berle@cpan.org>
245
266bdcc3 246dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
ccb9c9b1 247
9382ad07 248dnm: Justin Wheeler <jwheeler@datademons.com>
249
266bdcc3 250dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
4685e006 251
5cffe785 252dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
8fe164b9 253
ade0fe3b 254frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
255
d3b0e369 256gphat: Cory G Watson <gphat@cpan.org>
ad3d2d7c 257
e758ffe6 258groditi: Guillermo Roditi <groditi@cpan.org>
259
5d779578 260ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
261
bee21976 262jasonmay: Jason May <jason.a.may@gmail.com>
263
d3b0e369 264jesper: Jesper Krogh
5fb0c64c 265
4a743a00 266jgoulah: John Goulah <jgoulah@cpan.org>
267
102a2984 268jguenther: Justin Guenther <jguenther@cpan.org>
d7c4c15c 269
8b93a938 270jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
271
11736b4c 272jon: Jon Schutz <jjschutz@cpan.org>
273
1aec4bac 274jshirley: J. Shirley <jshirley@gmail.com>
275
d3b0e369 276konobi: Scott McWhirter
535fc2ee 277
4367679a 278lukes: Luke Saunders <luke.saunders@gmail.com>
279
709ea492 280marcus: Marcus Ramberg <mramberg@cpan.org>
281
114780ee 282mattlaw: Matt Lawrence
283
58755bba 284michaelr: Michael Reddick <michael.reddick@gmail.com>
285
77e7e47d 286ned: Neil de Carteret
287
266bdcc3 288nigel: Nigel Metheringham <nigelm@cpan.org>
6565b410 289
d3b0e369 290ningu: David Kamholz <dkamholz@cpan.org>
291
66cf3a84 292Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
293
20b4c148 294norbi: Norbert Buchmuller <norbi@nix.hu>
295
d3b0e369 296Numa: Dan Sully <daniel@cpan.org>
297
bf356c54 298oyse: Øystein Torget <oystein.torget@dnv.com>
299
266bdcc3 300paulm: Paul Makepeace
4763f4b7 301
d3b0e369 302penguin: K J Cheetham
303
8cfef6f5 304perigrin: Chris Prather <chris@prather.org>
305
14899528 306peter: Peter Collingbourne <peter@pcc.me.uk>
caac1708 307
266bdcc3 308phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
a53b95f1 309
56fadd8f 310plu: Johannes Plunien <plu@cpan.org>
311
d3b0e369 312quicksilver: Jules Bean
022e0893 313
4ed01b34 314rafl: Florian Ragwitz <rafl@debian.org>
315
7ff0dace 316rbuels: Robert Buels <rmb32@cornell.edu>
317
0da8b7da 318rdj: Ryan D Johnson <ryan@innerfence.com>
319
28ad4c43 320ribasushi: Peter Rabbitson <rabbit+dbic@rabbit.us>
d76e282a 321
b487918c 322rjbs: Ricardo Signes <rjbs@cpan.org>
323
6ffb5be5 324robkinyon: Rob Kinyon <rkinyon@cpan.org>
325
d3b0e369 326sc_: Just Another Perl Hacker
ba606e58 327
266bdcc3 328scotty: Scotty Allen <scotty@scottyallen.com>
181a28f4 329
1c133e22 330semifor: Marc Mims <marc@questright.com>
331
20b4c148 332solomon: Jared Johnson <jaredj@nmgi.com>
333
88f937fb 334spb: Stephen Bennett <stephen@freenode.net>
335
637ca936 336sszabo: Stephan Szabo <sszabo@bigpanda.com>
337
386c2272 338teejay : Aaron Trevena <teejay@cpan.org>
339
84e3c114 340Todd Lipcon
e063fe2c 341
6eb6264e 342Tom Hukins
343
d15e3fc5 344triode: Pete Gamache <gamache@cpan.org>
345
d3b0e369 346typester: Daisuke Murase <typester@cpan.org>
c0e7b4e5 347
4740bdb7 348victori: Victor Igumnov <victori@cpan.org>
349
d3b0e369 350wdh: Will Hawes
4c248161 351
00c03ced 352willert: Sebastian Willert <willert@cpan.org>
353
66d2a14e 354wreis: Wallace Reis <wreis@cpan.org>
355
d3b0e369 356zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
78060df8 357
b38e10bd 358=head1 COPYRIGHT
359
360Copyright (c) 2005 - 2009 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
361as listed above.
362
96154ef7 363=head1 LICENSE
364
365This library is free software and may be distributed under the same terms
366as perl itself.
367
34d52be2 368=cut