Merge 'DBIx-Class-current' into 'versioning'
[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/;
8
9sub mk_classdata {
10 my $self = shift;
11 $self->mk_group_accessors('inherited', $_[0]);
12 $self->set_inherited(@_) if @_ > 1;
13}
3c0068c1 14
7411204b 15sub component_base_class { 'DBIx::Class' }
227d4dee 16
95da6f35 17# Always remember to do all digits for the version even if they're 0
18# i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
19# brain damage and presumably various other packaging systems too
20
5378bbdd 21$VERSION = '0.07999_01';
b8777a0d 22
f0750722 23sub MODIFY_CODE_ATTRIBUTES {
b5d2c57f 24 my ($class,$code,@attrs) = @_;
25 $class->mk_classdata('__attr_cache' => {})
26 unless $class->can('__attr_cache');
27 $class->__attr_cache->{$code} = [@attrs];
28 return ();
f0750722 29}
30
da95b45f 31sub _attr_cache {
b5d2c57f 32 my $self = shift;
33 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
34 my $rest = eval { $self->next::method };
35 return $@ ? $cache : { %$cache, %$rest };
da95b45f 36}
37
ea2e61bf 381;
34d52be2 39
75d07914 40=head1 NAME
34d52be2 41
7e4b2f59 42DBIx::Class - Extensible and flexible object <-> relational mapper.
34d52be2 43
44=head1 SYNOPSIS
45
2053ab2a 46Create a schema class called DB/Main.pm:
34d52be2 47
a0638a7b 48 package DB::Main;
49 use base qw/DBIx::Class::Schema/;
34d52be2 50
a0638a7b 51 __PACKAGE__->load_classes();
daec44b8 52
a0638a7b 53 1;
daec44b8 54
2053ab2a 55Create a table class to represent artists, who have many CDs, in DB/Main/Artist.pm:
daec44b8 56
a0638a7b 57 package DB::Main::Artist;
58 use base qw/DBIx::Class/;
daec44b8 59
a0638a7b 60 __PACKAGE__->load_components(qw/PK::Auto Core/);
61 __PACKAGE__->table('artist');
62 __PACKAGE__->add_columns(qw/ artistid name /);
63 __PACKAGE__->set_primary_key('artistid');
2053ab2a 64 __PACKAGE__->has_many(cds => 'DB::Main::CD');
daec44b8 65
a0638a7b 66 1;
daec44b8 67
2053ab2a 68A table class to represent a CD, which belongs to an artist, in DB/Main/CD.pm:
39fe0e65 69
a0638a7b 70 package DB::Main::CD;
71 use base qw/DBIx::Class/;
39fe0e65 72
a0638a7b 73 __PACKAGE__->load_components(qw/PK::Auto Core/);
74 __PACKAGE__->table('cd');
2053ab2a 75 __PACKAGE__->add_columns(qw/ cdid artist title year /);
a0638a7b 76 __PACKAGE__->set_primary_key('cdid');
2053ab2a 77 __PACKAGE__->belongs_to(artist => 'DB::Main::Artist');
39fe0e65 78
a0638a7b 79 1;
39fe0e65 80
a0638a7b 81Then you can use these classes in your application's code:
39fe0e65 82
a0638a7b 83 # Connect to your database.
2053ab2a 84 use DB::Main;
85 my $schema = DB::Main->connect($dbi_dsn, $user, $pass, \%dbi_params);
a0638a7b 86
87 # Query for all artists and put them in an array,
88 # or retrieve them as a result set object.
2053ab2a 89 my @all_artists = $schema->resultset('Artist')->all;
90 my $all_artists_rs = $schema->resultset('Artist');
126042ee 91
a0638a7b 92 # Create a result set to search for artists.
86beca1d 93 # This does not query the DB.
2053ab2a 94 my $johns_rs = $schema->resultset('Artist')->search(
6576ef54 95 # Build your WHERE using an SQL::Abstract structure:
2053ab2a 96 { name => { like => 'John%' } }
a0638a7b 97 );
39fe0e65 98
2053ab2a 99 # Execute a joined query to get the cds.
a0638a7b 100 my @all_john_cds = $johns_rs->search_related('cds')->all;
448c8424 101
2053ab2a 102 # Fetch only the next row.
a0638a7b 103 my $first_john = $johns_rs->next;
448c8424 104
2053ab2a 105 # Specify ORDER BY on the query.
a0638a7b 106 my $first_john_cds_by_title_rs = $first_john->cds(
107 undef,
108 { order_by => 'title' }
109 );
448c8424 110
2053ab2a 111 # Create a result set that will fetch the artist relationship
112 # at the same time as it fetches CDs, using only one query.
884559b1 113 my $millennium_cds_rs = $schema->resultset('CD')->search(
a0638a7b 114 { year => 2000 },
115 { prefetch => 'artist' }
116 );
448c8424 117
880a1a0c 118 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
f183eccd 119 my $cd_artist_name = $cd->artist->name; # Already has the data so no query
076652e8 120
884559b1 121 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
f183eccd 122 $new_cd->artist($cd->artist);
f183eccd 123 $new_cd->insert; # Auto-increment primary key filled in after INSERT
f183eccd 124 $new_cd->title('Fork');
125
884559b1 126 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
f183eccd 127
880a1a0c 128 $millennium_cds_rs->update({ year => 2002 }); # Single-query bulk update
f183eccd 129
130=head1 DESCRIPTION
131
132This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
a0638a7b 133(and a compatibility layer as a springboard for porting) and a resultset API
f183eccd 134that allows abstract encapsulation of database operations. It aims to make
135representing queries in your code as perl-ish as possible while still
a0638a7b 136providing access to as many of the capabilities of the database as possible,
f183eccd 137including retrieving related records from multiple tables in a single query,
138JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support.
139
140DBIx::Class can handle multi-column primary and foreign keys, complex
141queries and database-level paging, and does its best to only query the
75d07914 142database in order to return something you've directly asked for. If a
143resultset is used as an iterator it only fetches rows off the statement
144handle as requested in order to minimise memory usage. It has auto-increment
2053ab2a 145support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
146known to be used in production on at least the first four, and is fork-
75d07914 147and thread-safe out of the box (although your DBD may not be).
f183eccd 148
149This project is still under rapid development, so features added in the
2053ab2a 150latest major release may not work 100% yet -- check the Changes if you run
f183eccd 151into trouble, and beware of anything explicitly marked EXPERIMENTAL. Failing
152test cases are *always* welcome and point releases are put out rapidly as
153bugs are found and fixed.
154
86beca1d 155Even so, we do our best to maintain full backwards compatibility for published
2053ab2a 156APIs, since DBIx::Class is used in production in a number of organisations.
157The test suite is quite substantial, and several developer releases are
86beca1d 158generally made to CPAN before the -current branch is merged back to trunk for
159a major release.
f183eccd 160
2053ab2a 161The community can be found via:
f183eccd 162
163 Mailing list: http://lists.rawmode.org/mailman/listinfo/dbix-class/
164
165 SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/
166
167 Wiki: http://dbix-class.shadowcatsystems.co.uk/
168
169 IRC: irc.perl.org#dbix-class
170
171=head1 WHERE TO GO NEXT
172
2ca930b4 173L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
174the modules where you will find documentation.
076652e8 175
3942ab4d 176=head1 AUTHOR
34d52be2 177
266bdcc3 178mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
34d52be2 179
3942ab4d 180=head1 CONTRIBUTORS
181
266bdcc3 182abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
84e3c114 183
266bdcc3 184andyg: Andy Grundman <andy@hybridized.org>
3942ab4d 185
266bdcc3 186ank: Andres Kievsky
3942ab4d 187
ce4c07df 188ash: Ash Berlin <ash@cpan.org>
189
967a4c40 190blblack: Brandon L. Black <blblack@gmail.com>
3942ab4d 191
62eb8fe8 192bluefeet: Aran Deltac <bluefeet@cpan.org>
193
d3b0e369 194captainL: Luke Saunders <luke.saunders@gmail.com>
195
196castaway: Jess Robinson
3942ab4d 197
266bdcc3 198claco: Christopher H. Laco
ccb9c9b1 199
266bdcc3 200clkao: CL Kao
3942ab4d 201
266bdcc3 202dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
ccb9c9b1 203
d3b0e369 204draven: Marcus Ramberg <mramberg@cpan.org>
4685e006 205
266bdcc3 206dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
4685e006 207
5cffe785 208dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
8fe164b9 209
d3b0e369 210gphat: Cory G Watson <gphat@cpan.org>
ad3d2d7c 211
d3b0e369 212jesper: Jesper Krogh
5fb0c64c 213
102a2984 214jguenther: Justin Guenther <jguenther@cpan.org>
d7c4c15c 215
d3b0e369 216konobi: Scott McWhirter
535fc2ee 217
d3b0e369 218LTJake: Brian Cassidy <bricas@cpan.org>
103e3e03 219
266bdcc3 220nigel: Nigel Metheringham <nigelm@cpan.org>
6565b410 221
d3b0e369 222ningu: David Kamholz <dkamholz@cpan.org>
223
224Numa: Dan Sully <daniel@cpan.org>
225
266bdcc3 226paulm: Paul Makepeace
4763f4b7 227
d3b0e369 228penguin: K J Cheetham
229
266bdcc3 230phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
a53b95f1 231
d3b0e369 232quicksilver: Jules Bean
022e0893 233
d3b0e369 234sc_: Just Another Perl Hacker
ba606e58 235
266bdcc3 236scotty: Scotty Allen <scotty@scottyallen.com>
181a28f4 237
637ca936 238sszabo: Stephan Szabo <sszabo@bigpanda.com>
239
84e3c114 240Todd Lipcon
e063fe2c 241
d3b0e369 242typester: Daisuke Murase <typester@cpan.org>
c0e7b4e5 243
d3b0e369 244wdh: Will Hawes
4c248161 245
00c03ced 246willert: Sebastian Willert <willert@cpan.org>
247
d3b0e369 248zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
78060df8 249
34d52be2 250=head1 LICENSE
251
252You may distribute this code under the same terms as Perl itself.
253
254=cut