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