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/>
140 Create a schema class called F<MyApp/Schema.pm>:
142 package MyApp::Schema;
143 use base qw/DBIx::Class::Schema/;
145 __PACKAGE__->load_namespaces();
149 Create a result class to represent artists, who have many CDs, in
150 F<MyApp/Schema/Result/Artist.pm>:
152 See L<DBIx::Class::ResultSource> for docs on defining result classes.
154 package MyApp::Schema::Result::Artist;
155 use base qw/DBIx::Class::Core/;
157 __PACKAGE__->table('artist');
158 __PACKAGE__->add_columns(qw/ artistid name /);
159 __PACKAGE__->set_primary_key('artistid');
160 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');
164 A result class to represent a CD, which belongs to an artist, in
165 F<MyApp/Schema/Result/CD.pm>:
167 package MyApp::Schema::Result::CD;
168 use base qw/DBIx::Class::Core/;
170 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
171 __PACKAGE__->table('cd');
172 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
173 __PACKAGE__->set_primary_key('cdid');
174 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
178 Then you can use these classes in your application's code:
180 # Connect to your database.
182 my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
184 # Query for all artists and put them in an array,
185 # or retrieve them as a result set object.
186 # $schema->resultset returns a DBIx::Class::ResultSet
187 my @all_artists = $schema->resultset('Artist')->all;
188 my $all_artists_rs = $schema->resultset('Artist');
190 # Output all artists names
191 # $artist here is a DBIx::Class::Row, which has accessors
192 # for all its columns. Rows are also subclasses of your Result class.
193 foreach $artist (@all_artists) {
194 print $artist->name, "\n";
197 # Create a result set to search for artists.
198 # This does not query the DB.
199 my $johns_rs = $schema->resultset('Artist')->search(
200 # Build your WHERE using an SQL::Abstract structure:
201 { name => { like => 'John%' } }
204 # Execute a joined query to get the cds.
205 my @all_john_cds = $johns_rs->search_related('cds')->all;
207 # Fetch the next available row.
208 my $first_john = $johns_rs->next;
210 # Specify ORDER BY on the query.
211 my $first_john_cds_by_title_rs = $first_john->cds(
213 { order_by => 'title' }
216 # Create a result set that will fetch the artist data
217 # at the same time as it fetches CDs, using only one query.
218 my $millennium_cds_rs = $schema->resultset('CD')->search(
220 { prefetch => 'artist' }
223 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
224 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
226 # new() makes a Result object but doesnt insert it into the DB.
227 # create() is the same as new() then insert().
228 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
229 $new_cd->artist($cd->artist);
230 $new_cd->insert; # Auto-increment primary key filled in after INSERT
231 $new_cd->title('Fork');
233 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
235 # change the year of all the millennium CDs at once
236 $millennium_cds_rs->update({ year => 2002 });
240 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
241 (with a compatibility layer as a springboard for porting) and a resultset API
242 that allows abstract encapsulation of database operations. It aims to make
243 representing queries in your code as perl-ish as possible while still
244 providing access to as many of the capabilities of the database as possible,
245 including retrieving related records from multiple tables in a single query,
246 C<JOIN>, C<LEFT JOIN>, C<COUNT>, C<DISTINCT>, C<GROUP BY>, C<ORDER BY> and
249 DBIx::Class can handle multi-column primary and foreign keys, complex
250 queries and database-level paging, and does its best to only query the
251 database in order to return something you've directly asked for. If a
252 resultset is used as an iterator it only fetches rows off the statement
253 handle as requested in order to minimise memory usage. It has auto-increment
254 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
255 known to be used in production on at least the first four, and is fork-
256 and thread-safe out of the box (although
257 L<your DBD may not be|DBI/Threads and Thread Safety>).
259 This project is still under rapid development, so large new features may be
260 marked B<experimental> - such APIs are still usable but may have edge bugs.
261 Failing test cases are I<always> welcome and point releases are put out rapidly
262 as bugs are found and fixed.
264 We do our best to maintain full backwards compatibility for published
265 APIs, since DBIx::Class is used in production in many organisations,
266 and even backwards incompatible changes to non-published APIs will be fixed
267 if they're reported and doing so doesn't cost the codebase anything.
269 The test suite is quite substantial, and several developer releases
270 are generally made to CPAN before the branch for the next release is
271 merged back to trunk for a major release.
273 =head1 HOW TO CONTRIBUTE
275 Contributions are always welcome, in all usable forms (we especially
276 welcome documentation improvements). The delivery methods include git-
277 or unified-diff formatted patches, GitHub pull requests, or plain bug
278 reports either via RT or the Mailing list. Contributors are generally
279 granted full access to the official repository after their first patch
280 passes successful review.
283 FIXME: Getty, frew and jnap need to get off their asses and finish the contrib section so we can link it here ;)
285 This project is maintained in a git repository. The code and related tools are
286 accessible at the following locations:
290 =item * Official repo: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
292 =item * Official gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
294 =item * GitHub mirror: L<https://github.com/dbsrgits/DBIx-Class>
296 =item * Authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/DBIx-Class.git>
298 =item * Travis-CI log: L<https://travis-ci.org/dbsrgits/dbix-class/builds>
301 ↪ Stable branch CI status: <img src="https://secure.travis-ci.org/dbsrgits/dbix-class.png?branch=master"></img>
307 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
309 (I mostly consider myself "project founder" these days but the AUTHOR heading
314 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
316 acca: Alexander Kuznetsov <acca@cpan.org>
318 aherzog: Adam Herzog <adam@herzogdesigns.com>
320 Alexander Keusch <cpan@keusch.at>
322 alexrj: Alessandro Ranellucci <aar@cpan.org>
324 alnewkirk: Al Newkirk <we@ana.im>
326 amiri: Amiri Barksdale <amiri@metalabel.com>
328 amoore: Andrew Moore <amoore@cpan.org>
330 andrewalker: Andre Walker <andre@andrewalker.net>
332 andyg: Andy Grundman <andy@hybridized.org>
336 arc: Aaron Crane <arc@cpan.org>
338 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
340 ash: Ash Berlin <ash@cpan.org>
342 bert: Norbert Csongradi <bert@cpan.org>
344 blblack: Brandon L. Black <blblack@gmail.com>
346 bluefeet: Aran Deltac <bluefeet@cpan.org>
348 bphillips: Brian Phillips <bphillips@cpan.org>
350 boghead: Bryan Beeley <cpan@beeley.org>
352 brd: Brad Davis <brd@FreeBSD.org>
354 bricas: Brian Cassidy <bricas@cpan.org>
356 brunov: Bruno Vecchi <vecchi.b@gmail.com>
358 caelum: Rafael Kitover <rkitover@cpan.org>
360 caldrin: Maik Hentsche <maik.hentsche@amd.com>
362 castaway: Jess Robinson
364 claco: Christopher H. Laco
368 da5id: David Jack Olrik <djo@cpan.org>
370 dariusj: Darius Jokilehto <dariusjokilehto@yahoo.co.uk>
372 davewood: David Schmidt <davewood@gmx.at>
374 daxim: Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim@cpan.org>
376 debolaz: Anders Nor Berle <berle@cpan.org>
378 dew: Dan Thomas <dan@godders.org>
380 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
382 dnm: Justin Wheeler <jwheeler@datademons.com>
384 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
386 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
388 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
390 edenc: Eden Cardim <edencardim@gmail.com>
392 felliott: Fitz Elliott <fitz.elliott@gmail.com>
394 freetime: Bill Moseley <moseley@hank.org>
396 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
398 goraxe: Gordon Irving <goraxe@cpan.org>
400 gphat: Cory G Watson <gphat@cpan.org>
402 Grant Street Group L<http://www.grantstreet.com/>
404 groditi: Guillermo Roditi <groditi@cpan.org>
406 Haarg: Graham Knop <haarg@haarg.org>
408 hobbs: Andrew Rodland <arodland@cpan.org>
410 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
412 initself: Mike Baas <mike@initselftech.com>
414 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
416 jawnsy: Jonathan Yu <jawnsy@cpan.org>
418 jasonmay: Jason May <jason.a.may@gmail.com>
422 jgoulah: John Goulah <jgoulah@cpan.org>
424 jguenther: Justin Guenther <jguenther@cpan.org>
426 jhannah: Jay Hannah <jay@jays.net>
428 jmac: Jason McIntosh <jmac@appleseed-sc.com>
430 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
432 jon: Jon Schutz <jjschutz@cpan.org>
434 jshirley: J. Shirley <jshirley@gmail.com>
436 kaare: Kaare Rasmussen
438 konobi: Scott McWhirter
440 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
442 lukes: Luke Saunders <luke.saunders@gmail.com>
444 marcus: Marcus Ramberg <mramberg@cpan.org>
446 mattlaw: Matt Lawrence
448 mattp: Matt Phillips <mattp@cpan.org>
450 michaelr: Michael Reddick <michael.reddick@gmail.com>
452 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
454 mithaldu: Christian Walde <walde.christian@gmail.com>
456 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
458 mstratman: Mark A. Stratman <stratman@gmail.com>
460 ned: Neil de Carteret
462 nigel: Nigel Metheringham <nigelm@cpan.org>
464 ningu: David Kamholz <dkamholz@cpan.org>
466 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
468 norbi: Norbert Buchmuller <norbi@nix.hu>
470 nuba: Nuba Princigalli <nuba@cpan.org>
472 Numa: Dan Sully <daniel@cpan.org>
474 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
476 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
478 paulm: Paul Makepeace
480 penguin: K J Cheetham
482 perigrin: Chris Prather <chris@prather.org>
484 peter: Peter Collingbourne <peter@pcc.me.uk>
486 Peter Valdemar ME<oslash>rch <peter@morch.com>
488 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
490 plu: Johannes Plunien <plu@cpan.org>
492 Possum: Daniel LeWarne <possum@cpan.org>
494 quicksilver: Jules Bean
496 rafl: Florian Ragwitz <rafl@debian.org>
498 rainboxx: Matthias Dietrich <perl@rb.ly>
500 rbo: Robert Bohne <rbo@cpan.org>
502 rbuels: Robert Buels <rmb32@cornell.edu>
504 rdj: Ryan D Johnson <ryan@innerfence.com>
506 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
508 rjbs: Ricardo Signes <rjbs@cpan.org>
510 robkinyon: Rob Kinyon <rkinyon@cpan.org>
512 Robert Olson <bob@rdolson.org>
514 moltar: Roman Filippov <romanf@cpan.org>
516 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
518 sc_: Just Another Perl Hacker
520 scotty: Scotty Allen <scotty@scottyallen.com>
522 semifor: Marc Mims <marc@questright.com>
524 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
526 solomon: Jared Johnson <jaredj@nmgi.com>
528 spb: Stephen Bennett <stephen@freenode.net>
530 Squeeks <squeek@cpan.org>
532 sszabo: Stephan Szabo <sszabo@bigpanda.com>
534 talexb: Alex Beamish <talexb@gmail.com>
536 tamias: Ronald J Kimball <rjk@tamias.net>
538 teejay : Aaron Trevena <teejay@cpan.org>
544 tonvoon: Ton Voon <tonvoon@cpan.org>
546 triode: Pete Gamache <gamache@cpan.org>
548 typester: Daisuke Murase <typester@cpan.org>
550 victori: Victor Igumnov <victori@cpan.org>
554 wesm: Wes Malone <wes@mitsi.com>
556 willert: Sebastian Willert <willert@cpan.org>
558 wreis: Wallace Reis <wreis@cpan.org>
560 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
562 yrlnry: Mark Jason Dominus <mjd@plover.com>
564 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
568 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
573 This library is free software and may be distributed under the same terms