7 package DBIx::Class::_ENV_;
11 *OLD_MRO = sub () { 1 };
15 *OLD_MRO = sub () { 0 };
18 # ::Runmode would only be loaded by DBICTest, which in turn implies t/
19 *DBICTEST = eval { DBICTest::RunMode->is_author }
24 # During 5.13 dev cycle HELEMs started to leak on copy
25 *PEEPEENESS = (defined $ENV{DBICTEST_ALL_LEAKS}
26 # request for all tests would force "non-leaky" illusion and vice-versa
27 ? ! $ENV{DBICTEST_ALL_LEAKS}
29 # otherwise confess that this perl is busted ONLY on smokers
31 if (eval { DBICTest::RunMode->is_smoker }) {
33 # leaky 5.13.6 (fixed in blead/cefd5c7c)
34 if ($] == '5.013006') { 1 }
36 # not sure why this one leaks, but disable anyway - ANDK seems to make it weep
37 elsif ($] == '5.013005') { 1 }
43 ) ? sub () { 1 } : sub () { 0 };
48 use DBIx::Class::Optional::Dependencies;
50 use vars qw($VERSION);
51 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
52 use DBIx::Class::StartupCheck;
54 __PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
55 __PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny');
58 shift->mk_classaccessor(@_);
61 sub mk_classaccessor {
63 $self->mk_group_accessors('inherited', $_[0]);
64 $self->set_inherited(@_) if @_ > 1;
67 sub component_base_class { 'DBIx::Class' }
69 # Always remember to do all digits for the version even if they're 0
70 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
71 # brain damage and presumably various other packaging systems too
74 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
76 sub MODIFY_CODE_ATTRIBUTES {
77 my ($class,$code,@attrs) = @_;
78 $class->mk_classdata('__attr_cache' => {})
79 unless $class->can('__attr_cache');
80 $class->__attr_cache->{$code} = [@attrs];
86 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
90 %{ $self->maybe::next::method || {} },
98 DBIx::Class - Extensible and flexible object <-> relational mapper.
100 =head1 GETTING HELP/SUPPORT
102 The community can be found via:
106 =item * Web Site: L<http://www.dbix-class.org/>
108 =item * IRC: irc.perl.org#dbix-class
111 <a href="http://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
113 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
115 =item * RT Bug Tracker: L<https://rt.cpan.org/Dist/Display.html?Queue=DBIx-Class>
117 =item * gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
119 =item * git: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
121 =item * twitter L<http://www.twitter.com/dbix_class>
127 Create a schema class called MyApp/Schema.pm:
129 package MyApp::Schema;
130 use base qw/DBIx::Class::Schema/;
132 __PACKAGE__->load_namespaces();
136 Create a result class to represent artists, who have many CDs, in
137 MyApp/Schema/Result/Artist.pm:
139 See L<DBIx::Class::ResultSource> for docs on defining result classes.
141 package MyApp::Schema::Result::Artist;
142 use base qw/DBIx::Class::Core/;
144 __PACKAGE__->table('artist');
145 __PACKAGE__->add_columns(qw/ artistid name /);
146 __PACKAGE__->set_primary_key('artistid');
147 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD');
151 A result class to represent a CD, which belongs to an artist, in
152 MyApp/Schema/Result/CD.pm:
154 package MyApp::Schema::Result::CD;
155 use base qw/DBIx::Class::Core/;
157 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
158 __PACKAGE__->table('cd');
159 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
160 __PACKAGE__->set_primary_key('cdid');
161 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
165 Then you can use these classes in your application's code:
167 # Connect to your database.
169 my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
171 # Query for all artists and put them in an array,
172 # or retrieve them as a result set object.
173 # $schema->resultset returns a DBIx::Class::ResultSet
174 my @all_artists = $schema->resultset('Artist')->all;
175 my $all_artists_rs = $schema->resultset('Artist');
177 # Output all artists names
178 # $artist here is a DBIx::Class::Row, which has accessors
179 # for all its columns. Rows are also subclasses of your Result class.
180 foreach $artist (@all_artists) {
181 print $artist->name, "\n";
184 # Create a result set to search for artists.
185 # This does not query the DB.
186 my $johns_rs = $schema->resultset('Artist')->search(
187 # Build your WHERE using an SQL::Abstract structure:
188 { name => { like => 'John%' } }
191 # Execute a joined query to get the cds.
192 my @all_john_cds = $johns_rs->search_related('cds')->all;
194 # Fetch the next available row.
195 my $first_john = $johns_rs->next;
197 # Specify ORDER BY on the query.
198 my $first_john_cds_by_title_rs = $first_john->cds(
200 { order_by => 'title' }
203 # Create a result set that will fetch the artist data
204 # at the same time as it fetches CDs, using only one query.
205 my $millennium_cds_rs = $schema->resultset('CD')->search(
207 { prefetch => 'artist' }
210 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
211 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
213 # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
214 # create() is the same as new() then insert().
215 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
216 $new_cd->artist($cd->artist);
217 $new_cd->insert; # Auto-increment primary key filled in after INSERT
218 $new_cd->title('Fork');
220 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
222 # change the year of all the millennium CDs at once
223 $millennium_cds_rs->update({ year => 2002 });
227 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
228 (with a compatibility layer as a springboard for porting) and a resultset API
229 that allows abstract encapsulation of database operations. It aims to make
230 representing queries in your code as perl-ish as possible while still
231 providing access to as many of the capabilities of the database as possible,
232 including retrieving related records from multiple tables in a single query,
233 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
235 DBIx::Class can handle multi-column primary and foreign keys, complex
236 queries and database-level paging, and does its best to only query the
237 database in order to return something you've directly asked for. If a
238 resultset is used as an iterator it only fetches rows off the statement
239 handle as requested in order to minimise memory usage. It has auto-increment
240 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
241 known to be used in production on at least the first four, and is fork-
242 and thread-safe out of the box (although
243 L<your DBD may not be|DBI/Threads_and_Thread_Safety>).
245 This project is still under rapid development, so large new features may be
246 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
247 Failing test cases are *always* welcome and point releases are put out rapidly
248 as bugs are found and fixed.
250 We do our best to maintain full backwards compatibility for published
251 APIs, since DBIx::Class is used in production in many organisations,
252 and even backwards incompatible changes to non-published APIs will be fixed
253 if they're reported and doing so doesn't cost the codebase anything.
255 The test suite is quite substantial, and several developer releases
256 are generally made to CPAN before the branch for the next release is
257 merged back to trunk for a major release.
259 =head1 WHERE TO GO NEXT
261 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
262 the modules where you will find documentation.
266 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
268 (I mostly consider myself "project founder" these days but the AUTHOR heading
273 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
275 acca: Alexander Kuznetsov <acca@cpan.org>
277 aherzog: Adam Herzog <adam@herzogdesigns.com>
279 Alexander Keusch <cpan@keusch.at>
281 alnewkirk: Al Newkirk <we@ana.im>
283 amiri: Amiri Barksdale <amiri@metalabel.com>
285 amoore: Andrew Moore <amoore@cpan.org>
287 andyg: Andy Grundman <andy@hybridized.org>
291 arc: Aaron Crane <arc@cpan.org>
293 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
295 ash: Ash Berlin <ash@cpan.org>
297 bert: Norbert Csongradi <bert@cpan.org>
299 blblack: Brandon L. Black <blblack@gmail.com>
301 bluefeet: Aran Deltac <bluefeet@cpan.org>
303 bphillips: Brian Phillips <bphillips@cpan.org>
305 boghead: Bryan Beeley <cpan@beeley.org>
307 bricas: Brian Cassidy <bricas@cpan.org>
309 brunov: Bruno Vecchi <vecchi.b@gmail.com>
311 caelum: Rafael Kitover <rkitover@cpan.org>
313 caldrin: Maik Hentsche <maik.hentsche@amd.com>
315 castaway: Jess Robinson
317 claco: Christopher H. Laco
321 da5id: David Jack Olrik <djo@cpan.org>
323 debolaz: Anders Nor Berle <berle@cpan.org>
325 dew: Dan Thomas <dan@godders.org>
327 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
329 dnm: Justin Wheeler <jwheeler@datademons.com>
331 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
333 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
335 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
337 freetime: Bill Moseley <moseley@hank.org>
339 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
341 goraxe: Gordon Irving <goraxe@cpan.org>
343 gphat: Cory G Watson <gphat@cpan.org>
345 Grant Street Group L<http://www.grantstreet.com/>
347 groditi: Guillermo Roditi <groditi@cpan.org>
349 Haarg: Graham Knop <haarg@haarg.org>
351 hobbs: Andrew Rodland <arodland@cpan.org>
353 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
355 initself: Mike Baas <mike@initselftech.com>
357 jawnsy: Jonathan Yu <jawnsy@cpan.org>
359 jasonmay: Jason May <jason.a.may@gmail.com>
363 jgoulah: John Goulah <jgoulah@cpan.org>
365 jguenther: Justin Guenther <jguenther@cpan.org>
367 jhannah: Jay Hannah <jay@jays.net>
369 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
371 jon: Jon Schutz <jjschutz@cpan.org>
373 jshirley: J. Shirley <jshirley@gmail.com>
375 kaare: Kaare Rasmussen
377 konobi: Scott McWhirter
379 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
381 lukes: Luke Saunders <luke.saunders@gmail.com>
383 marcus: Marcus Ramberg <mramberg@cpan.org>
385 mattlaw: Matt Lawrence
387 mattp: Matt Phillips <mattp@cpan.org>
389 michaelr: Michael Reddick <michael.reddick@gmail.com>
391 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
393 ned: Neil de Carteret
395 nigel: Nigel Metheringham <nigelm@cpan.org>
397 ningu: David Kamholz <dkamholz@cpan.org>
399 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
401 norbi: Norbert Buchmuller <norbi@nix.hu>
403 nuba: Nuba Princigalli <nuba@cpan.org>
405 Numa: Dan Sully <daniel@cpan.org>
407 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
409 oyse: Øystein Torget <oystein.torget@dnv.com>
411 paulm: Paul Makepeace
413 penguin: K J Cheetham
415 perigrin: Chris Prather <chris@prather.org>
417 peter: Peter Collingbourne <peter@pcc.me.uk>
419 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
421 plu: Johannes Plunien <plu@cpan.org>
423 Possum: Daniel LeWarne <possum@cpan.org>
425 quicksilver: Jules Bean
427 rafl: Florian Ragwitz <rafl@debian.org>
429 rainboxx: Matthias Dietrich <perl@rb.ly>
431 rbo: Robert Bohne <rbo@cpan.org>
433 rbuels: Robert Buels <rmb32@cornell.edu>
435 rdj: Ryan D Johnson <ryan@innerfence.com>
437 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
439 rjbs: Ricardo Signes <rjbs@cpan.org>
441 robkinyon: Rob Kinyon <rkinyon@cpan.org>
443 Robert Olson <bob@rdolson.org>
445 Roman: Roman Filippov <romanf@cpan.org>
447 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
449 sc_: Just Another Perl Hacker
451 scotty: Scotty Allen <scotty@scottyallen.com>
453 semifor: Marc Mims <marc@questright.com>
455 solomon: Jared Johnson <jaredj@nmgi.com>
457 spb: Stephen Bennett <stephen@freenode.net>
459 Squeeks <squeek@cpan.org>
461 sszabo: Stephan Szabo <sszabo@bigpanda.com>
463 talexb: Alex Beamish <talexb@gmail.com>
465 tamias: Ronald J Kimball <rjk@tamias.net>
467 teejay : Aaron Trevena <teejay@cpan.org>
473 tonvoon: Ton Voon <tonvoon@cpan.org>
475 triode: Pete Gamache <gamache@cpan.org>
477 typester: Daisuke Murase <typester@cpan.org>
479 victori: Victor Igumnov <victori@cpan.org>
483 willert: Sebastian Willert <willert@cpan.org>
485 wreis: Wallace Reis <wreis@cpan.org>
487 yrlnry: Mark Jason Dominus <mjd@plover.com>
489 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
493 Copyright (c) 2005 - 2010 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
498 This library is free software and may be distributed under the same terms