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