Up dependency on SQLT (releasing now)
[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
eaab653f 27$VERSION = '0.08099_06';
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
ce4c07df 210ash: Ash Berlin <ash@cpan.org>
211
3d5bd2af 212bert: Norbert Csongradi <bert@cpan.org>
213
967a4c40 214blblack: Brandon L. Black <blblack@gmail.com>
3942ab4d 215
62eb8fe8 216bluefeet: Aran Deltac <bluefeet@cpan.org>
217
bcb8f3ed 218bricas: Brian Cassidy <bricas@cpan.org>
219
281719d2 220caelum: Rafael Kitover <rkitover@cpan.org>
221
d3b0e369 222captainL: Luke Saunders <luke.saunders@gmail.com>
223
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
d3b0e369 246jesper: Jesper Krogh
5fb0c64c 247
4a743a00 248jgoulah: John Goulah <jgoulah@cpan.org>
249
102a2984 250jguenther: Justin Guenther <jguenther@cpan.org>
d7c4c15c 251
8b93a938 252jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
253
11736b4c 254jon: Jon Schutz <jjschutz@cpan.org>
255
1aec4bac 256jshirley: J. Shirley <jshirley@gmail.com>
257
d3b0e369 258konobi: Scott McWhirter
535fc2ee 259
709ea492 260marcus: Marcus Ramberg <mramberg@cpan.org>
261
114780ee 262mattlaw: Matt Lawrence
263
77e7e47d 264ned: Neil de Carteret
265
266bdcc3 266nigel: Nigel Metheringham <nigelm@cpan.org>
6565b410 267
d3b0e369 268ningu: David Kamholz <dkamholz@cpan.org>
269
270Numa: Dan Sully <daniel@cpan.org>
271
bf356c54 272oyse: Øystein Torget <oystein.torget@dnv.com>
273
266bdcc3 274paulm: Paul Makepeace
4763f4b7 275
d3b0e369 276penguin: K J Cheetham
277
8cfef6f5 278perigrin: Chris Prather <chris@prather.org>
279
266bdcc3 280phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
a53b95f1 281
56fadd8f 282plu: Johannes Plunien <plu@cpan.org>
283
d3b0e369 284quicksilver: Jules Bean
022e0893 285
4ed01b34 286rafl: Florian Ragwitz <rafl@debian.org>
287
0da8b7da 288rdj: Ryan D Johnson <ryan@innerfence.com>
289
28ad4c43 290ribasushi: Peter Rabbitson <rabbit+dbic@rabbit.us>
d76e282a 291
b487918c 292rjbs: Ricardo Signes <rjbs@cpan.org>
293
d3b0e369 294sc_: Just Another Perl Hacker
ba606e58 295
266bdcc3 296scotty: Scotty Allen <scotty@scottyallen.com>
181a28f4 297
1c133e22 298semifor: Marc Mims <marc@questright.com>
299
637ca936 300sszabo: Stephan Szabo <sszabo@bigpanda.com>
301
386c2272 302teejay : Aaron Trevena <teejay@cpan.org>
303
84e3c114 304Todd Lipcon
e063fe2c 305
6eb6264e 306Tom Hukins
307
d3b0e369 308typester: Daisuke Murase <typester@cpan.org>
c0e7b4e5 309
4740bdb7 310victori: Victor Igumnov <victori@cpan.org>
311
d3b0e369 312wdh: Will Hawes
4c248161 313
00c03ced 314willert: Sebastian Willert <willert@cpan.org>
315
d3b0e369 316zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
78060df8 317
35210f02 318norbi: Norbert Buchmuller <norbi@nix.hu>
319
34d52be2 320=head1 LICENSE
321
322You may distribute this code under the same terms as Perl itself.
323
324=cut