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