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>
277 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
279 (I mostly consider myself "project founder" these days but the AUTHOR heading
284 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
286 acca: Alexander Kuznetsov <acca@cpan.org>
288 aherzog: Adam Herzog <adam@herzogdesigns.com>
290 Alexander Keusch <cpan@keusch.at>
292 alexrj: Alessandro Ranellucci <aar@cpan.org>
294 alnewkirk: Al Newkirk <we@ana.im>
296 amiri: Amiri Barksdale <amiri@metalabel.com>
298 amoore: Andrew Moore <amoore@cpan.org>
300 andrewalker: Andre Walker <andre@andrewalker.net>
302 andyg: Andy Grundman <andy@hybridized.org>
306 arc: Aaron Crane <arc@cpan.org>
308 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
310 ash: Ash Berlin <ash@cpan.org>
312 bert: Norbert Csongrádi <bert@cpan.org>
314 blblack: Brandon L. Black <blblack@gmail.com>
316 bluefeet: Aran Deltac <bluefeet@cpan.org>
318 bphillips: Brian Phillips <bphillips@cpan.org>
320 boghead: Bryan Beeley <cpan@beeley.org>
322 brd: Brad Davis <brd@FreeBSD.org>
324 bricas: Brian Cassidy <bricas@cpan.org>
326 brunov: Bruno Vecchi <vecchi.b@gmail.com>
328 caelum: Rafael Kitover <rkitover@cpan.org>
330 caldrin: Maik Hentsche <maik.hentsche@amd.com>
332 castaway: Jess Robinson
334 claco: Christopher H. Laco
338 da5id: David Jack Olrik <djo@cpan.org>
340 dariusj: Darius Jokilehto <dariusjokilehto@yahoo.co.uk>
342 davewood: David Schmidt <davewood@gmx.at>
344 daxim: Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim@cpan.org>
346 debolaz: Anders Nor Berle <berle@cpan.org>
348 dew: Dan Thomas <dan@godders.org>
350 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
352 dnm: Justin Wheeler <jwheeler@datademons.com>
354 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
356 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
358 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
360 edenc: Eden Cardim <edencardim@gmail.com>
362 ether: Karen Etheridge <ether@cpan.org>
364 felliott: Fitz Elliott <fitz.elliott@gmail.com>
366 freetime: Bill Moseley <moseley@hank.org>
368 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
370 goraxe: Gordon Irving <goraxe@cpan.org>
372 gphat: Cory G Watson <gphat@cpan.org>
374 Grant Street Group L<http://www.grantstreet.com/>
376 groditi: Guillermo Roditi <groditi@cpan.org>
378 Haarg: Graham Knop <haarg@haarg.org>
380 hobbs: Andrew Rodland <arodland@cpan.org>
382 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
384 initself: Mike Baas <mike@initselftech.com>
386 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
388 jawnsy: Jonathan Yu <jawnsy@cpan.org>
390 jasonmay: Jason May <jason.a.may@gmail.com>
394 jgoulah: John Goulah <jgoulah@cpan.org>
396 jguenther: Justin Guenther <jguenther@cpan.org>
398 jhannah: Jay Hannah <jay@jays.net>
400 jmac: Jason McIntosh <jmac@appleseed-sc.com>
402 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
404 jon: Jon Schutz <jjschutz@cpan.org>
406 jshirley: J. Shirley <jshirley@gmail.com>
408 kaare: Kaare Rasmussen
410 konobi: Scott McWhirter
412 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
414 lukes: Luke Saunders <luke.saunders@gmail.com>
416 marcus: Marcus Ramberg <mramberg@cpan.org>
418 mattlaw: Matt Lawrence
420 mattp: Matt Phillips <mattp@cpan.org>
422 michaelr: Michael Reddick <michael.reddick@gmail.com>
424 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
426 mithaldu: Christian Walde <walde.christian@gmail.com>
428 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
430 mstratman: Mark A. Stratman <stratman@gmail.com>
432 ned: Neil de Carteret
434 nigel: Nigel Metheringham <nigelm@cpan.org>
436 ningu: David Kamholz <dkamholz@cpan.org>
438 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
440 norbi: Norbert Buchmuller <norbi@nix.hu>
442 nuba: Nuba Princigalli <nuba@cpan.org>
444 Numa: Dan Sully <daniel@cpan.org>
446 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
448 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
450 paulm: Paul Makepeace
452 penguin: K J Cheetham
454 perigrin: Chris Prather <chris@prather.org>
456 peter: Peter Collingbourne <peter@pcc.me.uk>
458 Peter Siklósi <einon@einon.hu>
460 Peter Valdemar ME<oslash>rch <peter@morch.com>
462 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
464 plu: Johannes Plunien <plu@cpan.org>
466 Possum: Daniel LeWarne <possum@cpan.org>
468 quicksilver: Jules Bean
470 rafl: Florian Ragwitz <rafl@debian.org>
472 rainboxx: Matthias Dietrich <perl@rb.ly>
474 rbo: Robert Bohne <rbo@cpan.org>
476 rbuels: Robert Buels <rmb32@cornell.edu>
478 rdj: Ryan D Johnson <ryan@innerfence.com>
480 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
482 rjbs: Ricardo Signes <rjbs@cpan.org>
484 robkinyon: Rob Kinyon <rkinyon@cpan.org>
486 Robert Olson <bob@rdolson.org>
488 moltar: Roman Filippov <romanf@cpan.org>
490 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
492 sc_: Just Another Perl Hacker
494 scotty: Scotty Allen <scotty@scottyallen.com>
496 semifor: Marc Mims <marc@questright.com>
498 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
500 solomon: Jared Johnson <jaredj@nmgi.com>
502 spb: Stephen Bennett <stephen@freenode.net>
504 Squeeks <squeek@cpan.org>
506 sszabo: Stephan Szabo <sszabo@bigpanda.com>
508 talexb: Alex Beamish <talexb@gmail.com>
510 tamias: Ronald J Kimball <rjk@tamias.net>
512 teejay : Aaron Trevena <teejay@cpan.org>
518 tonvoon: Ton Voon <tonvoon@cpan.org>
520 triode: Pete Gamache <gamache@cpan.org>
522 typester: Daisuke Murase <typester@cpan.org>
524 victori: Victor Igumnov <victori@cpan.org>
528 wesm: Wes Malone <wes@mitsi.com>
530 willert: Sebastian Willert <willert@cpan.org>
532 wreis: Wallace Reis <wreis@cpan.org>
534 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
536 yrlnry: Mark Jason Dominus <mjd@plover.com>
538 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
540 Zefram: Andrew Main <zefram@fysh.org>
544 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
549 This library is free software and may be distributed under the same terms