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