1DBIx::Class is Copyright (c) 2005-2020 by mst, castaway, ribasushi, and others.
2See AUTHORS and LICENSE included with this distribution. All rights reserved.
3
4NAME
5 DBIx::Class - Extensible and flexible object <-> relational mapper.
6
7WHERE TO START READING
8 See DBIx::Class::Manual::DocMap for an overview of the exhaustive
9 documentation. To get the most out of DBIx::Class with the least
10 confusion it is strongly recommended to read (at the very least) the
11 Manuals in the order presented there.
12
13GETTING HELP/SUPPORT
14 Due to the sheer size of its problem domain, DBIx::Class is a relatively
15 complex framework. After you start using DBIx::Class questions will
16 inevitably arise. If you are stuck with a problem or have doubts about a
17 particular approach do not hesitate to contact us via any of the
18 following options (the list is sorted by "fastest response time"):
19
20 * RT Bug Tracker:
21 <https://rt.cpan.org/Public/Dist/Display.html?Name=DBIx-Class>
22
23 * Email: <mailto:bug-DBIx-Class@rt.cpan.org>
24
25 * Twitter:
26 <https://twitter.com/intent/tweet?text=%40ribasushi%20%23DBIC>
27
28SYNOPSIS
29 For the very impatient: DBIx::Class::Manual::QuickStart
30
31 This code in the next step can be generated automatically from an
32 existing database, see dbicdump from the distribution
33 "DBIx-Class-Schema-Loader".
34
35 Schema classes preparation
36 Create a schema class called MyApp/Schema.pm:
37
38 package MyApp::Schema;
39 use base qw/DBIx::Class::Schema/;
40
41 __PACKAGE__->load_namespaces();
42
43 1;
44
45 Create a result class to represent artists, who have many CDs, in
46 MyApp/Schema/Result/Artist.pm:
47
48 See DBIx::Class::ResultSource for docs on defining result classes.
49
50 package MyApp::Schema::Result::Artist;
51 use base qw/DBIx::Class::Core/;
52
53 __PACKAGE__->table('artist');
54 __PACKAGE__->add_columns(qw/ artistid name /);
55 __PACKAGE__->set_primary_key('artistid');
56 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');
57
58 1;
59
60 A result class to represent a CD, which belongs to an artist, in
61 MyApp/Schema/Result/CD.pm:
62
63 package MyApp::Schema::Result::CD;
64 use base qw/DBIx::Class::Core/;
65
66 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
67 __PACKAGE__->table('cd');
68 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
69 __PACKAGE__->set_primary_key('cdid');
70 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
71
72 1;
73
74 API usage
75 Then you can use these classes in your application's code:
76
77 # Connect to your database.
78 use MyApp::Schema;
79 my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
80
81 # Query for all artists and put them in an array,
82 # or retrieve them as a result set object.
83 # $schema->resultset returns a DBIx::Class::ResultSet
84 my @all_artists = $schema->resultset('Artist')->all;
85 my $all_artists_rs = $schema->resultset('Artist');
86
87 # Output all artists names
88 # $artist here is a DBIx::Class::Row, which has accessors
89 # for all its columns. Rows are also subclasses of your Result class.
90 foreach $artist (@all_artists) {
91 print $artist->name, "\n";
92 }
93
94 # Create a result set to search for artists.
95 # This does not query the DB.
96 my $johns_rs = $schema->resultset('Artist')->search(
97 # Build your WHERE using an SQL::Abstract::Classic-compatible structure:
98 { name => { like => 'John%' } }
99 );
100
101 # Execute a joined query to get the cds.
102 my @all_john_cds = $johns_rs->search_related('cds')->all;
103
104 # Fetch the next available row.
105 my $first_john = $johns_rs->next;
106
107 # Specify ORDER BY on the query.
108 my $first_john_cds_by_title_rs = $first_john->cds(
109 undef,
110 { order_by => 'title' }
111 );
112
113 # Create a result set that will fetch the artist data
114 # at the same time as it fetches CDs, using only one query.
115 my $millennium_cds_rs = $schema->resultset('CD')->search(
116 { year => 2000 },
117 { prefetch => 'artist' }
118 );
119
120 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
121 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
122
123 # new() makes a Result object but doesn't insert it into the DB.
124 # create() is the same as new() then insert().
125 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
126 $new_cd->artist($cd->artist);
127 $new_cd->insert; # Auto-increment primary key filled in after INSERT
128 $new_cd->title('Fork');
129
130 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
131
132 # change the year of all the millennium CDs at once
133 $millennium_cds_rs->update({ year => 2002 });
134
135DESCRIPTION
136 This is an SQL to OO mapper with an object API inspired by Class::DBI
137 (with a compatibility layer as a springboard for porting) and a
138 resultset API that allows abstract encapsulation of database operations.
139 It aims to make representing queries in your code as perl-ish as
140 possible while still providing access to as many of the capabilities of
141 the database as possible, including retrieving related records from
142 multiple tables in a single query, "JOIN", "LEFT JOIN", "COUNT",
143 "DISTINCT", "GROUP BY", "ORDER BY" and "HAVING" support.
144
145 DBIx::Class can handle multi-column primary and foreign keys, complex
146 queries and database-level paging, and does its best to only query the
147 database in order to return something you've directly asked for. If a
148 resultset is used as an iterator it only fetches rows off the statement
149 handle as requested in order to minimise memory usage. It has
150 auto-increment support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server
151 and DB2 and is known to be used in production on at least the first
152 four, and is fork- and thread-safe out of the box (although your DBD may
153 not be).
154
155 This project is still under rapid development, so large new features may
156 be marked experimental - such APIs are still usable but may have edge
157 bugs. Failing test cases are *always* welcome and point releases are put
158 out rapidly as bugs are found and fixed.
159
160 We do our best to maintain full backwards compatibility for published
161 APIs, since DBIx::Class is used in production in many organisations, and
162 even backwards incompatible changes to non-published APIs will be fixed
163 if they're reported and doing so doesn't cost the codebase anything.
164
165 The test suite is quite substantial, and several developer releases are
166 generally made to CPAN before the branch for the next release is merged
167 back to trunk for a major release.
168
169HOW TO CONTRIBUTE
170 Contributions are always welcome, in all usable forms (we especially
171 welcome documentation improvements). The delivery methods include git-
172 or unified-diff formatted patches, GitHub pull requests, or plain bug
173 reports either via RT or the Mailing list. Do not hesitate to get in
174 touch with any further questions you may have.
175
176 This project is maintained in a git repository. The code and related
177 tools are accessible at the following locations:
178
179 * Current git repository: <https://github.com/Perl5/DBIx-Class>
180
181 * Travis-CI log:
182 <https://travis-ci.com/github/Perl5/DBIx-Class/branches>
183
184AUTHORS
185 Even though a large portion of the source *appears* to be written by
186 just a handful of people, this library continues to remain a
187 collaborative effort - perhaps one of the most successful such projects
188 on CPAN <http://cpan.org>. It is important to remember that ideas do not
189 always result in a direct code contribution, but deserve acknowledgement
190 just the same. Time and time again the seemingly most insignificant
191 questions and suggestions have been shown to catalyze monumental
192 improvements in consistency, accuracy and performance.
193
194 List of the awesome contributors who made DBIC v0.082842 possible
195
196 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
197
198 acca: Alexander Kuznetsov <acca@cpan.org>
199
200 acme: Leon Brocard <acme@astray.com>
201
202 aherzog: Adam Herzog <adam@herzogdesigns.com>
203
204 Alexander Keusch <cpan@keusch.at>
205
206 alexrj: Alessandro Ranellucci <aar@cpan.org>
207
208 alnewkirk: Al Newkirk <github@alnewkirk.com>
209
210 Altreus: Alastair McGowan-Douglas <alastair.mcgowan@opusvl.com>
211
212 amiri: Amiri Barksdale <amiribarksdale@gmail.com>
213
214 amoore: Andrew Moore <amoore@cpan.org>
215
216 Andrew Mehta <Andrew@unitedgames.co.uk>
217
218 andrewalker: Andre Walker <andre@andrewalker.net>
219
220 andyg: Andy Grundman <andy@hybridized.org>
221
222 ank: Andres Kievsky <ank@ank.com.ar>
223
224 arc: Aaron Crane <arc@cpan.org>
225
226 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
227
228 ash: Ash Berlin <ash@cpan.org>
229
230 bert: Norbert Csongrádi <bert@cpan.org>
231
232 bfwg: Colin Newell <colin.newell@gmail.com>
233
234 blblack: Brandon L. Black <blblack@gmail.com>
235
236 bluefeet: Aran Deltac <bluefeet@cpan.org>
237
238 boghead: Bryan Beeley <cpan@beeley.org>
239
240 bphillips: Brian Phillips <bphillips@cpan.org>
241
242 brd: Brad Davis <brd@FreeBSD.org>
243
244 Brian Kirkbride <brian.kirkbride@deeperbydesign.com>
245
246 bricas: Brian Cassidy <bricas@cpan.org>
247
248 brunov: Bruno Vecchi <vecchi.b@gmail.com>
249
250 caelum: Rafael Kitover <rkitover@cpan.org>
251
252 caldrin: Maik Hentsche <maik.hentsche@amd.com>
253
254 castaway: Jess Robinson <castaway@desert-island.me.uk>
255
256 chorny: Alexandr Ciornii <alexchorny@gmail.com>
257
258 cj: C.J. Adams-Collier <cjcollier@cpan.org>
259
260 claco: Christopher H. Laco <claco@cpan.org>
261
262 clkao: CL Kao <clkao@clkao.org>
263
264 Ctrl-O <http://ctrlo.com/>
265
266 da5id: David Jack Olrik <david@olrik.dk>
267
268 dams: Damien Krotkine <dams@cpan.org>
269
270 dandv: Dan Dascalescu <ddascalescu+github@gmail.com>
271
272 dariusj: Darius Jokilehto <dariusjokilehto@yahoo.co.uk>
273
274 davewood: David Schmidt <mail@davidschmidt.at>
275
276 daxim: Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim@cpan.org>
277
278 dduncan: Darren Duncan <darren@darrenduncan.net>
279
280 debolaz: Anders Nor Berle <berle@cpan.org>
281
282 dew: Dan Thomas <dan@godders.org>
283
284 dim0xff: Dmitry Latin <dim0xff@gmail.com>
285
286 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
287
288 dnm: Justin Wheeler <jwheeler@datademons.com>
289
290 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
291
292 Dr^ZigMan: Robert Stone <drzigman@drzigman.com>
293
294 dsteinbrunner: David Steinbrunner <dsteinbrunner@pobox.com>
295
296 duncan_dmg: Duncan Garland <Duncan.Garland@motortrak.com>
297
298 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
299
300 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
301
302 edenc: Eden Cardim <edencardim@gmail.com>
303
304 Eligo <http://eligo.co.uk/>
305
306 ether: Karen Etheridge <ether@cpan.org>
307
308 evdb: Edmund von der Burg <evdb@ecclestoad.co.uk>
309
310 faxm0dem: Fabien Wernli <cpan@faxm0dem.org>
311
312 felliott: Fitz Elliott <fitz.elliott@gmail.com>
313
314 fgabolde: Fabrice Gabolde <fgabolde@weborama.com>
315
316 freetime: Bill Moseley <moseley@hank.org>
317
318 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
319
320 gbjk: Gareth Kirwan <gbjk@thermeon.com>
321
322 geotheve: Georgina Thevenet <geotheve@gmail.com>
323
324 Getty: Torsten Raudssus <torsten@raudss.us>
325
326 goraxe: Gordon Irving <goraxe@cpan.org>
327
328 gphat: Cory G Watson <gphat@cpan.org>
329
330 Grant Street Group <http://www.grantstreet.com/>
331
332 gregoa: Gregor Herrmann <gregoa@debian.org>
333
334 groditi: Guillermo Roditi <groditi@cpan.org>
335
336 gshank: Gerda Shank <gshank@cpan.org>
337
338 guacamole: Fred Steinberg <fred.steinberg@gmail.com>
339
340 Haarg: Graham Knop <haarg@haarg.org>
341
342 hobbs: Andrew Rodland <andrew@cleverdomain.org>
343
344 Ian Wells <ijw@cack.org.uk>
345
346 idn: Ian Norton <i.norton@shadowcat.co.uk>
347
348 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
349
350 ingy: Ingy döt Net <ingy@ingy.net>
351
352 initself: Mike Baas <mike@initselftech.com>
353
354 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
355
356 jasonmay: Jason May <jason.a.may@gmail.com>
357
358 jawnsy: Jonathan Yu <jawnsy@cpan.org>
359
360 jegade: Jens Gassmann <jens.gassmann@atomix.de>
361
362 jeneric: Eric A. Miller <emiller@cpan.org>
363
364 jesper: Jesper Krogh <jesper@krogh.cc>
365
366 Jesse Sheidlower <jester@panix.com>
367
368 jgoulah: John Goulah <jgoulah@cpan.org>
369
370 jguenther: Justin Guenther <jguenther@cpan.org>
371
372 jhannah: Jay Hannah <jay@jays.net>
373
374 jmac: Jason McIntosh <jmac@appleseed-sc.com>
375
376 jmmills: Jason M. Mills <jmmills@cpan.org>
377
378 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
379
380 Joe Carlson <jwcarlson@lbl.gov>
381
382 jon: Jon Schutz <jjschutz@cpan.org>
383
384 Jordan Metzmeier <jmetzmeier@magazines.com>
385
386 jshirley: J. Shirley <jshirley@gmail.com>
387
388 kaare: Kaare Rasmussen
389
390 kd: Kieren Diment <diment@gmail.com>
391
392 kentnl: Kent Fredric <kentnl@cpan.org>
393
394 kkane: Kevin L. Kane <kevin.kane@gmail.com>
395
396 konobi: Scott McWhirter <konobi@cpan.org>
397
398 lejeunerenard: Sean Zellmer <sean@lejeunerenard.com>
399
400 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
401
402 lukes: Luke Saunders <luke.saunders@gmail.com>
403
404 marcus: Marcus Ramberg <mramberg@cpan.org>
405
406 mateu: Mateu X. Hunter <hunter@missoula.org>
407
408 Matt LeBlanc <antirice@gmail.com>
409
410 Matt Sickler <imMute@msk4.com>
411
412 mattlaw: Matt Lawrence
413
414 mattp: Matt Phillips <mattp@cpan.org>
415
416 mdk: Mark Keating <m.keating@shadowcat.co.uk>
417
418 melo: Pedro Melo <melo@simplicidade.org>
419
420 metaperl: Terrence Brannon <metaperl@gmail.com>
421
422 michaelr: Michael Reddick <michael.reddick@gmail.com>
423
424 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
425
426 minty: Murray Walker <perl@minty.org>
427
428 mithaldu: Christian Walde <walde.christian@gmail.com>
429
430 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
431
432 mna: Maya
433
434 mo: Moritz Onken <onken@netcubed.de>
435
436 moltar: Roman Filippov <romanf@cpan.org>
437
438 moritz: Moritz Lenz <moritz@faui2k3.org>
439
440 mrf: Mike Francis <ungrim97@gmail.com>
441
442 mst: Matt S. Trout <mst@shadowcat.co.uk>
443
444 mstratman: Mark A. Stratman <stratman@gmail.com>
445
446 ned: Neil de Carteret <n3dst4@gmail.com>
447
448 nigel: Nigel Metheringham <nigelm@cpan.org>
449
450 ningu: David Kamholz <dkamholz@cpan.org>
451
452 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
453
454 norbi: Norbert Buchmuller <norbi@nix.hu>
455
456 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
457
458 nuba: Nuba Princigalli <nuba@cpan.org>
459
460 Numa: Dan Sully <daniel@cpan.org>
461
462 oalders: Olaf Alders <olaf@wundersolutions.com>
463
464 Olly Betts <olly@survex.com>
465
466 osfameron: Hakim Cassimally <osfameron@cpan.org>
467
468 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
469
470 oyse: Øystein Torget <oystein.torget@dnv.com>
471
472 paulm: Paul Makepeace <paulm+pause@paulm.com>
473
474 penguin: K J Cheetham <jamie@shadowcatsystems.co.uk>
475
476 perigrin: Chris Prather <chris@prather.org>
477
478 Peter Siklósi <einon@einon.hu>
479
480 Peter Valdemar Mørch <peter@morch.com>
481
482 peter: Peter Collingbourne <peter@pcc.me.uk>
483
484 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
485
486 plu: Johannes Plunien <plu@cpan.org>
487
488 pmooney: Paul Mooney <paul.mooney@net-a-porter.com>
489
490 Possum: Daniel LeWarne <possum@cpan.org>
491
492 pplu: Jose Luis Martinez <jlmartinez@capside.com>
493
494 quicksilver: Jules Bean <jules@jellybean.co.uk>
495
496 racke: Stefan Hornburg <racke@linuxia.de>
497
498 rafl: Florian Ragwitz <rafl@debian.org>
499
500 rainboxx: Matthias Dietrich <perl@rb.ly>
501
502 rbo: Robert Bohne <rbo@cpan.org>
503
504 rbuels: Robert Buels <rmb32@cornell.edu>
505
506 rdj: Ryan D Johnson <ryan@innerfence.com>
507
508 Relequestual: Ben Hutton <relequestual@gmail.com>
509
510 renormalist: Steffen Schwigon <schwigon@cpan.org>
511
512 ribasushi: Peter Rabbitson <ribasushi@leporine.io>
513
514 rjbs: Ricardo Signes <rjbs@cpan.org>
515
516 Robert Krimen <rkrimen@cpan.org>
517
518 Robert Olson <bob@rdolson.org>
519
520 robkinyon: Rob Kinyon <rkinyon@cpan.org>
521
522 Roman Ardern-Corris <spam_in@3legs.com>
523
524 ruoso: Daniel Ruoso <daniel@ruoso.com>
525
526 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
527
528 sc_: Just Another Perl Hacker
529
530 schwern: Michael G Schwern <mschwern@cpan.org>
531
532 Scott R. Godin <webdragon.net@gmail.com>
533
534 scotty: Scotty Allen <scotty@scottyallen.com>
535
536 semifor: Marc Mims <marc@questright.com>
537
538 Simon Elliott <cpan@browsing.co.uk>
539
540 SineSwiper: Brendan Byrd <perl@resonatorsoft.org>
541
542 skaufman: Samuel Kaufman <sam@socialflow.com>
543
544 solomon: Jared Johnson <jaredj@nmgi.com>
545
546 spb: Stephen Bennett <stephen@freenode.net>
547
548 Squeeks <squeek@cpan.org>
549
550 srezic: Slaven Rezic <slaven@rezic.de>
551
552 sszabo: Stephan Szabo <sszabo@bigpanda.com>
553
554 Stephen Peters <steve@stephenpeters.me>
555
556 stonecolddevin: Devin Austin <dhoss@cpan.org>
557
558 talexb: Alex Beamish <talexb@gmail.com>
559
560 tamias: Ronald J Kimball <rjk@tamias.net>
561
562 TBSliver: Tom Bloor <t.bloor@shadowcat.co.uk>
563
564 teejay: Aaron Trevena <teejay@cpan.org>
565
566 theorbtwo: James Mastros <james@mastros.biz>
567
568 Thomas Kratz <tomk@cpan.org>
569
570 timbunce: Tim Bunce <tim.bunce@pobox.com>
571
572 tinita: Tina Mueller <cpan2@tinita.de>
573
574 Todd Lipcon
575
576 Tom Hukins <tom@eborcom.com>
577
578 tommy: Tommy Butler <tbutler.cpan.org@internetalias.net>
579
580 tonvoon: Ton Voon <ton.voon@opsview.com>
581
582 triode: Pete Gamache <gamache@cpan.org>
583
584 typester: Daisuke Murase <typester@cpan.org>
585
586 uree: Oriol Soriano <oriol.soriano@capside.com>
587
588 uwe: Uwe Voelker <uwe@uwevoelker.de>
589
590 vanstyn: Henry Van Styn <vanstyn@cpan.org>
591
592 victori: Victor Igumnov <victori@cpan.org>
593
594 wdh: Will Hawes <wdhawes@gmail.com>
595
596 wesm: Wes Malone <wes@mitsi.com>
597
598 willert: Sebastian Willert <willert@cpan.org>
599
600 wintermute: Toby Corkindale <tjc@cpan.org>
601
602 wreis: Wallace Reis <wreis@cpan.org>
603
604 x86-64 <x86mail@gmail.com>
605
606 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
607
608 xmikew: Mike Wisener <xmikew@32ths.com>
609
610 yrlnry: Mark Jason Dominus <mjd@plover.com>
611
612 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
613
614 Zefram: Andrew Main <zefram@fysh.org>
615
616 The canonical source of authors and their details is the AUTHORS file at
617 the root of this distribution (or repository). The canonical source of
618 per-line authorship is the git repository history itself.
619
620COPYRIGHT AND LICENSE
621 Copyright (c) 2005 by mst, castaway, ribasushi, and other DBIx::Class
622 "AUTHORS" as listed above and in AUTHORS.
623
624 This library is free software and may be distributed under the same
625 terms as perl5 itself. See LICENSE for the complete licensing terms.
626
627