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