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
19 package # hide from pause
27 BROKEN_FORK => ($^O eq 'MSWin32') ? 1 : 0,
29 HAS_ITHREADS => $Config{useithreads} ? 1 : 0,
31 # ::Runmode would only be loaded by DBICTest, which in turn implies t/
32 DBICTEST => eval { DBICTest::RunMode->is_author } ? 1 : 0,
34 # During 5.13 dev cycle HELEMs started to leak on copy
36 # request for all tests would force "non-leaky" illusion and vice-versa
37 defined $ENV{DBICTEST_ALL_LEAKS} ? !$ENV{DBICTEST_ALL_LEAKS}
38 # otherwise confess that this perl is busted ONLY on smokers
39 : eval { DBICTest::RunMode->is_smoker } && ($] >= 5.013005 and $] <= 5.013006) ? 1
40 # otherwise we are good
44 # There was a brief period of p5p insanity when $@ was invisible in a DESTROY
45 INVISIBLE_DOLLAR_AT => ($] >= 5.013001 and $] <= 5.013007) ? 1 : 0,
51 constant->import( OLD_MRO => 1 );
55 constant->import( OLD_MRO => 0 );
61 use DBIx::Class::Optional::Dependencies;
63 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
64 use DBIx::Class::StartupCheck;
66 __PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
67 __PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny|^Class::Accessor::Grouped|^Context::Preserve');
70 shift->mk_classaccessor(@_);
73 sub mk_classaccessor {
75 $self->mk_group_accessors('inherited', $_[0]);
76 $self->set_inherited(@_) if @_ > 1;
79 sub component_base_class { 'DBIx::Class' }
81 sub MODIFY_CODE_ATTRIBUTES {
82 my ($class,$code,@attrs) = @_;
83 $class->mk_classdata('__attr_cache' => {})
84 unless $class->can('__attr_cache');
85 $class->__attr_cache->{$code} = [@attrs];
91 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
95 %{ $self->maybe::next::method || {} },
103 DBIx::Class - Extensible and flexible object <-> relational mapper.
105 =head1 GETTING HELP/SUPPORT
107 The community can be found via:
111 =item * IRC: irc.perl.org#dbix-class
114 <a href="http://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
116 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
118 =item * Twitter L<http://www.twitter.com/dbix_class>
120 =item * Web Site: L<http://www.dbix-class.org/>
122 =item * RT Bug Tracker: L<https://rt.cpan.org/Dist/Display.html?Queue=DBIx-Class>
126 The project is maintained in a git repository, accessible from the following sources:
130 =item * git: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
132 =item * gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
134 =item * github mirror: L<https://github.com/dbsrgits/DBIx-Class>
136 =item * authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/DBIx-Class.git>
142 Create a schema class called MyApp/Schema.pm:
144 package MyApp::Schema;
145 use base qw/DBIx::Class::Schema/;
147 __PACKAGE__->load_namespaces();
151 Create a result class to represent artists, who have many CDs, in
152 MyApp/Schema/Result/Artist.pm:
154 See L<DBIx::Class::ResultSource> for docs on defining result classes.
156 package MyApp::Schema::Result::Artist;
157 use base qw/DBIx::Class::Core/;
159 __PACKAGE__->table('artist');
160 __PACKAGE__->add_columns(qw/ artistid name /);
161 __PACKAGE__->set_primary_key('artistid');
162 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');
166 A result class to represent a CD, which belongs to an artist, in
167 MyApp/Schema/Result/CD.pm:
169 package MyApp::Schema::Result::CD;
170 use base qw/DBIx::Class::Core/;
172 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
173 __PACKAGE__->table('cd');
174 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
175 __PACKAGE__->set_primary_key('cdid');
176 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
180 Then you can use these classes in your application's code:
182 # Connect to your database.
184 my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
186 # Query for all artists and put them in an array,
187 # or retrieve them as a result set object.
188 # $schema->resultset returns a DBIx::Class::ResultSet
189 my @all_artists = $schema->resultset('Artist')->all;
190 my $all_artists_rs = $schema->resultset('Artist');
192 # Output all artists names
193 # $artist here is a DBIx::Class::Row, which has accessors
194 # for all its columns. Rows are also subclasses of your Result class.
195 foreach $artist (@all_artists) {
196 print $artist->name, "\n";
199 # Create a result set to search for artists.
200 # This does not query the DB.
201 my $johns_rs = $schema->resultset('Artist')->search(
202 # Build your WHERE using an SQL::Abstract structure:
203 { name => { like => 'John%' } }
206 # Execute a joined query to get the cds.
207 my @all_john_cds = $johns_rs->search_related('cds')->all;
209 # Fetch the next available row.
210 my $first_john = $johns_rs->next;
212 # Specify ORDER BY on the query.
213 my $first_john_cds_by_title_rs = $first_john->cds(
215 { order_by => 'title' }
218 # Create a result set that will fetch the artist data
219 # at the same time as it fetches CDs, using only one query.
220 my $millennium_cds_rs = $schema->resultset('CD')->search(
222 { prefetch => 'artist' }
225 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
226 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
228 # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
229 # create() is the same as new() then insert().
230 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
231 $new_cd->artist($cd->artist);
232 $new_cd->insert; # Auto-increment primary key filled in after INSERT
233 $new_cd->title('Fork');
235 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
237 # change the year of all the millennium CDs at once
238 $millennium_cds_rs->update({ year => 2002 });
242 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
243 (with a compatibility layer as a springboard for porting) and a resultset API
244 that allows abstract encapsulation of database operations. It aims to make
245 representing queries in your code as perl-ish as possible while still
246 providing access to as many of the capabilities of the database as possible,
247 including retrieving related records from multiple tables in a single query,
248 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
250 DBIx::Class can handle multi-column primary and foreign keys, complex
251 queries and database-level paging, and does its best to only query the
252 database in order to return something you've directly asked for. If a
253 resultset is used as an iterator it only fetches rows off the statement
254 handle as requested in order to minimise memory usage. It has auto-increment
255 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
256 known to be used in production on at least the first four, and is fork-
257 and thread-safe out of the box (although
258 L<your DBD may not be|DBI/Threads and Thread Safety>).
260 This project is still under rapid development, so large new features may be
261 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
262 Failing test cases are *always* welcome and point releases are put out rapidly
263 as bugs are found and fixed.
265 We do our best to maintain full backwards compatibility for published
266 APIs, since DBIx::Class is used in production in many organisations,
267 and even backwards incompatible changes to non-published APIs will be fixed
268 if they're reported and doing so doesn't cost the codebase anything.
270 The test suite is quite substantial, and several developer releases
271 are generally made to CPAN before the branch for the next release is
272 merged back to trunk for a major release.
274 =head1 WHERE TO GO NEXT
276 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
277 the modules where you will find documentation.
281 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
283 (I mostly consider myself "project founder" these days but the AUTHOR heading
288 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
290 acca: Alexander Kuznetsov <acca@cpan.org>
292 aherzog: Adam Herzog <adam@herzogdesigns.com>
294 Alexander Keusch <cpan@keusch.at>
296 alexrj: Alessandro Ranellucci <aar@cpan.org>
298 alnewkirk: Al Newkirk <we@ana.im>
300 amiri: Amiri Barksdale <amiri@metalabel.com>
302 amoore: Andrew Moore <amoore@cpan.org>
304 andyg: Andy Grundman <andy@hybridized.org>
308 arc: Aaron Crane <arc@cpan.org>
310 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
312 ash: Ash Berlin <ash@cpan.org>
314 bert: Norbert Csongradi <bert@cpan.org>
316 blblack: Brandon L. Black <blblack@gmail.com>
318 bluefeet: Aran Deltac <bluefeet@cpan.org>
320 bphillips: Brian Phillips <bphillips@cpan.org>
322 boghead: Bryan Beeley <cpan@beeley.org>
324 brd: Brad Davis <brd@FreeBSD.org>
326 bricas: Brian Cassidy <bricas@cpan.org>
328 brunov: Bruno Vecchi <vecchi.b@gmail.com>
330 caelum: Rafael Kitover <rkitover@cpan.org>
332 caldrin: Maik Hentsche <maik.hentsche@amd.com>
334 castaway: Jess Robinson
336 claco: Christopher H. Laco
340 da5id: David Jack Olrik <djo@cpan.org>
342 debolaz: Anders Nor Berle <berle@cpan.org>
344 dew: Dan Thomas <dan@godders.org>
346 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
348 dnm: Justin Wheeler <jwheeler@datademons.com>
350 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
352 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
354 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
356 edenc: Eden Cardim <edencardim@gmail.com>
358 felliott: Fitz Elliott <fitz.elliott@gmail.com>
360 freetime: Bill Moseley <moseley@hank.org>
362 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
364 goraxe: Gordon Irving <goraxe@cpan.org>
366 gphat: Cory G Watson <gphat@cpan.org>
368 Grant Street Group L<http://www.grantstreet.com/>
370 groditi: Guillermo Roditi <groditi@cpan.org>
372 Haarg: Graham Knop <haarg@haarg.org>
374 hobbs: Andrew Rodland <arodland@cpan.org>
376 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
378 initself: Mike Baas <mike@initselftech.com>
380 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
382 jawnsy: Jonathan Yu <jawnsy@cpan.org>
384 jasonmay: Jason May <jason.a.may@gmail.com>
388 jgoulah: John Goulah <jgoulah@cpan.org>
390 jguenther: Justin Guenther <jguenther@cpan.org>
392 jhannah: Jay Hannah <jay@jays.net>
394 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
396 jon: Jon Schutz <jjschutz@cpan.org>
398 jshirley: J. Shirley <jshirley@gmail.com>
400 kaare: Kaare Rasmussen
402 konobi: Scott McWhirter
404 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
406 lukes: Luke Saunders <luke.saunders@gmail.com>
408 marcus: Marcus Ramberg <mramberg@cpan.org>
410 mattlaw: Matt Lawrence
412 mattp: Matt Phillips <mattp@cpan.org>
414 michaelr: Michael Reddick <michael.reddick@gmail.com>
416 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
418 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
420 mstratman: Mark A. Stratman <stratman@gmail.com>
422 ned: Neil de Carteret
424 nigel: Nigel Metheringham <nigelm@cpan.org>
426 ningu: David Kamholz <dkamholz@cpan.org>
428 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
430 norbi: Norbert Buchmuller <norbi@nix.hu>
432 nuba: Nuba Princigalli <nuba@cpan.org>
434 Numa: Dan Sully <daniel@cpan.org>
436 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
438 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
440 paulm: Paul Makepeace
442 penguin: K J Cheetham
444 perigrin: Chris Prather <chris@prather.org>
446 peter: Peter Collingbourne <peter@pcc.me.uk>
448 Peter Valdemar ME<oslash>rch <peter@morch.com>
450 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
452 plu: Johannes Plunien <plu@cpan.org>
454 Possum: Daniel LeWarne <possum@cpan.org>
456 quicksilver: Jules Bean
458 rafl: Florian Ragwitz <rafl@debian.org>
460 rainboxx: Matthias Dietrich <perl@rb.ly>
462 rbo: Robert Bohne <rbo@cpan.org>
464 rbuels: Robert Buels <rmb32@cornell.edu>
466 rdj: Ryan D Johnson <ryan@innerfence.com>
468 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
470 rjbs: Ricardo Signes <rjbs@cpan.org>
472 robkinyon: Rob Kinyon <rkinyon@cpan.org>
474 Robert Olson <bob@rdolson.org>
476 Roman: Roman Filippov <romanf@cpan.org>
478 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
480 sc_: Just Another Perl Hacker
482 scotty: Scotty Allen <scotty@scottyallen.com>
484 semifor: Marc Mims <marc@questright.com>
486 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
488 solomon: Jared Johnson <jaredj@nmgi.com>
490 spb: Stephen Bennett <stephen@freenode.net>
492 Squeeks <squeek@cpan.org>
494 sszabo: Stephan Szabo <sszabo@bigpanda.com>
496 talexb: Alex Beamish <talexb@gmail.com>
498 tamias: Ronald J Kimball <rjk@tamias.net>
500 teejay : Aaron Trevena <teejay@cpan.org>
506 tonvoon: Ton Voon <tonvoon@cpan.org>
508 triode: Pete Gamache <gamache@cpan.org>
510 typester: Daisuke Murase <typester@cpan.org>
512 victori: Victor Igumnov <victori@cpan.org>
516 wesm: Wes Malone <wes@mitsi.com>
518 willert: Sebastian Willert <willert@cpan.org>
520 wreis: Wallace Reis <wreis@cpan.org>
522 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
524 yrlnry: Mark Jason Dominus <mjd@plover.com>
526 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
530 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
535 This library is free software and may be distributed under the same terms