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
27 BROKEN_FORK => ($^O eq 'MSWin32') ? 1 : 0,
29 HAS_ITHREADS => $Config{useithreads} ? 1 : 0,
31 # ::Runmode would only be loaded by DBICTest, which in turn implies t/
32 DBICTEST => eval { DBICTest::RunMode->is_author } ? 1 : 0,
34 # During 5.13 dev cycle HELEMs started to leak on copy
36 # request for all tests would force "non-leaky" illusion and vice-versa
37 defined $ENV{DBICTEST_ALL_LEAKS} ? !$ENV{DBICTEST_ALL_LEAKS}
38 # otherwise confess that this perl is busted ONLY on smokers
39 : eval { DBICTest::RunMode->is_smoker } && ($] >= 5.013005 and $] <= 5.013006) ? 1
40 # otherwise we are good
47 constant->import( OLD_MRO => 1 );
51 constant->import( OLD_MRO => 0 );
57 use DBIx::Class::Optional::Dependencies;
59 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
60 use DBIx::Class::StartupCheck;
61 use DBIx::Class::Exception;
63 __PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
64 __PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny|^Class::Accessor::Grouped|^Context::Preserve');
67 shift->mk_classaccessor(@_);
70 sub mk_classaccessor {
72 $self->mk_group_accessors('inherited', $_[0]);
73 $self->set_inherited(@_) if @_ > 1;
76 sub component_base_class { 'DBIx::Class' }
78 sub MODIFY_CODE_ATTRIBUTES {
79 my ($class,$code,@attrs) = @_;
80 $class->mk_classdata('__attr_cache' => {})
81 unless $class->can('__attr_cache');
82 $class->__attr_cache->{$code} = [@attrs];
88 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
92 %{ $self->maybe::next::method || {} },
100 DBIx::Class - Extensible and flexible object <-> relational mapper.
102 =head1 WHERE TO START READING
104 See L<DBIx::Class::Manual::DocMap> for an overview of the exhaustive documentation.
105 To get the most out of DBIx::Class with the least confusion it is strongly
106 recommended to read (at the very least) the
107 L<Manuals|DBIx::Class::Manual::DocMap/Manuals> in the order presented there.
109 =head1 HOW TO GET HELP
111 Due to the complexity of its problem domain, DBIx::Class is a relatively
112 complex framework. After you start using DBIx::Class questions will inevitably
113 arise. If you are stuck with a problem or have doubts about a particular
114 approach do not hesitate to contact the community with your questions. The
115 list below is sorted by "fastest response time":
119 =item * IRC: irc.perl.org#dbix-class
122 <a href="https://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/NoAuth/Bugs.html?Dist=DBIx-Class>
128 =item * Twitter: L<https://www.twitter.com/dbix_class>
130 =item * Web Site: L<http://www.dbix-class.org/>
134 =head1 HOW TO CONTRIBUTE
136 Contributions are always welcome, in all usable forms (we especially
137 welcome documentation improvements). The delivery methods include git-
138 or unified-diff formatted patches, GitHub pull requests, or plain bug
139 reports either via RT or the Mailing list. Contributors are generally
140 granted full access to the official repository after their first patch
141 passes successful review.
144 FIXME: Getty, frew and jnap need to get off their asses and finish the contrib section so we can link it here ;)
146 This project is maintained in a git repository. The code and related tools are
147 accessible at the following locations:
151 =item * Official repo: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
153 =item * Official gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
155 =item * GitHub mirror: L<https://github.com/dbsrgits/DBIx-Class>
157 =item * Authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/DBIx-Class.git>
159 =item * Travis-CI log: L<https://travis-ci.org/dbsrgits/dbix-class/builds>
162 <br>↪ Stable branch CI status: <img src="https://secure.travis-ci.org/dbsrgits/dbix-class.png?branch=master"></img>
168 Create a schema class called MyApp/Schema.pm:
170 package MyApp::Schema;
171 use base qw/DBIx::Class::Schema/;
173 __PACKAGE__->load_namespaces();
177 Create a result class to represent artists, who have many CDs, in
178 MyApp/Schema/Result/Artist.pm:
180 See L<DBIx::Class::ResultSource> for docs on defining result classes.
182 package MyApp::Schema::Result::Artist;
183 use base qw/DBIx::Class::Core/;
185 __PACKAGE__->table('artist');
186 __PACKAGE__->add_columns(qw/ artistid name /);
187 __PACKAGE__->set_primary_key('artistid');
188 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');
192 A result class to represent a CD, which belongs to an artist, in
193 MyApp/Schema/Result/CD.pm:
195 package MyApp::Schema::Result::CD;
196 use base qw/DBIx::Class::Core/;
198 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
199 __PACKAGE__->table('cd');
200 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
201 __PACKAGE__->set_primary_key('cdid');
202 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
206 Then you can use these classes in your application's code:
208 # Connect to your database.
210 my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
212 # Query for all artists and put them in an array,
213 # or retrieve them as a result set object.
214 # $schema->resultset returns a DBIx::Class::ResultSet
215 my @all_artists = $schema->resultset('Artist')->all;
216 my $all_artists_rs = $schema->resultset('Artist');
218 # Output all artists names
219 # $artist here is a DBIx::Class::Row, which has accessors
220 # for all its columns. Rows are also subclasses of your Result class.
221 foreach $artist (@all_artists) {
222 print $artist->name, "\n";
225 # Create a result set to search for artists.
226 # This does not query the DB.
227 my $johns_rs = $schema->resultset('Artist')->search(
228 # Build your WHERE using an SQL::Abstract structure:
229 { name => { like => 'John%' } }
232 # Execute a joined query to get the cds.
233 my @all_john_cds = $johns_rs->search_related('cds')->all;
235 # Fetch the next available row.
236 my $first_john = $johns_rs->next;
238 # Specify ORDER BY on the query.
239 my $first_john_cds_by_title_rs = $first_john->cds(
241 { order_by => 'title' }
244 # Create a result set that will fetch the artist data
245 # at the same time as it fetches CDs, using only one query.
246 my $millennium_cds_rs = $schema->resultset('CD')->search(
248 { prefetch => 'artist' }
251 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
252 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
254 # new() makes a Result object but doesnt insert it into the DB.
255 # create() is the same as new() then insert().
256 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
257 $new_cd->artist($cd->artist);
258 $new_cd->insert; # Auto-increment primary key filled in after INSERT
259 $new_cd->title('Fork');
261 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
263 # change the year of all the millennium CDs at once
264 $millennium_cds_rs->update({ year => 2002 });
268 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
269 (with a compatibility layer as a springboard for porting) and a resultset API
270 that allows abstract encapsulation of database operations. It aims to make
271 representing queries in your code as perl-ish as possible while still
272 providing access to as many of the capabilities of the database as possible,
273 including retrieving related records from multiple tables in a single query,
274 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
276 DBIx::Class can handle multi-column primary and foreign keys, complex
277 queries and database-level paging, and does its best to only query the
278 database in order to return something you've directly asked for. If a
279 resultset is used as an iterator it only fetches rows off the statement
280 handle as requested in order to minimise memory usage. It has auto-increment
281 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
282 known to be used in production on at least the first four, and is fork-
283 and thread-safe out of the box (although
284 L<your DBD may not be|DBI/Threads and Thread Safety>).
286 This project is still under rapid development, so large new features may be
287 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
288 Failing test cases are *always* welcome and point releases are put out rapidly
289 as bugs are found and fixed.
291 We do our best to maintain full backwards compatibility for published
292 APIs, since DBIx::Class is used in production in many organisations,
293 and even backwards incompatible changes to non-published APIs will be fixed
294 if they're reported and doing so doesn't cost the codebase anything.
296 The test suite is quite substantial, and several developer releases
297 are generally made to CPAN before the branch for the next release is
298 merged back to trunk for a major release.
302 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
304 (I mostly consider myself "project founder" these days but the AUTHOR heading
309 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
311 acca: Alexander Kuznetsov <acca@cpan.org>
313 aherzog: Adam Herzog <adam@herzogdesigns.com>
315 Alexander Keusch <cpan@keusch.at>
317 alexrj: Alessandro Ranellucci <aar@cpan.org>
319 alnewkirk: Al Newkirk <we@ana.im>
321 amiri: Amiri Barksdale <amiri@metalabel.com>
323 amoore: Andrew Moore <amoore@cpan.org>
325 andrewalker: Andre Walker <andre@andrewalker.net>
327 andyg: Andy Grundman <andy@hybridized.org>
331 arc: Aaron Crane <arc@cpan.org>
333 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
335 ash: Ash Berlin <ash@cpan.org>
337 bert: Norbert Csongradi <bert@cpan.org>
339 blblack: Brandon L. Black <blblack@gmail.com>
341 bluefeet: Aran Deltac <bluefeet@cpan.org>
343 bphillips: Brian Phillips <bphillips@cpan.org>
345 boghead: Bryan Beeley <cpan@beeley.org>
347 brd: Brad Davis <brd@FreeBSD.org>
349 bricas: Brian Cassidy <bricas@cpan.org>
351 brunov: Bruno Vecchi <vecchi.b@gmail.com>
353 caelum: Rafael Kitover <rkitover@cpan.org>
355 caldrin: Maik Hentsche <maik.hentsche@amd.com>
357 castaway: Jess Robinson
359 claco: Christopher H. Laco
363 da5id: David Jack Olrik <djo@cpan.org>
365 davewood: David Schmidt <davewood@gmx.at>
367 debolaz: Anders Nor Berle <berle@cpan.org>
369 dew: Dan Thomas <dan@godders.org>
371 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
373 dnm: Justin Wheeler <jwheeler@datademons.com>
375 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
377 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
379 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
381 edenc: Eden Cardim <edencardim@gmail.com>
383 felliott: Fitz Elliott <fitz.elliott@gmail.com>
385 freetime: Bill Moseley <moseley@hank.org>
387 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
389 goraxe: Gordon Irving <goraxe@cpan.org>
391 gphat: Cory G Watson <gphat@cpan.org>
393 Grant Street Group L<http://www.grantstreet.com/>
395 groditi: Guillermo Roditi <groditi@cpan.org>
397 Haarg: Graham Knop <haarg@haarg.org>
399 hobbs: Andrew Rodland <arodland@cpan.org>
401 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
403 initself: Mike Baas <mike@initselftech.com>
405 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
407 jawnsy: Jonathan Yu <jawnsy@cpan.org>
409 jasonmay: Jason May <jason.a.may@gmail.com>
413 jgoulah: John Goulah <jgoulah@cpan.org>
415 jguenther: Justin Guenther <jguenther@cpan.org>
417 jhannah: Jay Hannah <jay@jays.net>
419 jmac: Jason McIntosh <jmac@appleseed-sc.com>
421 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
423 jon: Jon Schutz <jjschutz@cpan.org>
425 jshirley: J. Shirley <jshirley@gmail.com>
427 kaare: Kaare Rasmussen
429 konobi: Scott McWhirter
431 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
433 lukes: Luke Saunders <luke.saunders@gmail.com>
435 marcus: Marcus Ramberg <mramberg@cpan.org>
437 mattlaw: Matt Lawrence
439 mattp: Matt Phillips <mattp@cpan.org>
441 michaelr: Michael Reddick <michael.reddick@gmail.com>
443 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
445 mithaldu: Christian Walde <walde.christian@gmail.com>
447 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
449 mstratman: Mark A. Stratman <stratman@gmail.com>
451 ned: Neil de Carteret
453 nigel: Nigel Metheringham <nigelm@cpan.org>
455 ningu: David Kamholz <dkamholz@cpan.org>
457 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
459 norbi: Norbert Buchmuller <norbi@nix.hu>
461 nuba: Nuba Princigalli <nuba@cpan.org>
463 Numa: Dan Sully <daniel@cpan.org>
465 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
467 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
469 paulm: Paul Makepeace
471 penguin: K J Cheetham
473 perigrin: Chris Prather <chris@prather.org>
475 peter: Peter Collingbourne <peter@pcc.me.uk>
477 Peter Valdemar ME<oslash>rch <peter@morch.com>
479 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
481 plu: Johannes Plunien <plu@cpan.org>
483 Possum: Daniel LeWarne <possum@cpan.org>
485 quicksilver: Jules Bean
487 rafl: Florian Ragwitz <rafl@debian.org>
489 rainboxx: Matthias Dietrich <perl@rb.ly>
491 rbo: Robert Bohne <rbo@cpan.org>
493 rbuels: Robert Buels <rmb32@cornell.edu>
495 rdj: Ryan D Johnson <ryan@innerfence.com>
497 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
499 rjbs: Ricardo Signes <rjbs@cpan.org>
501 robkinyon: Rob Kinyon <rkinyon@cpan.org>
503 Robert Olson <bob@rdolson.org>
505 moltar: Roman Filippov <romanf@cpan.org>
507 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
509 sc_: Just Another Perl Hacker
511 scotty: Scotty Allen <scotty@scottyallen.com>
513 semifor: Marc Mims <marc@questright.com>
515 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
517 solomon: Jared Johnson <jaredj@nmgi.com>
519 spb: Stephen Bennett <stephen@freenode.net>
521 Squeeks <squeek@cpan.org>
523 sszabo: Stephan Szabo <sszabo@bigpanda.com>
525 talexb: Alex Beamish <talexb@gmail.com>
527 tamias: Ronald J Kimball <rjk@tamias.net>
529 teejay : Aaron Trevena <teejay@cpan.org>
535 tonvoon: Ton Voon <tonvoon@cpan.org>
537 triode: Pete Gamache <gamache@cpan.org>
539 typester: Daisuke Murase <typester@cpan.org>
541 victori: Victor Igumnov <victori@cpan.org>
545 wesm: Wes Malone <wes@mitsi.com>
547 willert: Sebastian Willert <willert@cpan.org>
549 wreis: Wallace Reis <wreis@cpan.org>
551 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
553 yrlnry: Mark Jason Dominus <mjd@plover.com>
555 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
559 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
564 This library is free software and may be distributed under the same terms