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