Attach a storage debugobj lazily instead of at new() time
[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
95965b44 30$VERSION = '0.08124';
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
0ac0af6c 298initself: Mike Baas <mike@initselftech.com>
299
bee21976 300jasonmay: Jason May <jason.a.may@gmail.com>
301
d3b0e369 302jesper: Jesper Krogh
5fb0c64c 303
4a743a00 304jgoulah: John Goulah <jgoulah@cpan.org>
305
102a2984 306jguenther: Justin Guenther <jguenther@cpan.org>
d7c4c15c 307
a14a46e2 308jhannah: Jay Hannah <jay@jays.net>
309
8b93a938 310jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
311
11736b4c 312jon: Jon Schutz <jjschutz@cpan.org>
313
1aec4bac 314jshirley: J. Shirley <jshirley@gmail.com>
315
d3b0e369 316konobi: Scott McWhirter
535fc2ee 317
4367679a 318lukes: Luke Saunders <luke.saunders@gmail.com>
319
709ea492 320marcus: Marcus Ramberg <mramberg@cpan.org>
321
114780ee 322mattlaw: Matt Lawrence
323
58755bba 324michaelr: Michael Reddick <michael.reddick@gmail.com>
325
77e7e47d 326ned: Neil de Carteret
327
266bdcc3 328nigel: Nigel Metheringham <nigelm@cpan.org>
6565b410 329
d3b0e369 330ningu: David Kamholz <dkamholz@cpan.org>
331
66cf3a84 332Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
333
20b4c148 334norbi: Norbert Buchmuller <norbi@nix.hu>
335
48580715 336nuba: Nuba Princigalli <nuba@cpan.org>
337
d3b0e369 338Numa: Dan Sully <daniel@cpan.org>
339
dc571b76 340ovid: Curtis "Ovid" Poe <ovid@cpan.org>
341
bf356c54 342oyse: Øystein Torget <oystein.torget@dnv.com>
343
266bdcc3 344paulm: Paul Makepeace
4763f4b7 345
d3b0e369 346penguin: K J Cheetham
347
8cfef6f5 348perigrin: Chris Prather <chris@prather.org>
349
14899528 350peter: Peter Collingbourne <peter@pcc.me.uk>
caac1708 351
266bdcc3 352phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
a53b95f1 353
56fadd8f 354plu: Johannes Plunien <plu@cpan.org>
355
0c1a4a15 356Possum: Daniel LeWarne <possum@cpan.org>
357
d3b0e369 358quicksilver: Jules Bean
022e0893 359
4ed01b34 360rafl: Florian Ragwitz <rafl@debian.org>
361
0c1a4a15 362rainboxx: Matthias Dietrich <perl@rb.ly>
363
868a7b26 364rbo: Robert Bohne <rbo@cpan.org>
365
7ff0dace 366rbuels: Robert Buels <rmb32@cornell.edu>
367
0da8b7da 368rdj: Ryan D Johnson <ryan@innerfence.com>
369
66b1e361 370ribasushi: Peter Rabbitson <ribasushi@cpan.org>
d76e282a 371
b487918c 372rjbs: Ricardo Signes <rjbs@cpan.org>
373
6ffb5be5 374robkinyon: Rob Kinyon <rkinyon@cpan.org>
375
e4c9f3f0 376Roman: Roman Filippov <romanf@cpan.org>
377
d3b0e369 378sc_: Just Another Perl Hacker
ba606e58 379
266bdcc3 380scotty: Scotty Allen <scotty@scottyallen.com>
181a28f4 381
1c133e22 382semifor: Marc Mims <marc@questright.com>
383
20b4c148 384solomon: Jared Johnson <jaredj@nmgi.com>
385
88f937fb 386spb: Stephen Bennett <stephen@freenode.net>
387
637ca936 388sszabo: Stephan Szabo <sszabo@bigpanda.com>
389
386c2272 390teejay : Aaron Trevena <teejay@cpan.org>
391
84e3c114 392Todd Lipcon
e063fe2c 393
6eb6264e 394Tom Hukins
395
2e4b6d78 396tonvoon: Ton Voon <tonvoon@cpan.org>
397
d15e3fc5 398triode: Pete Gamache <gamache@cpan.org>
399
d3b0e369 400typester: Daisuke Murase <typester@cpan.org>
c0e7b4e5 401
4740bdb7 402victori: Victor Igumnov <victori@cpan.org>
403
d3b0e369 404wdh: Will Hawes
4c248161 405
00c03ced 406willert: Sebastian Willert <willert@cpan.org>
407
66d2a14e 408wreis: Wallace Reis <wreis@cpan.org>
409
d52d4d6e 410yrlnry: Mark Jason Dominus <mjd@plover.com>
411
d3b0e369 412zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
78060df8 413
b38e10bd 414=head1 COPYRIGHT
415
48580715 416Copyright (c) 2005 - 2010 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
b38e10bd 417as listed above.
418
96154ef7 419=head1 LICENSE
420
421This library is free software and may be distributed under the same terms
422as perl itself.
423
34d52be2 424=cut