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
18 use DBIx::Class::_Util;
21 use DBIx::Class::Optional::Dependencies;
23 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
24 use DBIx::Class::StartupCheck;
25 use DBIx::Class::Exception;
27 __PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
28 __PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny|^Class::Accessor::Grouped|^Context::Preserve');
31 shift->mk_classaccessor(@_);
34 sub mk_classaccessor {
36 $self->mk_group_accessors('inherited', $_[0]);
37 $self->set_inherited(@_) if @_ > 1;
40 sub component_base_class { 'DBIx::Class' }
42 sub MODIFY_CODE_ATTRIBUTES {
43 my ($class,$code,@attrs) = @_;
44 $class->mk_classdata('__attr_cache' => {})
45 unless $class->can('__attr_cache');
46 $class->__attr_cache->{$code} = [@attrs];
52 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
56 %{ $self->maybe::next::method || {} },
68 DBIx::Class - Extensible and flexible object <-> relational mapper.
70 =head1 WHERE TO START READING
72 See L<DBIx::Class::Manual::DocMap> for an overview of the exhaustive documentation.
73 To get the most out of DBIx::Class with the least confusion it is strongly
74 recommended to read (at the very least) the
75 L<Manuals|DBIx::Class::Manual::DocMap/Manuals> in the order presented there.
77 =head1 HOW TO GET HELP
79 Due to the complexity of its problem domain, DBIx::Class is a relatively
80 complex framework. After you start using DBIx::Class questions will inevitably
81 arise. If you are stuck with a problem or have doubts about a particular
82 approach do not hesitate to contact the community with your questions. The
83 list below is sorted by "fastest response time":
87 =item * IRC: irc.perl.org#dbix-class
90 <a href="https://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
92 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
94 =item * RT Bug Tracker: L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-Class>
96 =item * Twitter: L<https://www.twitter.com/dbix_class>
98 =item * Web Site: L<http://www.dbix-class.org/>
104 For the very impatient: L<DBIx::Class::Manual::QuickStart>
106 This code in the next step can be generated automatically from an existing
107 database, see L<dbicdump> from the distribution C<DBIx-Class-Schema-Loader>.
109 =head2 Schema classes preparation
111 Create a schema class called F<MyApp/Schema.pm>:
113 package MyApp::Schema;
114 use base qw/DBIx::Class::Schema/;
116 __PACKAGE__->load_namespaces();
120 Create a result class to represent artists, who have many CDs, in
121 F<MyApp/Schema/Result/Artist.pm>:
123 See L<DBIx::Class::ResultSource> for docs on defining result classes.
125 package MyApp::Schema::Result::Artist;
126 use base qw/DBIx::Class::Core/;
128 __PACKAGE__->table('artist');
129 __PACKAGE__->add_columns(qw/ artistid name /);
130 __PACKAGE__->set_primary_key('artistid');
131 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');
135 A result class to represent a CD, which belongs to an artist, in
136 F<MyApp/Schema/Result/CD.pm>:
138 package MyApp::Schema::Result::CD;
139 use base qw/DBIx::Class::Core/;
141 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
142 __PACKAGE__->table('cd');
143 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
144 __PACKAGE__->set_primary_key('cdid');
145 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
151 Then you can use these classes in your application's code:
153 # Connect to your database.
155 my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
157 # Query for all artists and put them in an array,
158 # or retrieve them as a result set object.
159 # $schema->resultset returns a DBIx::Class::ResultSet
160 my @all_artists = $schema->resultset('Artist')->all;
161 my $all_artists_rs = $schema->resultset('Artist');
163 # Output all artists names
164 # $artist here is a DBIx::Class::Row, which has accessors
165 # for all its columns. Rows are also subclasses of your Result class.
166 foreach $artist (@all_artists) {
167 print $artist->name, "\n";
170 # Create a result set to search for artists.
171 # This does not query the DB.
172 my $johns_rs = $schema->resultset('Artist')->search(
173 # Build your WHERE using an SQL::Abstract structure:
174 { name => { like => 'John%' } }
177 # Execute a joined query to get the cds.
178 my @all_john_cds = $johns_rs->search_related('cds')->all;
180 # Fetch the next available row.
181 my $first_john = $johns_rs->next;
183 # Specify ORDER BY on the query.
184 my $first_john_cds_by_title_rs = $first_john->cds(
186 { order_by => 'title' }
189 # Create a result set that will fetch the artist data
190 # at the same time as it fetches CDs, using only one query.
191 my $millennium_cds_rs = $schema->resultset('CD')->search(
193 { prefetch => 'artist' }
196 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
197 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
199 # new() makes a Result object but doesnt insert it into the DB.
200 # create() is the same as new() then insert().
201 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
202 $new_cd->artist($cd->artist);
203 $new_cd->insert; # Auto-increment primary key filled in after INSERT
204 $new_cd->title('Fork');
206 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
208 # change the year of all the millennium CDs at once
209 $millennium_cds_rs->update({ year => 2002 });
213 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
214 (with a compatibility layer as a springboard for porting) and a resultset API
215 that allows abstract encapsulation of database operations. It aims to make
216 representing queries in your code as perl-ish as possible while still
217 providing access to as many of the capabilities of the database as possible,
218 including retrieving related records from multiple tables in a single query,
219 C<JOIN>, C<LEFT JOIN>, C<COUNT>, C<DISTINCT>, C<GROUP BY>, C<ORDER BY> and
222 DBIx::Class can handle multi-column primary and foreign keys, complex
223 queries and database-level paging, and does its best to only query the
224 database in order to return something you've directly asked for. If a
225 resultset is used as an iterator it only fetches rows off the statement
226 handle as requested in order to minimise memory usage. It has auto-increment
227 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
228 known to be used in production on at least the first four, and is fork-
229 and thread-safe out of the box (although
230 L<your DBD may not be|DBI/Threads and Thread Safety>).
232 This project is still under rapid development, so large new features may be
233 marked B<experimental> - such APIs are still usable but may have edge bugs.
234 Failing test cases are I<always> welcome and point releases are put out rapidly
235 as bugs are found and fixed.
237 We do our best to maintain full backwards compatibility for published
238 APIs, since DBIx::Class is used in production in many organisations,
239 and even backwards incompatible changes to non-published APIs will be fixed
240 if they're reported and doing so doesn't cost the codebase anything.
242 The test suite is quite substantial, and several developer releases
243 are generally made to CPAN before the branch for the next release is
244 merged back to trunk for a major release.
246 =head1 HOW TO CONTRIBUTE
248 Contributions are always welcome, in all usable forms (we especially
249 welcome documentation improvements). The delivery methods include git-
250 or unified-diff formatted patches, GitHub pull requests, or plain bug
251 reports either via RT or the Mailing list. Contributors are generally
252 granted full access to the official repository after their first patch
253 passes successful review.
256 FIXME: Getty, frew and jnap need to get off their asses and finish the contrib section so we can link it here ;)
258 This project is maintained in a git repository. The code and related tools are
259 accessible at the following locations:
263 =item * Official repo: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
265 =item * Official gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
267 =item * GitHub mirror: L<https://github.com/dbsrgits/DBIx-Class>
269 =item * Authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/DBIx-Class.git>
271 =item * Travis-CI log: L<https://travis-ci.org/dbsrgits/dbix-class/builds>
274 ↪ Stable branch CI status: <img src="https://secure.travis-ci.org/dbsrgits/dbix-class.png?branch=master"></img>
280 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
282 (I mostly consider myself "project founder" these days but the AUTHOR heading
287 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
289 acca: Alexander Kuznetsov <acca@cpan.org>
291 aherzog: Adam Herzog <adam@herzogdesigns.com>
293 Alexander Keusch <cpan@keusch.at>
295 alexrj: Alessandro Ranellucci <aar@cpan.org>
297 alnewkirk: Al Newkirk <we@ana.im>
299 amiri: Amiri Barksdale <amiri@metalabel.com>
301 amoore: Andrew Moore <amoore@cpan.org>
303 Andrew Mehta <Andrew@unitedgames.co.uk>
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 bfwg: Colin Newell <colin.newell@gmail.com>
321 blblack: Brandon L. Black <blblack@gmail.com>
323 bluefeet: Aran Deltac <bluefeet@cpan.org>
325 bphillips: Brian Phillips <bphillips@cpan.org>
327 boghead: Bryan Beeley <cpan@beeley.org>
329 brd: Brad Davis <brd@FreeBSD.org>
331 bricas: Brian Cassidy <bricas@cpan.org>
333 brunov: Bruno Vecchi <vecchi.b@gmail.com>
335 caelum: Rafael Kitover <rkitover@cpan.org>
337 caldrin: Maik Hentsche <maik.hentsche@amd.com>
339 castaway: Jess Robinson
341 claco: Christopher H. Laco
345 Ctrl-o L<http://ctrlo.com/>
347 da5id: David Jack Olrik <djo@cpan.org>
349 dariusj: Darius Jokilehto <dariusjokilehto@yahoo.co.uk>
351 davewood: David Schmidt <davewood@gmx.at>
353 daxim: Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim@cpan.org>
355 debolaz: Anders Nor Berle <berle@cpan.org>
357 dew: Dan Thomas <dan@godders.org>
359 dim0xff: Dmitry Latin <dim0xff@gmail.com>
361 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
363 dnm: Justin Wheeler <jwheeler@datademons.com>
365 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
367 duncan_dmg: Duncan Garland <Duncan.Garland@motortrak.com>
369 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
371 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
373 edenc: Eden Cardim <edencardim@gmail.com>
375 Eligo L<http://eligo.co.uk/>
377 ether: Karen Etheridge <ether@cpan.org>
379 felliott: Fitz Elliott <fitz.elliott@gmail.com>
381 freetime: Bill Moseley <moseley@hank.org>
383 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
385 goraxe: Gordon Irving <goraxe@cpan.org>
387 gphat: Cory G Watson <gphat@cpan.org>
389 Grant Street Group L<http://www.grantstreet.com/>
391 groditi: Guillermo Roditi <groditi@cpan.org>
393 Haarg: Graham Knop <haarg@haarg.org>
395 hobbs: Andrew Rodland <arodland@cpan.org>
397 idn: Ian Norton <i.norton@shadowcat.co.uk>
399 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
401 initself: Mike Baas <mike@initselftech.com>
403 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
405 jawnsy: Jonathan Yu <jawnsy@cpan.org>
407 jasonmay: Jason May <jason.a.may@gmail.com>
411 jgoulah: John Goulah <jgoulah@cpan.org>
413 jguenther: Justin Guenther <jguenther@cpan.org>
415 jhannah: Jay Hannah <jay@jays.net>
417 jmac: Jason McIntosh <jmac@appleseed-sc.com>
419 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
421 jon: Jon Schutz <jjschutz@cpan.org>
423 jshirley: J. Shirley <jshirley@gmail.com>
425 kaare: Kaare Rasmussen
427 konobi: Scott McWhirter
429 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
431 lukes: Luke Saunders <luke.saunders@gmail.com>
433 marcus: Marcus Ramberg <mramberg@cpan.org>
435 mattlaw: Matt Lawrence
437 mattp: Matt Phillips <mattp@cpan.org>
439 mdk: Mark Keating <m.keating@shadowcat.co.uk>
443 michaelr: Michael Reddick <michael.reddick@gmail.com>
445 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
447 minty: Murray Walker <perl@minty.org>
449 mithaldu: Christian Walde <walde.christian@gmail.com>
451 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
453 mstratman: Mark A. Stratman <stratman@gmail.com>
455 ned: Neil de Carteret
457 nigel: Nigel Metheringham <nigelm@cpan.org>
459 ningu: David Kamholz <dkamholz@cpan.org>
461 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
463 norbi: Norbert Buchmuller <norbi@nix.hu>
465 nuba: Nuba Princigalli <nuba@cpan.org>
467 Numa: Dan Sully <daniel@cpan.org>
469 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
471 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
473 paulm: Paul Makepeace
475 penguin: K J Cheetham
477 perigrin: Chris Prather <chris@prather.org>
479 peter: Peter Collingbourne <peter@pcc.me.uk>
481 Peter Siklósi <einon@einon.hu>
483 Peter Valdemar ME<oslash>rch <peter@morch.com>
485 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
487 plu: Johannes Plunien <plu@cpan.org>
489 pplu: Jose Luis Martinez <jlmartinez@capside.com>
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 Stephen Peters <steve@stephenpeters.me>
535 talexb: Alex Beamish <talexb@gmail.com>
537 tamias: Ronald J Kimball <rjk@tamias.net>
539 TBSliver: Tom Bloor <t.bloor@shadowcat.co.uk>
541 teejay : Aaron Trevena <teejay@cpan.org>
543 theorbtwo: James Mastros <james@mastros.biz>
549 tonvoon: Ton Voon <tonvoon@cpan.org>
551 triode: Pete Gamache <gamache@cpan.org>
553 typester: Daisuke Murase <typester@cpan.org>
555 victori: Victor Igumnov <victori@cpan.org>
559 wesm: Wes Malone <wes@mitsi.com>
561 willert: Sebastian Willert <willert@cpan.org>
563 wreis: Wallace Reis <wreis@cpan.org>
565 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
567 uree: Oriol Soriano <oriol.soriano@capside.com>
569 yrlnry: Mark Jason Dominus <mjd@plover.com>
571 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
573 Zefram: Andrew Main <zefram@fysh.org>
577 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
582 This library is free software and may be distributed under the same terms