README
1NAME
2 DBIx::Class - Extensible and flexible object <-> relational mapper.
3
4GETTING HELP/SUPPORT
5 The community can be found via:
6
7 * IRC: <irc.perl.org#dbix-class (click for instant chatroom login) >
8
9 * Mailing list: <http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
10
11 * RT Bug Tracker:
12 <https://rt.cpan.org/Dist/Display.html?Queue=DBIx-Class>
13
14 * SVNWeb:
15 <http://dev.catalyst.perl.org/svnweb/bast/browse/DBIx-Class/0.08>
16
17 * SVN: <http://dev.catalyst.perl.org/repos/bast/DBIx-Class/0.08>
18
19SYNOPSIS
20 Create a schema class called MyDB/Schema.pm:
21
22 package MyDB::Schema;
23 use base qw/DBIx::Class::Schema/;
24
25 __PACKAGE__->load_namespaces();
26
27 1;
28
29 Create a result class to represent artists, who have many CDs, in
30 MyDB/Schema/Result/Artist.pm:
31
32 See DBIx::Class::ResultSource for docs on defining result classes.
33
34 package MyDB::Schema::Result::Artist;
35 use base qw/DBIx::Class::Core/;
36
37 __PACKAGE__->table('artist');
38 __PACKAGE__->add_columns(qw/ artistid name /);
39 __PACKAGE__->set_primary_key('artistid');
40 __PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD');
41
42 1;
43
44 A result class to represent a CD, which belongs to an artist, in
45 MyDB/Schema/Result/CD.pm:
46
47 package MyDB::Schema::Result::CD;
48 use base qw/DBIx::Class::Core/;
49
50 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
51 __PACKAGE__->table('cd');
52 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
53 __PACKAGE__->set_primary_key('cdid');
54 __PACKAGE__->belongs_to(artist => 'MyDB::Schema::Artist', 'artistid');
55
56 1;
57
58 Then you can use these classes in your application's code:
59
60 # Connect to your database.
61 use MyDB::Schema;
62 my $schema = MyDB::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
63
64 # Query for all artists and put them in an array,
65 # or retrieve them as a result set object.
66 # $schema->resultset returns a DBIx::Class::ResultSet
67 my @all_artists = $schema->resultset('Artist')->all;
68 my $all_artists_rs = $schema->resultset('Artist');
69
70 # Output all artists names
71 # $artist here is a DBIx::Class::Row, which has accessors
72 # for all its columns. Rows are also subclasses of your Result class.
73 foreach $artist (@all_artists) {
74 print $artist->name, "\n";
75 }
76
77 # Create a result set to search for artists.
78 # This does not query the DB.
79 my $johns_rs = $schema->resultset('Artist')->search(
80 # Build your WHERE using an SQL::Abstract structure:
81 { name => { like => 'John%' } }
82 );
83
84 # Execute a joined query to get the cds.
85 my @all_john_cds = $johns_rs->search_related('cds')->all;
86
87 # Fetch the next available row.
88 my $first_john = $johns_rs->next;
89
90 # Specify ORDER BY on the query.
91 my $first_john_cds_by_title_rs = $first_john->cds(
92 undef,
93 { order_by => 'title' }
94 );
95
96 # Create a result set that will fetch the artist data
97 # at the same time as it fetches CDs, using only one query.
98 my $millennium_cds_rs = $schema->resultset('CD')->search(
99 { year => 2000 },
100 { prefetch => 'artist' }
101 );
102
103 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
104 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
105
106 # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
107 # create() is the same as new() then insert().
108 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
109 $new_cd->artist($cd->artist);
110 $new_cd->insert; # Auto-increment primary key filled in after INSERT
111 $new_cd->title('Fork');
112
113 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
114
115 # change the year of all the millennium CDs at once
116 $millennium_cds_rs->update({ year => 2002 });
117
118DESCRIPTION
119 This is an SQL to OO mapper with an object API inspired by Class::DBI
120 (with a compatibility layer as a springboard for porting) and a
121 resultset API that allows abstract encapsulation of database operations.
122 It aims to make representing queries in your code as perl-ish as
123 possible while still providing access to as many of the capabilities of
124 the database as possible, including retrieving related records from
125 multiple tables in a single query, JOIN, LEFT JOIN, COUNT, DISTINCT,
126 GROUP BY, ORDER BY and HAVING support.
127
128 DBIx::Class can handle multi-column primary and foreign keys, complex
129 queries and database-level paging, and does its best to only query the
130 database in order to return something you've directly asked for. If a
131 resultset is used as an iterator it only fetches rows off the statement
132 handle as requested in order to minimise memory usage. It has
133 auto-increment support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server
134 and DB2 and is known to be used in production on at least the first
135 four, and is fork- and thread-safe out of the box (although your DBD may
136 not be).
137
138 This project is still under rapid development, so large new features may
139 be marked EXPERIMENTAL - such APIs are still usable but may have edge
140 bugs. Failing test cases are *always* welcome and point releases are put
141 out rapidly as bugs are found and fixed.
142
143 We do our best to maintain full backwards compatibility for published
144 APIs, since DBIx::Class is used in production in many organisations, and
145 even backwards incompatible changes to non-published APIs will be fixed
146 if they're reported and doing so doesn't cost the codebase anything.
147
148 The test suite is quite substantial, and several developer releases are
149 generally made to CPAN before the branch for the next release is merged
150 back to trunk for a major release.
151
152WHERE TO GO NEXT
153 DBIx::Class::Manual::DocMap lists each task you might want help on, and
154 the modules where you will find documentation.
155
156AUTHOR
157 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
158
159 (I mostly consider myself "project founder" these days but the AUTHOR
160 heading is traditional :)
161
162CONTRIBUTORS
163 abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
164
165 aherzog: Adam Herzog <adam@herzogdesigns.com>
166
167 andyg: Andy Grundman <andy@hybridized.org>
168
169 ank: Andres Kievsky
170
171 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
172
173 ash: Ash Berlin <ash@cpan.org>
174
175 bert: Norbert Csongradi <bert@cpan.org>
176
177 blblack: Brandon L. Black <blblack@gmail.com>
178
179 bluefeet: Aran Deltac <bluefeet@cpan.org>
180
181 boghead: Bryan Beeley <cpan@beeley.org>
182
183 bricas: Brian Cassidy <bricas@cpan.org>
184
185 brunov: Bruno Vecchi <vecchi.b@gmail.com>
186
187 caelum: Rafael Kitover <rkitover@cpan.org>
188
189 castaway: Jess Robinson
190
191 claco: Christopher H. Laco
192
193 clkao: CL Kao
194
195 da5id: David Jack Olrik <djo@cpan.org>
196
197 debolaz: Anders Nor Berle <berle@cpan.org>
198
199 dew: Dan Thomas <dan@godders.org>
200
201 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
202
203 dnm: Justin Wheeler <jwheeler@datademons.com>
204
205 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
206
207 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
208
209 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
210
211 goraxe: Gordon Irving <goraxe@cpan.org>
212
213 gphat: Cory G Watson <gphat@cpan.org>
214
215 groditi: Guillermo Roditi <groditi@cpan.org>
216
217 ilmari: Dagfinn Ilmari Manns�ker <ilmari@ilmari.org>
218
219 jasonmay: Jason May <jason.a.may@gmail.com>
220
221 jesper: Jesper Krogh
222
223 jgoulah: John Goulah <jgoulah@cpan.org>
224
225 jguenther: Justin Guenther <jguenther@cpan.org>
226
227 jhannah: Jay Hannah <jay@jays.net>
228
229 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
230
231 jon: Jon Schutz <jjschutz@cpan.org>
232
233 jshirley: J. Shirley <jshirley@gmail.com>
234
235 konobi: Scott McWhirter
236
237 lukes: Luke Saunders <luke.saunders@gmail.com>
238
239 marcus: Marcus Ramberg <mramberg@cpan.org>
240
241 mattlaw: Matt Lawrence
242
243 michaelr: Michael Reddick <michael.reddick@gmail.com>
244
245 ned: Neil de Carteret
246
247 nigel: Nigel Metheringham <nigelm@cpan.org>
248
249 ningu: David Kamholz <dkamholz@cpan.org>
250
251 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
252
253 norbi: Norbert Buchmuller <norbi@nix.hu>
254
255 nuba: Nuba Princigalli <nuba@cpan.org>
256
257 Numa: Dan Sully <daniel@cpan.org>
258
259 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
260
261 oyse: �ystein Torget <oystein.torget@dnv.com>
262
263 paulm: Paul Makepeace
264
265 penguin: K J Cheetham
266
267 perigrin: Chris Prather <chris@prather.org>
268
269 peter: Peter Collingbourne <peter@pcc.me.uk>
270
271 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
272
273 plu: Johannes Plunien <plu@cpan.org>
274
275 quicksilver: Jules Bean
276
277 rafl: Florian Ragwitz <rafl@debian.org>
278
279 rbuels: Robert Buels <rmb32@cornell.edu>
280
281 rdj: Ryan D Johnson <ryan@innerfence.com>
282
283 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
284
285 rjbs: Ricardo Signes <rjbs@cpan.org>
286
287 robkinyon: Rob Kinyon <rkinyon@cpan.org>
288
289 Roman: Roman Filippov <romanf@cpan.org>
290
291 sc_: Just Another Perl Hacker
292
293 scotty: Scotty Allen <scotty@scottyallen.com>
294
295 semifor: Marc Mims <marc@questright.com>
296
297 solomon: Jared Johnson <jaredj@nmgi.com>
298
299 spb: Stephen Bennett <stephen@freenode.net>
300
301 sszabo: Stephan Szabo <sszabo@bigpanda.com>
302
303 teejay : Aaron Trevena <teejay@cpan.org>
304
305 Todd Lipcon
306
307 Tom Hukins
308
309 triode: Pete Gamache <gamache@cpan.org>
310
311 typester: Daisuke Murase <typester@cpan.org>
312
313 victori: Victor Igumnov <victori@cpan.org>
314
315 wdh: Will Hawes
316
317 willert: Sebastian Willert <willert@cpan.org>
318
319 wreis: Wallace Reis <wreis@cpan.org>
320
321 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
322
323COPYRIGHT
324 Copyright (c) 2005 - 2010 the DBIx::Class "AUTHOR" and "CONTRIBUTORS" as
325 listed above.
326
327LICENSE
328 This library is free software and may be distributed under the same
329 terms as perl itself.
330
331