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