7 # Always remember to do all digits for the version even if they're 0
8 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
9 # brain damage and presumably various other packaging systems too
11 # $VERSION declaration must stay up here, ahead of any other package
12 # declarations, as to not confuse various modules attempting to determine
13 # this ones version, whether that be s.c.o. or Module::Metadata, etc
16 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
19 package DBIx::Class::_ENV_;
23 *OLD_MRO = sub () { 1 };
27 *OLD_MRO = sub () { 0 };
30 # ::Runmode would only be loaded by DBICTest, which in turn implies t/
31 *DBICTEST = eval { DBICTest::RunMode->is_author }
36 # There was a brief period of p5p insanity when $@ was invisible in a DESTROY
37 *INVISIBLE_DOLLAR_AT = ($] >= 5.013001 and $] <= 5.013007)
42 # During 5.13 dev cycle HELEMs started to leak on copy
43 *PEEPEENESS = (defined $ENV{DBICTEST_ALL_LEAKS}
44 # request for all tests would force "non-leaky" illusion and vice-versa
45 ? ! $ENV{DBICTEST_ALL_LEAKS}
47 # otherwise confess that this perl is busted ONLY on smokers
49 if (eval { DBICTest::RunMode->is_smoker }) {
51 # leaky 5.13.6 (fixed in blead/cefd5c7c)
52 if ($] == '5.013006') { 1 }
54 # not sure why this one leaks, but disable anyway - ANDK seems to make it weep
55 elsif ($] == '5.013005') { 1 }
61 ) ? sub () { 1 } : sub () { 0 };
67 use DBIx::Class::Optional::Dependencies;
69 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
70 use DBIx::Class::StartupCheck;
72 __PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
73 __PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny');
76 shift->mk_classaccessor(@_);
79 sub mk_classaccessor {
81 $self->mk_group_accessors('inherited', $_[0]);
82 $self->set_inherited(@_) if @_ > 1;
85 sub component_base_class { 'DBIx::Class' }
87 sub MODIFY_CODE_ATTRIBUTES {
88 my ($class,$code,@attrs) = @_;
89 $class->mk_classdata('__attr_cache' => {})
90 unless $class->can('__attr_cache');
91 $class->__attr_cache->{$code} = [@attrs];
97 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
101 %{ $self->maybe::next::method || {} },
109 DBIx::Class - Extensible and flexible object <-> relational mapper.
111 =head1 GETTING HELP/SUPPORT
113 The community can be found via:
117 =item * Web Site: L<http://www.dbix-class.org/>
119 =item * IRC: irc.perl.org#dbix-class
122 <a href="http://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
124 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
126 =item * RT Bug Tracker: L<https://rt.cpan.org/Dist/Display.html?Queue=DBIx-Class>
128 =item * gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
130 =item * git: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
132 =item * twitter L<http://www.twitter.com/dbix_class>
138 Create a schema class called MyApp/Schema.pm:
140 package MyApp::Schema;
141 use base qw/DBIx::Class::Schema/;
143 __PACKAGE__->load_namespaces();
147 Create a result class to represent artists, who have many CDs, in
148 MyApp/Schema/Result/Artist.pm:
150 See L<DBIx::Class::ResultSource> for docs on defining result classes.
152 package MyApp::Schema::Result::Artist;
153 use base qw/DBIx::Class::Core/;
155 __PACKAGE__->table('artist');
156 __PACKAGE__->add_columns(qw/ artistid name /);
157 __PACKAGE__->set_primary_key('artistid');
158 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD');
162 A result class to represent a CD, which belongs to an artist, in
163 MyApp/Schema/Result/CD.pm:
165 package MyApp::Schema::Result::CD;
166 use base qw/DBIx::Class::Core/;
168 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
169 __PACKAGE__->table('cd');
170 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
171 __PACKAGE__->set_primary_key('cdid');
172 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
176 Then you can use these classes in your application's code:
178 # Connect to your database.
180 my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
182 # Query for all artists and put them in an array,
183 # or retrieve them as a result set object.
184 # $schema->resultset returns a DBIx::Class::ResultSet
185 my @all_artists = $schema->resultset('Artist')->all;
186 my $all_artists_rs = $schema->resultset('Artist');
188 # Output all artists names
189 # $artist here is a DBIx::Class::Row, which has accessors
190 # for all its columns. Rows are also subclasses of your Result class.
191 foreach $artist (@all_artists) {
192 print $artist->name, "\n";
195 # Create a result set to search for artists.
196 # This does not query the DB.
197 my $johns_rs = $schema->resultset('Artist')->search(
198 # Build your WHERE using an SQL::Abstract structure:
199 { name => { like => 'John%' } }
202 # Execute a joined query to get the cds.
203 my @all_john_cds = $johns_rs->search_related('cds')->all;
205 # Fetch the next available row.
206 my $first_john = $johns_rs->next;
208 # Specify ORDER BY on the query.
209 my $first_john_cds_by_title_rs = $first_john->cds(
211 { order_by => 'title' }
214 # Create a result set that will fetch the artist data
215 # at the same time as it fetches CDs, using only one query.
216 my $millennium_cds_rs = $schema->resultset('CD')->search(
218 { prefetch => 'artist' }
221 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
222 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
224 # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
225 # create() is the same as new() then insert().
226 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
227 $new_cd->artist($cd->artist);
228 $new_cd->insert; # Auto-increment primary key filled in after INSERT
229 $new_cd->title('Fork');
231 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
233 # change the year of all the millennium CDs at once
234 $millennium_cds_rs->update({ year => 2002 });
238 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
239 (with a compatibility layer as a springboard for porting) and a resultset API
240 that allows abstract encapsulation of database operations. It aims to make
241 representing queries in your code as perl-ish as possible while still
242 providing access to as many of the capabilities of the database as possible,
243 including retrieving related records from multiple tables in a single query,
244 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
246 DBIx::Class can handle multi-column primary and foreign keys, complex
247 queries and database-level paging, and does its best to only query the
248 database in order to return something you've directly asked for. If a
249 resultset is used as an iterator it only fetches rows off the statement
250 handle as requested in order to minimise memory usage. It has auto-increment
251 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
252 known to be used in production on at least the first four, and is fork-
253 and thread-safe out of the box (although
254 L<your DBD may not be|DBI/Threads_and_Thread_Safety>).
256 This project is still under rapid development, so large new features may be
257 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
258 Failing test cases are *always* welcome and point releases are put out rapidly
259 as bugs are found and fixed.
261 We do our best to maintain full backwards compatibility for published
262 APIs, since DBIx::Class is used in production in many organisations,
263 and even backwards incompatible changes to non-published APIs will be fixed
264 if they're reported and doing so doesn't cost the codebase anything.
266 The test suite is quite substantial, and several developer releases
267 are generally made to CPAN before the branch for the next release is
268 merged back to trunk for a major release.
270 =head1 WHERE TO GO NEXT
272 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
273 the modules where you will find documentation.
277 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
279 (I mostly consider myself "project founder" these days but the AUTHOR heading
284 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
286 acca: Alexander Kuznetsov <acca@cpan.org>
288 aherzog: Adam Herzog <adam@herzogdesigns.com>
290 Alexander Keusch <cpan@keusch.at>
292 alnewkirk: Al Newkirk <we@ana.im>
294 amiri: Amiri Barksdale <amiri@metalabel.com>
296 amoore: Andrew Moore <amoore@cpan.org>
298 andyg: Andy Grundman <andy@hybridized.org>
302 arc: Aaron Crane <arc@cpan.org>
304 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
306 ash: Ash Berlin <ash@cpan.org>
308 bert: Norbert Csongradi <bert@cpan.org>
310 blblack: Brandon L. Black <blblack@gmail.com>
312 bluefeet: Aran Deltac <bluefeet@cpan.org>
314 bphillips: Brian Phillips <bphillips@cpan.org>
316 boghead: Bryan Beeley <cpan@beeley.org>
318 bricas: Brian Cassidy <bricas@cpan.org>
320 brunov: Bruno Vecchi <vecchi.b@gmail.com>
322 caelum: Rafael Kitover <rkitover@cpan.org>
324 caldrin: Maik Hentsche <maik.hentsche@amd.com>
326 castaway: Jess Robinson
328 claco: Christopher H. Laco
332 da5id: David Jack Olrik <djo@cpan.org>
334 debolaz: Anders Nor Berle <berle@cpan.org>
336 dew: Dan Thomas <dan@godders.org>
338 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
340 dnm: Justin Wheeler <jwheeler@datademons.com>
342 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
344 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
346 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
348 felliott: Fitz Elliott <fitz.elliott@gmail.com>
350 freetime: Bill Moseley <moseley@hank.org>
352 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
354 goraxe: Gordon Irving <goraxe@cpan.org>
356 gphat: Cory G Watson <gphat@cpan.org>
358 Grant Street Group L<http://www.grantstreet.com/>
360 groditi: Guillermo Roditi <groditi@cpan.org>
362 Haarg: Graham Knop <haarg@haarg.org>
364 hobbs: Andrew Rodland <arodland@cpan.org>
366 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
368 initself: Mike Baas <mike@initselftech.com>
370 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
372 jawnsy: Jonathan Yu <jawnsy@cpan.org>
374 jasonmay: Jason May <jason.a.may@gmail.com>
378 jgoulah: John Goulah <jgoulah@cpan.org>
380 jguenther: Justin Guenther <jguenther@cpan.org>
382 jhannah: Jay Hannah <jay@jays.net>
384 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
386 jon: Jon Schutz <jjschutz@cpan.org>
388 jshirley: J. Shirley <jshirley@gmail.com>
390 kaare: Kaare Rasmussen
392 konobi: Scott McWhirter
394 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
396 lukes: Luke Saunders <luke.saunders@gmail.com>
398 marcus: Marcus Ramberg <mramberg@cpan.org>
400 mattlaw: Matt Lawrence
402 mattp: Matt Phillips <mattp@cpan.org>
404 michaelr: Michael Reddick <michael.reddick@gmail.com>
406 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
408 ned: Neil de Carteret
410 nigel: Nigel Metheringham <nigelm@cpan.org>
412 ningu: David Kamholz <dkamholz@cpan.org>
414 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
416 norbi: Norbert Buchmuller <norbi@nix.hu>
418 nuba: Nuba Princigalli <nuba@cpan.org>
420 Numa: Dan Sully <daniel@cpan.org>
422 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
424 oyse: Øystein Torget <oystein.torget@dnv.com>
426 paulm: Paul Makepeace
428 penguin: K J Cheetham
430 perigrin: Chris Prather <chris@prather.org>
432 peter: Peter Collingbourne <peter@pcc.me.uk>
434 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
436 plu: Johannes Plunien <plu@cpan.org>
438 Possum: Daniel LeWarne <possum@cpan.org>
440 quicksilver: Jules Bean
442 rafl: Florian Ragwitz <rafl@debian.org>
444 rainboxx: Matthias Dietrich <perl@rb.ly>
446 rbo: Robert Bohne <rbo@cpan.org>
448 rbuels: Robert Buels <rmb32@cornell.edu>
450 rdj: Ryan D Johnson <ryan@innerfence.com>
452 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
454 rjbs: Ricardo Signes <rjbs@cpan.org>
456 robkinyon: Rob Kinyon <rkinyon@cpan.org>
458 Robert Olson <bob@rdolson.org>
460 Roman: Roman Filippov <romanf@cpan.org>
462 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
464 sc_: Just Another Perl Hacker
466 scotty: Scotty Allen <scotty@scottyallen.com>
468 semifor: Marc Mims <marc@questright.com>
470 solomon: Jared Johnson <jaredj@nmgi.com>
472 spb: Stephen Bennett <stephen@freenode.net>
474 Squeeks <squeek@cpan.org>
476 sszabo: Stephan Szabo <sszabo@bigpanda.com>
478 talexb: Alex Beamish <talexb@gmail.com>
480 tamias: Ronald J Kimball <rjk@tamias.net>
482 teejay : Aaron Trevena <teejay@cpan.org>
488 tonvoon: Ton Voon <tonvoon@cpan.org>
490 triode: Pete Gamache <gamache@cpan.org>
492 typester: Daisuke Murase <typester@cpan.org>
494 victori: Victor Igumnov <victori@cpan.org>
498 willert: Sebastian Willert <willert@cpan.org>
500 wreis: Wallace Reis <wreis@cpan.org>
502 yrlnry: Mark Jason Dominus <mjd@plover.com>
504 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
508 Copyright (c) 2005 - 2010 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
513 This library is free software and may be distributed under the same terms