9 use DBIx::Class::Optional::Dependencies;
11 use vars qw($VERSION);
12 use base qw/DBIx::Class::Componentised Class::Accessor::Grouped/;
13 use DBIx::Class::StartupCheck;
16 shift->mk_classaccessor(@_);
19 sub mk_classaccessor {
21 $self->mk_group_accessors('inherited', $_[0]);
22 $self->set_inherited(@_) if @_ > 1;
25 sub component_base_class { 'DBIx::Class' }
27 # Always remember to do all digits for the version even if they're 0
28 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
29 # brain damage and presumably various other packaging systems too
32 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
34 sub MODIFY_CODE_ATTRIBUTES {
35 my ($class,$code,@attrs) = @_;
36 $class->mk_classdata('__attr_cache' => {})
37 unless $class->can('__attr_cache');
38 $class->__attr_cache->{$code} = [@attrs];
44 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
48 %{ $self->maybe::next::method || {} },
54 Git-season is OPEN! Ask about 'dbic commit?', and get busy :) | DBIC: 0.08124, Schema::Loader: 0.07002 | NO PASTING, use http://paste.scsys.co.uk | Query syntax is perldoc SQL::Abstract | "many_to_many" is not a relationship | DBIC_TRACE=1 | chainsaw delegates - DBIC: ribasushi, Schema::Loader: ribasushi | < dnm> MySQL is a piece of horsesnot.
58 DBIx::Class - Extensible and flexible object <-> relational mapper.
60 =head1 GETTING HELP/SUPPORT
62 The community can be found via:
66 =item * IRC: irc.perl.org#dbix-class
69 <a href="http://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
71 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
73 =item * RT Bug Tracker: L<https://rt.cpan.org/Dist/Display.html?Queue=DBIx-Class>
75 =item * gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
77 =item * git: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
79 =item * twitter L<http://www.twitter.com/dbix_class>
85 Create a schema class called MyDB/Schema.pm:
88 use base qw/DBIx::Class::Schema/;
90 __PACKAGE__->load_namespaces();
94 Create a result class to represent artists, who have many CDs, in
95 MyDB/Schema/Result/Artist.pm:
97 See L<DBIx::Class::ResultSource> for docs on defining result classes.
99 package MyDB::Schema::Result::Artist;
100 use base qw/DBIx::Class::Core/;
102 __PACKAGE__->table('artist');
103 __PACKAGE__->add_columns(qw/ artistid name /);
104 __PACKAGE__->set_primary_key('artistid');
105 __PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD');
109 A result class to represent a CD, which belongs to an artist, in
110 MyDB/Schema/Result/CD.pm:
112 package MyDB::Schema::Result::CD;
113 use base qw/DBIx::Class::Core/;
115 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
116 __PACKAGE__->table('cd');
117 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
118 __PACKAGE__->set_primary_key('cdid');
119 __PACKAGE__->belongs_to(artist => 'MyDB::Schema::Artist', 'artistid');
123 Then you can use these classes in your application's code:
125 # Connect to your database.
127 my $schema = MyDB::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
129 # Query for all artists and put them in an array,
130 # or retrieve them as a result set object.
131 # $schema->resultset returns a DBIx::Class::ResultSet
132 my @all_artists = $schema->resultset('Artist')->all;
133 my $all_artists_rs = $schema->resultset('Artist');
135 # Output all artists names
136 # $artist here is a DBIx::Class::Row, which has accessors
137 # for all its columns. Rows are also subclasses of your Result class.
138 foreach $artist (@all_artists) {
139 print $artist->name, "\n";
142 # Create a result set to search for artists.
143 # This does not query the DB.
144 my $johns_rs = $schema->resultset('Artist')->search(
145 # Build your WHERE using an SQL::Abstract structure:
146 { name => { like => 'John%' } }
149 # Execute a joined query to get the cds.
150 my @all_john_cds = $johns_rs->search_related('cds')->all;
152 # Fetch the next available row.
153 my $first_john = $johns_rs->next;
155 # Specify ORDER BY on the query.
156 my $first_john_cds_by_title_rs = $first_john->cds(
158 { order_by => 'title' }
161 # Create a result set that will fetch the artist data
162 # at the same time as it fetches CDs, using only one query.
163 my $millennium_cds_rs = $schema->resultset('CD')->search(
165 { prefetch => 'artist' }
168 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
169 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
171 # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
172 # create() is the same as new() then insert().
173 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
174 $new_cd->artist($cd->artist);
175 $new_cd->insert; # Auto-increment primary key filled in after INSERT
176 $new_cd->title('Fork');
178 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
180 # change the year of all the millennium CDs at once
181 $millennium_cds_rs->update({ year => 2002 });
185 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
186 (with a compatibility layer as a springboard for porting) and a resultset API
187 that allows abstract encapsulation of database operations. It aims to make
188 representing queries in your code as perl-ish as possible while still
189 providing access to as many of the capabilities of the database as possible,
190 including retrieving related records from multiple tables in a single query,
191 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
193 DBIx::Class can handle multi-column primary and foreign keys, complex
194 queries and database-level paging, and does its best to only query the
195 database in order to return something you've directly asked for. If a
196 resultset is used as an iterator it only fetches rows off the statement
197 handle as requested in order to minimise memory usage. It has auto-increment
198 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
199 known to be used in production on at least the first four, and is fork-
200 and thread-safe out of the box (although your DBD may not be).
202 This project is still under rapid development, so large new features may be
203 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
204 Failing test cases are *always* welcome and point releases are put out rapidly
205 as bugs are found and fixed.
207 We do our best to maintain full backwards compatibility for published
208 APIs, since DBIx::Class is used in production in many organisations,
209 and even backwards incompatible changes to non-published APIs will be fixed
210 if they're reported and doing so doesn't cost the codebase anything.
212 The test suite is quite substantial, and several developer releases
213 are generally made to CPAN before the branch for the next release is
214 merged back to trunk for a major release.
216 =head1 WHERE TO GO NEXT
218 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
219 the modules where you will find documentation.
223 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
225 (I mostly consider myself "project founder" these days but the AUTHOR heading
230 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
232 aherzog: Adam Herzog <adam@herzogdesigns.com>
234 Alexander Keusch <cpan@keusch.at>
236 amiri: Amiri Barksdale <amiri@metalabel.com>
238 amoore: Andrew Moore <amoore@cpan.org>
240 andyg: Andy Grundman <andy@hybridized.org>
244 arc: Aaron Crane <arc@cpan.org>
246 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
248 ash: Ash Berlin <ash@cpan.org>
250 bert: Norbert Csongradi <bert@cpan.org>
252 blblack: Brandon L. Black <blblack@gmail.com>
254 bluefeet: Aran Deltac <bluefeet@cpan.org>
256 boghead: Bryan Beeley <cpan@beeley.org>
258 bricas: Brian Cassidy <bricas@cpan.org>
260 brunov: Bruno Vecchi <vecchi.b@gmail.com>
262 caelum: Rafael Kitover <rkitover@cpan.org>
264 castaway: Jess Robinson
266 claco: Christopher H. Laco
270 da5id: David Jack Olrik <djo@cpan.org>
272 debolaz: Anders Nor Berle <berle@cpan.org>
274 dew: Dan Thomas <dan@godders.org>
276 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
278 dnm: Justin Wheeler <jwheeler@datademons.com>
280 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
282 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
284 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
286 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
288 goraxe: Gordon Irving <goraxe@cpan.org>
290 gphat: Cory G Watson <gphat@cpan.org>
292 groditi: Guillermo Roditi <groditi@cpan.org>
294 Haarg: Graham Knop <haarg@haarg.org>
296 hobbs: Andrew Rodland <arodland@cpan.org>
298 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
300 jasonmay: Jason May <jason.a.may@gmail.com>
304 jgoulah: John Goulah <jgoulah@cpan.org>
306 jguenther: Justin Guenther <jguenther@cpan.org>
308 jhannah: Jay Hannah <jay@jays.net>
310 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
312 jon: Jon Schutz <jjschutz@cpan.org>
314 jshirley: J. Shirley <jshirley@gmail.com>
316 konobi: Scott McWhirter
318 lukes: Luke Saunders <luke.saunders@gmail.com>
320 marcus: Marcus Ramberg <mramberg@cpan.org>
322 mattlaw: Matt Lawrence
324 michaelr: Michael Reddick <michael.reddick@gmail.com>
326 ned: Neil de Carteret
328 nigel: Nigel Metheringham <nigelm@cpan.org>
330 ningu: David Kamholz <dkamholz@cpan.org>
332 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
334 norbi: Norbert Buchmuller <norbi@nix.hu>
336 nuba: Nuba Princigalli <nuba@cpan.org>
338 Numa: Dan Sully <daniel@cpan.org>
340 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
342 oyse: Øystein Torget <oystein.torget@dnv.com>
344 paulm: Paul Makepeace
346 penguin: K J Cheetham
348 perigrin: Chris Prather <chris@prather.org>
350 peter: Peter Collingbourne <peter@pcc.me.uk>
352 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
354 plu: Johannes Plunien <plu@cpan.org>
356 Possum: Daniel LeWarne <possum@cpan.org>
358 quicksilver: Jules Bean
360 rafl: Florian Ragwitz <rafl@debian.org>
362 rainboxx: Matthias Dietrich <perl@rb.ly>
364 rbo: Robert Bohne <rbo@cpan.org>
366 rbuels: Robert Buels <rmb32@cornell.edu>
368 rdj: Ryan D Johnson <ryan@innerfence.com>
370 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
372 rjbs: Ricardo Signes <rjbs@cpan.org>
374 robkinyon: Rob Kinyon <rkinyon@cpan.org>
376 Roman: Roman Filippov <romanf@cpan.org>
378 sc_: Just Another Perl Hacker
380 scotty: Scotty Allen <scotty@scottyallen.com>
382 semifor: Marc Mims <marc@questright.com>
384 solomon: Jared Johnson <jaredj@nmgi.com>
386 spb: Stephen Bennett <stephen@freenode.net>
388 sszabo: Stephan Szabo <sszabo@bigpanda.com>
390 teejay : Aaron Trevena <teejay@cpan.org>
396 tonvoon: Ton Voon <tonvoon@cpan.org>
398 triode: Pete Gamache <gamache@cpan.org>
400 typester: Daisuke Murase <typester@cpan.org>
402 victori: Victor Igumnov <victori@cpan.org>
406 willert: Sebastian Willert <willert@cpan.org>
408 wreis: Wallace Reis <wreis@cpan.org>
410 yrlnry: Mark Jason Dominus <mjd@plover.com>
412 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
416 Copyright (c) 2005 - 2010 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
421 This library is free software and may be distributed under the same terms