9 *DBIx::Class::_ENV_::OLD_MRO = sub () { 1 };
13 *DBIx::Class::_ENV_::OLD_MRO = sub () { 0 };
16 # ::Runmode would only be loaded by DBICTest, which in turn implies t/
17 *DBIx::Class::_ENV_::DBICTEST = eval { DBICTest::RunMode->is_author }
25 use DBIx::Class::Optional::Dependencies;
27 use vars qw($VERSION);
28 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
29 use DBIx::Class::StartupCheck;
32 shift->mk_classaccessor(@_);
35 sub mk_classaccessor {
37 $self->mk_group_accessors('inherited', $_[0]);
38 $self->set_inherited(@_) if @_ > 1;
41 sub component_base_class { 'DBIx::Class' }
43 # Always remember to do all digits for the version even if they're 0
44 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
45 # brain damage and presumably various other packaging systems too
48 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
50 sub MODIFY_CODE_ATTRIBUTES {
51 my ($class,$code,@attrs) = @_;
52 $class->mk_classdata('__attr_cache' => {})
53 unless $class->can('__attr_cache');
54 $class->__attr_cache->{$code} = [@attrs];
60 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
64 %{ $self->maybe::next::method || {} },
72 DBIx::Class - Extensible and flexible object <-> relational mapper.
74 =head1 GETTING HELP/SUPPORT
76 The community can be found via:
80 =item * Web Site: L<http://www.dbix-class.org/>
82 =item * IRC: irc.perl.org#dbix-class
85 <a href="http://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
87 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
89 =item * RT Bug Tracker: L<https://rt.cpan.org/Dist/Display.html?Queue=DBIx-Class>
91 =item * gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
93 =item * git: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
95 =item * twitter L<http://www.twitter.com/dbix_class>
101 Create a schema class called MyDB/Schema.pm:
103 package MyDB::Schema;
104 use base qw/DBIx::Class::Schema/;
106 __PACKAGE__->load_namespaces();
110 Create a result class to represent artists, who have many CDs, in
111 MyDB/Schema/Result/Artist.pm:
113 See L<DBIx::Class::ResultSource> for docs on defining result classes.
115 package MyDB::Schema::Result::Artist;
116 use base qw/DBIx::Class::Core/;
118 __PACKAGE__->table('artist');
119 __PACKAGE__->add_columns(qw/ artistid name /);
120 __PACKAGE__->set_primary_key('artistid');
121 __PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD');
125 A result class to represent a CD, which belongs to an artist, in
126 MyDB/Schema/Result/CD.pm:
128 package MyDB::Schema::Result::CD;
129 use base qw/DBIx::Class::Core/;
131 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
132 __PACKAGE__->table('cd');
133 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
134 __PACKAGE__->set_primary_key('cdid');
135 __PACKAGE__->belongs_to(artist => 'MyDB::Schema::Result::Artist', 'artistid');
139 Then you can use these classes in your application's code:
141 # Connect to your database.
143 my $schema = MyDB::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
145 # Query for all artists and put them in an array,
146 # or retrieve them as a result set object.
147 # $schema->resultset returns a DBIx::Class::ResultSet
148 my @all_artists = $schema->resultset('Artist')->all;
149 my $all_artists_rs = $schema->resultset('Artist');
151 # Output all artists names
152 # $artist here is a DBIx::Class::Row, which has accessors
153 # for all its columns. Rows are also subclasses of your Result class.
154 foreach $artist (@all_artists) {
155 print $artist->name, "\n";
158 # Create a result set to search for artists.
159 # This does not query the DB.
160 my $johns_rs = $schema->resultset('Artist')->search(
161 # Build your WHERE using an SQL::Abstract structure:
162 { name => { like => 'John%' } }
165 # Execute a joined query to get the cds.
166 my @all_john_cds = $johns_rs->search_related('cds')->all;
168 # Fetch the next available row.
169 my $first_john = $johns_rs->next;
171 # Specify ORDER BY on the query.
172 my $first_john_cds_by_title_rs = $first_john->cds(
174 { order_by => 'title' }
177 # Create a result set that will fetch the artist data
178 # at the same time as it fetches CDs, using only one query.
179 my $millennium_cds_rs = $schema->resultset('CD')->search(
181 { prefetch => 'artist' }
184 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
185 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
187 # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
188 # create() is the same as new() then insert().
189 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
190 $new_cd->artist($cd->artist);
191 $new_cd->insert; # Auto-increment primary key filled in after INSERT
192 $new_cd->title('Fork');
194 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
196 # change the year of all the millennium CDs at once
197 $millennium_cds_rs->update({ year => 2002 });
201 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
202 (with a compatibility layer as a springboard for porting) and a resultset API
203 that allows abstract encapsulation of database operations. It aims to make
204 representing queries in your code as perl-ish as possible while still
205 providing access to as many of the capabilities of the database as possible,
206 including retrieving related records from multiple tables in a single query,
207 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
209 DBIx::Class can handle multi-column primary and foreign keys, complex
210 queries and database-level paging, and does its best to only query the
211 database in order to return something you've directly asked for. If a
212 resultset is used as an iterator it only fetches rows off the statement
213 handle as requested in order to minimise memory usage. It has auto-increment
214 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
215 known to be used in production on at least the first four, and is fork-
216 and thread-safe out of the box (although
217 L<your DBD may not be|DBI/Threads_and_Thread_Safety>).
219 This project is still under rapid development, so large new features may be
220 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
221 Failing test cases are *always* welcome and point releases are put out rapidly
222 as bugs are found and fixed.
224 We do our best to maintain full backwards compatibility for published
225 APIs, since DBIx::Class is used in production in many organisations,
226 and even backwards incompatible changes to non-published APIs will be fixed
227 if they're reported and doing so doesn't cost the codebase anything.
229 The test suite is quite substantial, and several developer releases
230 are generally made to CPAN before the branch for the next release is
231 merged back to trunk for a major release.
233 =head1 WHERE TO GO NEXT
235 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
236 the modules where you will find documentation.
240 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
242 (I mostly consider myself "project founder" these days but the AUTHOR heading
247 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
249 aherzog: Adam Herzog <adam@herzogdesigns.com>
251 Alexander Keusch <cpan@keusch.at>
253 alnewkirk: Al Newkirk <we@ana.im>
255 amiri: Amiri Barksdale <amiri@metalabel.com>
257 amoore: Andrew Moore <amoore@cpan.org>
259 andyg: Andy Grundman <andy@hybridized.org>
263 arc: Aaron Crane <arc@cpan.org>
265 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
267 ash: Ash Berlin <ash@cpan.org>
269 bert: Norbert Csongradi <bert@cpan.org>
271 blblack: Brandon L. Black <blblack@gmail.com>
273 bluefeet: Aran Deltac <bluefeet@cpan.org>
275 bphillips: Brian Phillips <bphillips@cpan.org>
277 boghead: Bryan Beeley <cpan@beeley.org>
279 bricas: Brian Cassidy <bricas@cpan.org>
281 brunov: Bruno Vecchi <vecchi.b@gmail.com>
283 caelum: Rafael Kitover <rkitover@cpan.org>
285 caldrin: Maik Hentsche <maik.hentsche@amd.com>
287 castaway: Jess Robinson
289 claco: Christopher H. Laco
293 da5id: David Jack Olrik <djo@cpan.org>
295 debolaz: Anders Nor Berle <berle@cpan.org>
297 dew: Dan Thomas <dan@godders.org>
299 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
301 dnm: Justin Wheeler <jwheeler@datademons.com>
303 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
305 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
307 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
309 freetime: Bill Moseley <moseley@hank.org>
311 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
313 goraxe: Gordon Irving <goraxe@cpan.org>
315 gphat: Cory G Watson <gphat@cpan.org>
317 Grant Street Group L<http://www.grantstreet.com/>
319 groditi: Guillermo Roditi <groditi@cpan.org>
321 Haarg: Graham Knop <haarg@haarg.org>
323 hobbs: Andrew Rodland <arodland@cpan.org>
325 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
327 initself: Mike Baas <mike@initselftech.com>
329 jawnsy: Jonathan Yu <jawnsy@cpan.org>
331 jasonmay: Jason May <jason.a.may@gmail.com>
335 jgoulah: John Goulah <jgoulah@cpan.org>
337 jguenther: Justin Guenther <jguenther@cpan.org>
339 jhannah: Jay Hannah <jay@jays.net>
341 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
343 jon: Jon Schutz <jjschutz@cpan.org>
345 jshirley: J. Shirley <jshirley@gmail.com>
347 kaare: Kaare Rasmussen
349 konobi: Scott McWhirter
351 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
353 lukes: Luke Saunders <luke.saunders@gmail.com>
355 marcus: Marcus Ramberg <mramberg@cpan.org>
357 mattlaw: Matt Lawrence
359 mattp: Matt Phillips <mattp@cpan.org>
361 michaelr: Michael Reddick <michael.reddick@gmail.com>
363 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
365 ned: Neil de Carteret
367 nigel: Nigel Metheringham <nigelm@cpan.org>
369 ningu: David Kamholz <dkamholz@cpan.org>
371 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
373 norbi: Norbert Buchmuller <norbi@nix.hu>
375 nuba: Nuba Princigalli <nuba@cpan.org>
377 Numa: Dan Sully <daniel@cpan.org>
379 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
381 oyse: Øystein Torget <oystein.torget@dnv.com>
383 paulm: Paul Makepeace
385 penguin: K J Cheetham
387 perigrin: Chris Prather <chris@prather.org>
389 peter: Peter Collingbourne <peter@pcc.me.uk>
391 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
393 plu: Johannes Plunien <plu@cpan.org>
395 Possum: Daniel LeWarne <possum@cpan.org>
397 quicksilver: Jules Bean
399 rafl: Florian Ragwitz <rafl@debian.org>
401 rainboxx: Matthias Dietrich <perl@rb.ly>
403 rbo: Robert Bohne <rbo@cpan.org>
405 rbuels: Robert Buels <rmb32@cornell.edu>
407 rdj: Ryan D Johnson <ryan@innerfence.com>
409 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
411 rjbs: Ricardo Signes <rjbs@cpan.org>
413 robkinyon: Rob Kinyon <rkinyon@cpan.org>
415 Roman: Roman Filippov <romanf@cpan.org>
417 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
419 sc_: Just Another Perl Hacker
421 scotty: Scotty Allen <scotty@scottyallen.com>
423 semifor: Marc Mims <marc@questright.com>
425 solomon: Jared Johnson <jaredj@nmgi.com>
427 spb: Stephen Bennett <stephen@freenode.net>
429 Squeeks <squeek@cpan.org>
431 sszabo: Stephan Szabo <sszabo@bigpanda.com>
433 talexb: Alex Beamish <talexb@gmail.com>
435 tamias: Ronald J Kimball <rjk@tamias.net>
437 teejay : Aaron Trevena <teejay@cpan.org>
443 tonvoon: Ton Voon <tonvoon@cpan.org>
445 triode: Pete Gamache <gamache@cpan.org>
447 typester: Daisuke Murase <typester@cpan.org>
449 victori: Victor Igumnov <victori@cpan.org>
453 willert: Sebastian Willert <willert@cpan.org>
455 wreis: Wallace Reis <wreis@cpan.org>
457 yrlnry: Mark Jason Dominus <mjd@plover.com>
459 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
463 Copyright (c) 2005 - 2010 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
468 This library is free software and may be distributed under the same terms