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