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