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