changed the way args are passed to a storage, should make it easier to use existing...
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class.pm
1 package DBIx::Class;
2
3 use strict;
4 use warnings;
5
6 use vars qw($VERSION);
7 use base qw/DBIx::Class::Componentised Class::Accessor::Grouped/;
8 use DBIx::Class::StartupCheck;
9
10
11 sub mk_classdata { 
12   shift->mk_classaccessor(@_);
13 }
14
15 sub mk_classaccessor {
16   my $self = shift;
17   $self->mk_group_accessors('inherited', $_[0]); 
18   $self->set_inherited(@_) if @_ > 1;
19 }
20
21 sub component_base_class { 'DBIx::Class' }
22
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
27 $VERSION = '0.08010';
28
29 sub MODIFY_CODE_ATTRIBUTES {
30   my ($class,$code,@attrs) = @_;
31   $class->mk_classdata('__attr_cache' => {})
32     unless $class->can('__attr_cache');
33   $class->__attr_cache->{$code} = [@attrs];
34   return ();
35 }
36
37 sub _attr_cache {
38   my $self = shift;
39   my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
40   my $rest = eval { $self->next::method };
41   return $@ ? $cache : { %$cache, %$rest };
42 }
43
44 1;
45
46 =head1 NAME
47
48 DBIx::Class - Extensible and flexible object <-> relational mapper.
49
50 =head1 SYNOPSIS
51
52 Create a schema class called DB/Main.pm:
53
54   package DB::Main;
55   use base qw/DBIx::Class::Schema/;
56
57   __PACKAGE__->load_classes();
58
59   1;
60
61 Create a table class to represent artists, who have many CDs, in DB/Main/Artist.pm:
62
63   package DB::Main::Artist;
64   use base qw/DBIx::Class/;
65
66   __PACKAGE__->load_components(qw/PK::Auto Core/);
67   __PACKAGE__->table('artist');
68   __PACKAGE__->add_columns(qw/ artistid name /);
69   __PACKAGE__->set_primary_key('artistid');
70   __PACKAGE__->has_many(cds => 'DB::Main::CD');
71
72   1;
73
74 A table class to represent a CD, which belongs to an artist, in DB/Main/CD.pm:
75
76   package DB::Main::CD;
77   use base qw/DBIx::Class/;
78
79   __PACKAGE__->load_components(qw/PK::Auto Core/);
80   __PACKAGE__->table('cd');
81   __PACKAGE__->add_columns(qw/ cdid artist title year /);
82   __PACKAGE__->set_primary_key('cdid');
83   __PACKAGE__->belongs_to(artist => 'DB::Main::Artist');
84
85   1;
86
87 Then you can use these classes in your application's code:
88
89   # Connect to your database.
90   use DB::Main;
91   my $schema = DB::Main->connect($dbi_dsn, $user, $pass, \%dbi_params);
92
93   # Query for all artists and put them in an array,
94   # or retrieve them as a result set object.
95   my @all_artists = $schema->resultset('Artist')->all;
96   my $all_artists_rs = $schema->resultset('Artist');
97
98   # Create a result set to search for artists.
99   # This does not query the DB.
100   my $johns_rs = $schema->resultset('Artist')->search(
101     # Build your WHERE using an SQL::Abstract structure:
102     { name => { like => 'John%' } }
103   );
104
105   # Execute a joined query to get the cds.
106   my @all_john_cds = $johns_rs->search_related('cds')->all;
107
108   # Fetch only the next row.
109   my $first_john = $johns_rs->next;
110
111   # Specify ORDER BY on the query.
112   my $first_john_cds_by_title_rs = $first_john->cds(
113     undef,
114     { order_by => 'title' }
115   );
116
117   # Create a result set that will fetch the artist relationship
118   # at the same time as it fetches CDs, using only one query.
119   my $millennium_cds_rs = $schema->resultset('CD')->search(
120     { year => 2000 },
121     { prefetch => 'artist' }
122   );
123
124   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
125   my $cd_artist_name = $cd->artist->name; # Already has the data so no query
126
127   # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
128   # create() is the same as new() then insert().
129   my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
130   $new_cd->artist($cd->artist);
131   $new_cd->insert; # Auto-increment primary key filled in after INSERT
132   $new_cd->title('Fork');
133
134   $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
135
136   $millennium_cds_rs->update({ year => 2002 }); # Single-query bulk update
137
138 =head1 DESCRIPTION
139
140 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
141 (and a compatibility layer as a springboard for porting) and a resultset API
142 that allows abstract encapsulation of database operations. It aims to make
143 representing queries in your code as perl-ish as possible while still
144 providing access to as many of the capabilities of the database as possible,
145 including retrieving related records from multiple tables in a single query,
146 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support.
147
148 DBIx::Class can handle multi-column primary and foreign keys, complex
149 queries and database-level paging, and does its best to only query the
150 database in order to return something you've directly asked for. If a
151 resultset is used as an iterator it only fetches rows off the statement
152 handle as requested in order to minimise memory usage. It has auto-increment
153 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
154 known to be used in production on at least the first four, and is fork-
155 and thread-safe out of the box (although your DBD may not be).
156
157 This project is still under rapid development, so large new features may be
158 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
159 Failing test cases are *always* welcome and point releases are put out rapidly
160 as bugs are found and fixed.
161
162 We do our best to maintain full backwards compatibility for published
163 APIs, since DBIx::Class is used in production in many organisations,
164 and even backwards incompatible changes to non-published APIs will be fixed
165 if they're reported and doing so doesn't cost the codebase anything.
166
167 The test suite is quite substantial, and several developer releases
168 are generally made to CPAN before the branch for the next release is
169 merged back to trunk for a major release.
170
171 The community can be found via:
172
173   Mailing list: http://lists.scsys.co.uk/mailman/listinfo/dbix-class/
174
175   SVN: http://dev.catalyst.perl.org/repos/bast/DBIx-Class/
176
177   SVNWeb: http://dev.catalyst.perl.org/svnweb/bast/browse/DBIx-Class/
178
179   IRC: irc.perl.org#dbix-class
180
181 =head1 WHERE TO GO NEXT
182
183 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
184 the modules where you will find documentation.
185
186 =head1 AUTHOR
187
188 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
189
190 (I mostly consider myself "project founder" these days but the AUTHOR heading
191 is traditional :)
192
193 =head1 CONTRIBUTORS
194
195 abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
196
197 aherzog: Adam Herzog <adam@herzogdesigns.com>
198
199 andyg: Andy Grundman <andy@hybridized.org>
200
201 ank: Andres Kievsky
202
203 ash: Ash Berlin <ash@cpan.org>
204
205 bert: Norbert Csongradi <bert@cpan.org>
206
207 blblack: Brandon L. Black <blblack@gmail.com>
208
209 bluefeet: Aran Deltac <bluefeet@cpan.org>
210
211 captainL: Luke Saunders <luke.saunders@gmail.com>
212
213 castaway: Jess Robinson
214
215 claco: Christopher H. Laco
216
217 clkao: CL Kao
218
219 da5id: David Jack Olrik <djo@cpan.org>
220
221 debolaz: Anders Nor Berle <berle@cpan.org>
222
223 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
224
225 dnm: Justin Wheeler <jwheeler@datademons.com>
226
227 draven: Marcus Ramberg <mramberg@cpan.org>
228
229 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
230
231 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
232
233 gphat: Cory G Watson <gphat@cpan.org>
234
235 jesper: Jesper Krogh
236
237 jguenther: Justin Guenther <jguenther@cpan.org>
238
239 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
240
241 jon: Jon Schutz <jjschutz@cpan.org>
242
243 jshirley: J. Shirley <jshirley@gmail.com>
244
245 konobi: Scott McWhirter
246
247 LTJake: Brian Cassidy <bricas@cpan.org>
248
249 mattlaw: Matt Lawrence
250
251 ned: Neil de Carteret
252
253 nigel: Nigel Metheringham <nigelm@cpan.org>
254
255 ningu: David Kamholz <dkamholz@cpan.org>
256
257 Numa: Dan Sully <daniel@cpan.org>
258
259 oyse: Ã˜ystein Torget <oystein.torget@dnv.com>
260
261 paulm: Paul Makepeace
262
263 penguin: K J Cheetham
264
265 perigrin: Chris Prather <chris@prather.org>
266
267 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
268
269 quicksilver: Jules Bean
270
271 rdj: Ryan D Johnson <ryan@innerfence.com>
272
273 sc_: Just Another Perl Hacker
274
275 scotty: Scotty Allen <scotty@scottyallen.com>
276
277 semifor: Marc Mims <marc@questright.com>
278
279 sszabo: Stephan Szabo <sszabo@bigpanda.com>
280
281 teejay : Aaron Trevena <teejay@cpan.org>
282
283 Todd Lipcon
284
285 Tom Hukins
286
287 typester: Daisuke Murase <typester@cpan.org>
288
289 victori: Victor Igumnov <victori@cpan.org>
290
291 wdh: Will Hawes
292
293 willert: Sebastian Willert <willert@cpan.org>
294
295 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
296
297 =head1 LICENSE
298
299 You may distribute this code under the same terms as Perl itself.
300
301 =cut