d681820250ce3069f585d50834123c6016544d5e
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class.pm
1 package DBIx::Class;
2
3 use strict;
4 use warnings;
5
6 use MRO::Compat;
7 use mro 'c3';
8
9 use DBIx::Class::Optional::Dependencies;
10
11 use vars qw($VERSION);
12 use base qw/DBIx::Class::Componentised Class::Accessor::Grouped/;
13 use DBIx::Class::StartupCheck;
14
15 sub mk_classdata {
16   shift->mk_classaccessor(@_);
17 }
18
19 sub mk_classaccessor {
20   my $self = shift;
21   $self->mk_group_accessors('inherited', $_[0]);
22   $self->set_inherited(@_) if @_ > 1;
23 }
24
25 sub component_base_class { 'DBIx::Class' }
26
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
30 $VERSION = '0.08121_01';
31
32 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
33
34 sub MODIFY_CODE_ATTRIBUTES {
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 ();
40 }
41
42 sub _attr_cache {
43   my $self = shift;
44   my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
45
46   return {
47     %$cache,
48     %{ $self->maybe::next::method || {} },
49   };
50 }
51
52 1;
53
54 =head1 NAME
55
56 DBIx::Class - Extensible and flexible object <-> relational mapper.
57
58 =head1 GETTING HELP/SUPPORT
59
60 The community can be found via:
61
62 =over
63
64 =item * IRC: irc.perl.org#dbix-class
65
66 =for html
67 <a href="http://mibbit.com/chat/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
68
69 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
70
71 =item * RT Bug Tracker: L<https://rt.cpan.org/Dist/Display.html?Queue=DBIx-Class>
72
73 =item * gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
74
75 =item * git: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
76
77 =back
78
79 =head1 SYNOPSIS
80
81 Create a schema class called MyDB/Schema.pm:
82
83   package MyDB::Schema;
84   use base qw/DBIx::Class::Schema/;
85
86   __PACKAGE__->load_namespaces();
87
88   1;
89
90 Create a result class to represent artists, who have many CDs, in
91 MyDB/Schema/Result/Artist.pm:
92
93 See L<DBIx::Class::ResultSource> for docs on defining result classes.
94
95   package MyDB::Schema::Result::Artist;
96   use base qw/DBIx::Class::Core/;
97
98   __PACKAGE__->table('artist');
99   __PACKAGE__->add_columns(qw/ artistid name /);
100   __PACKAGE__->set_primary_key('artistid');
101   __PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD');
102
103   1;
104
105 A result class to represent a CD, which belongs to an artist, in
106 MyDB/Schema/Result/CD.pm:
107
108   package MyDB::Schema::Result::CD;
109   use base qw/DBIx::Class::Core/;
110
111   __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
112   __PACKAGE__->table('cd');
113   __PACKAGE__->add_columns(qw/ cdid artistid title year /);
114   __PACKAGE__->set_primary_key('cdid');
115   __PACKAGE__->belongs_to(artist => 'MyDB::Schema::Artist', 'artistid');
116
117   1;
118
119 Then you can use these classes in your application's code:
120
121   # Connect to your database.
122   use MyDB::Schema;
123   my $schema = MyDB::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
124
125   # Query for all artists and put them in an array,
126   # or retrieve them as a result set object.
127   # $schema->resultset returns a DBIx::Class::ResultSet
128   my @all_artists = $schema->resultset('Artist')->all;
129   my $all_artists_rs = $schema->resultset('Artist');
130
131   # Output all artists names
132   # $artist here is a DBIx::Class::Row, which has accessors
133   # for all its columns. Rows are also subclasses of your Result class.
134   foreach $artist (@all_artists) {
135     print $artist->name, "\n";
136   }
137
138   # Create a result set to search for artists.
139   # This does not query the DB.
140   my $johns_rs = $schema->resultset('Artist')->search(
141     # Build your WHERE using an SQL::Abstract structure:
142     { name => { like => 'John%' } }
143   );
144
145   # Execute a joined query to get the cds.
146   my @all_john_cds = $johns_rs->search_related('cds')->all;
147
148   # Fetch the next available row.
149   my $first_john = $johns_rs->next;
150
151   # Specify ORDER BY on the query.
152   my $first_john_cds_by_title_rs = $first_john->cds(
153     undef,
154     { order_by => 'title' }
155   );
156
157   # Create a result set that will fetch the artist data
158   # at the same time as it fetches CDs, using only one query.
159   my $millennium_cds_rs = $schema->resultset('CD')->search(
160     { year => 2000 },
161     { prefetch => 'artist' }
162   );
163
164   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
165   my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
166
167   # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
168   # create() is the same as new() then insert().
169   my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
170   $new_cd->artist($cd->artist);
171   $new_cd->insert; # Auto-increment primary key filled in after INSERT
172   $new_cd->title('Fork');
173
174   $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
175
176   # change the year of all the millennium CDs at once
177   $millennium_cds_rs->update({ year => 2002 });
178
179 =head1 DESCRIPTION
180
181 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
182 (with a compatibility layer as a springboard for porting) and a resultset API
183 that allows abstract encapsulation of database operations. It aims to make
184 representing queries in your code as perl-ish as possible while still
185 providing access to as many of the capabilities of the database as possible,
186 including retrieving related records from multiple tables in a single query,
187 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
188
189 DBIx::Class can handle multi-column primary and foreign keys, complex
190 queries and database-level paging, and does its best to only query the
191 database in order to return something you've directly asked for. If a
192 resultset is used as an iterator it only fetches rows off the statement
193 handle as requested in order to minimise memory usage. It has auto-increment
194 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
195 known to be used in production on at least the first four, and is fork-
196 and thread-safe out of the box (although your DBD may not be).
197
198 This project is still under rapid development, so large new features may be
199 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
200 Failing test cases are *always* welcome and point releases are put out rapidly
201 as bugs are found and fixed.
202
203 We do our best to maintain full backwards compatibility for published
204 APIs, since DBIx::Class is used in production in many organisations,
205 and even backwards incompatible changes to non-published APIs will be fixed
206 if they're reported and doing so doesn't cost the codebase anything.
207
208 The test suite is quite substantial, and several developer releases
209 are generally made to CPAN before the branch for the next release is
210 merged back to trunk for a major release.
211
212 =head1 WHERE TO GO NEXT
213
214 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
215 the modules where you will find documentation.
216
217 =head1 AUTHOR
218
219 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
220
221 (I mostly consider myself "project founder" these days but the AUTHOR heading
222 is traditional :)
223
224 =head1 CONTRIBUTORS
225
226 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
227
228 aherzog: Adam Herzog <adam@herzogdesigns.com>
229
230 Alexander Keusch <cpan@keusch.at>
231
232 amoore: Andrew Moore <amoore@cpan.org>
233
234 andyg: Andy Grundman <andy@hybridized.org>
235
236 ank: Andres Kievsky
237
238 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
239
240 ash: Ash Berlin <ash@cpan.org>
241
242 bert: Norbert Csongradi <bert@cpan.org>
243
244 blblack: Brandon L. Black <blblack@gmail.com>
245
246 bluefeet: Aran Deltac <bluefeet@cpan.org>
247
248 boghead: Bryan Beeley <cpan@beeley.org>
249
250 bricas: Brian Cassidy <bricas@cpan.org>
251
252 brunov: Bruno Vecchi <vecchi.b@gmail.com>
253
254 caelum: Rafael Kitover <rkitover@cpan.org>
255
256 castaway: Jess Robinson
257
258 claco: Christopher H. Laco
259
260 clkao: CL Kao
261
262 da5id: David Jack Olrik <djo@cpan.org>
263
264 debolaz: Anders Nor Berle <berle@cpan.org>
265
266 dew: Dan Thomas <dan@godders.org>
267
268 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
269
270 dnm: Justin Wheeler <jwheeler@datademons.com>
271
272 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
273
274 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
275
276 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
277
278 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
279
280 goraxe: Gordon Irving <goraxe@cpan.org>
281
282 gphat: Cory G Watson <gphat@cpan.org>
283
284 groditi: Guillermo Roditi <groditi@cpan.org>
285
286 Haarg: Graham Knop <haarg@haarg.org>
287
288 hobbs: Andrew Rodland <arodland@cpan.org>
289
290 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
291
292 jasonmay: Jason May <jason.a.may@gmail.com>
293
294 jesper: Jesper Krogh
295
296 jgoulah: John Goulah <jgoulah@cpan.org>
297
298 jguenther: Justin Guenther <jguenther@cpan.org>
299
300 jhannah: Jay Hannah <jay@jays.net>
301
302 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
303
304 jon: Jon Schutz <jjschutz@cpan.org>
305
306 jshirley: J. Shirley <jshirley@gmail.com>
307
308 konobi: Scott McWhirter
309
310 lukes: Luke Saunders <luke.saunders@gmail.com>
311
312 marcus: Marcus Ramberg <mramberg@cpan.org>
313
314 mattlaw: Matt Lawrence
315
316 michaelr: Michael Reddick <michael.reddick@gmail.com>
317
318 ned: Neil de Carteret
319
320 nigel: Nigel Metheringham <nigelm@cpan.org>
321
322 ningu: David Kamholz <dkamholz@cpan.org>
323
324 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
325
326 norbi: Norbert Buchmuller <norbi@nix.hu>
327
328 nuba: Nuba Princigalli <nuba@cpan.org>
329
330 Numa: Dan Sully <daniel@cpan.org>
331
332 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
333
334 oyse: Ã˜ystein Torget <oystein.torget@dnv.com>
335
336 paulm: Paul Makepeace
337
338 penguin: K J Cheetham
339
340 perigrin: Chris Prather <chris@prather.org>
341
342 peter: Peter Collingbourne <peter@pcc.me.uk>
343
344 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
345
346 plu: Johannes Plunien <plu@cpan.org>
347
348 quicksilver: Jules Bean
349
350 rafl: Florian Ragwitz <rafl@debian.org>
351
352 rbo: Robert Bohne <rbo@cpan.org>
353
354 rbuels: Robert Buels <rmb32@cornell.edu>
355
356 rdj: Ryan D Johnson <ryan@innerfence.com>
357
358 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
359
360 rjbs: Ricardo Signes <rjbs@cpan.org>
361
362 robkinyon: Rob Kinyon <rkinyon@cpan.org>
363
364 Roman: Roman Filippov <romanf@cpan.org>
365
366 sc_: Just Another Perl Hacker
367
368 scotty: Scotty Allen <scotty@scottyallen.com>
369
370 semifor: Marc Mims <marc@questright.com>
371
372 solomon: Jared Johnson <jaredj@nmgi.com>
373
374 spb: Stephen Bennett <stephen@freenode.net>
375
376 sszabo: Stephan Szabo <sszabo@bigpanda.com>
377
378 teejay : Aaron Trevena <teejay@cpan.org>
379
380 Todd Lipcon
381
382 Tom Hukins
383
384 tonvoon: Ton Voon <tonvoon@cpan.org>
385
386 triode: Pete Gamache <gamache@cpan.org>
387
388 typester: Daisuke Murase <typester@cpan.org>
389
390 victori: Victor Igumnov <victori@cpan.org>
391
392 wdh: Will Hawes
393
394 willert: Sebastian Willert <willert@cpan.org>
395
396 wreis: Wallace Reis <wreis@cpan.org>
397
398 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
399
400 Possum: Daniel LeWarne <possum@cpan.org>
401
402 =head1 COPYRIGHT
403
404 Copyright (c) 2005 - 2010 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
405 as listed above.
406
407 =head1 LICENSE
408
409 This library is free software and may be distributed under the same terms
410 as perl itself.
411
412 =cut