Fix erroneous todoification in sqlite test
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class.pm
1 package DBIx::Class;
2
3 use strict;
4 use warnings;
5
6 our $VERSION;
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
10
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
14 $VERSION = '0.08270';
15
16 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
17
18 use DBIx::Class::_Util;
19 use mro 'c3';
20
21 use DBIx::Class::Optional::Dependencies;
22
23 use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
24 use DBIx::Class::StartupCheck;
25 use DBIx::Class::Exception;
26
27 __PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
28 __PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny|^Class::Accessor::Grouped|^Context::Preserve');
29
30 sub mk_classdata {
31   shift->mk_classaccessor(@_);
32 }
33
34 sub mk_classaccessor {
35   my $self = shift;
36   $self->mk_group_accessors('inherited', $_[0]);
37   $self->set_inherited(@_) if @_ > 1;
38 }
39
40 sub component_base_class { 'DBIx::Class' }
41
42 sub MODIFY_CODE_ATTRIBUTES {
43   my ($class,$code,@attrs) = @_;
44   $class->mk_classdata('__attr_cache' => {})
45     unless $class->can('__attr_cache');
46   $class->__attr_cache->{$code} = [@attrs];
47   return ();
48 }
49
50 sub _attr_cache {
51   my $self = shift;
52   my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
53
54   return {
55     %$cache,
56     %{ $self->maybe::next::method || {} },
57   };
58 }
59
60 1;
61
62 __END__
63
64 =encoding UTF-8
65
66 =head1 NAME
67
68 DBIx::Class - Extensible and flexible object <-> relational mapper.
69
70 =head1 WHERE TO START READING
71
72 See L<DBIx::Class::Manual::DocMap> for an overview of the exhaustive documentation.
73 To get the most out of DBIx::Class with the least confusion it is strongly
74 recommended to read (at the very least) the
75 L<Manuals|DBIx::Class::Manual::DocMap/Manuals> in the order presented there.
76
77 =head1 HOW TO GET HELP
78
79 Due to the complexity of its problem domain, DBIx::Class is a relatively
80 complex framework. After you start using DBIx::Class questions will inevitably
81 arise. If you are stuck with a problem or have doubts about a particular
82 approach do not hesitate to contact the community with your questions. The
83 list below is sorted by "fastest response time":
84
85 =over
86
87 =item * IRC: irc.perl.org#dbix-class
88
89 =for html
90 <a href="https://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
91
92 =item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
93
94 =item * RT Bug Tracker: L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-Class>
95
96 =item * Twitter: L<https://www.twitter.com/dbix_class>
97
98 =item * Web Site: L<http://www.dbix-class.org/>
99
100 =back
101
102 =head1 SYNOPSIS
103
104 For the very impatient: L<DBIx::Class::Manual::QuickStart>
105
106 This code in the next step can be generated automatically from an existing
107 database, see L<dbicdump> from the distribution C<DBIx-Class-Schema-Loader>.
108
109 =head2 Schema classes preparation
110
111 Create a schema class called F<MyApp/Schema.pm>:
112
113   package MyApp::Schema;
114   use base qw/DBIx::Class::Schema/;
115
116   __PACKAGE__->load_namespaces();
117
118   1;
119
120 Create a result class to represent artists, who have many CDs, in
121 F<MyApp/Schema/Result/Artist.pm>:
122
123 See L<DBIx::Class::ResultSource> for docs on defining result classes.
124
125   package MyApp::Schema::Result::Artist;
126   use base qw/DBIx::Class::Core/;
127
128   __PACKAGE__->table('artist');
129   __PACKAGE__->add_columns(qw/ artistid name /);
130   __PACKAGE__->set_primary_key('artistid');
131   __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');
132
133   1;
134
135 A result class to represent a CD, which belongs to an artist, in
136 F<MyApp/Schema/Result/CD.pm>:
137
138   package MyApp::Schema::Result::CD;
139   use base qw/DBIx::Class::Core/;
140
141   __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
142   __PACKAGE__->table('cd');
143   __PACKAGE__->add_columns(qw/ cdid artistid title year /);
144   __PACKAGE__->set_primary_key('cdid');
145   __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
146
147   1;
148
149 =head2 API usage
150
151 Then you can use these classes in your application's code:
152
153   # Connect to your database.
154   use MyApp::Schema;
155   my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
156
157   # Query for all artists and put them in an array,
158   # or retrieve them as a result set object.
159   # $schema->resultset returns a DBIx::Class::ResultSet
160   my @all_artists = $schema->resultset('Artist')->all;
161   my $all_artists_rs = $schema->resultset('Artist');
162
163   # Output all artists names
164   # $artist here is a DBIx::Class::Row, which has accessors
165   # for all its columns. Rows are also subclasses of your Result class.
166   foreach $artist (@all_artists) {
167     print $artist->name, "\n";
168   }
169
170   # Create a result set to search for artists.
171   # This does not query the DB.
172   my $johns_rs = $schema->resultset('Artist')->search(
173     # Build your WHERE using an SQL::Abstract structure:
174     { name => { like => 'John%' } }
175   );
176
177   # Execute a joined query to get the cds.
178   my @all_john_cds = $johns_rs->search_related('cds')->all;
179
180   # Fetch the next available row.
181   my $first_john = $johns_rs->next;
182
183   # Specify ORDER BY on the query.
184   my $first_john_cds_by_title_rs = $first_john->cds(
185     undef,
186     { order_by => 'title' }
187   );
188
189   # Create a result set that will fetch the artist data
190   # at the same time as it fetches CDs, using only one query.
191   my $millennium_cds_rs = $schema->resultset('CD')->search(
192     { year => 2000 },
193     { prefetch => 'artist' }
194   );
195
196   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
197   my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
198
199   # new() makes a Result object but doesnt insert it into the DB.
200   # create() is the same as new() then insert().
201   my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
202   $new_cd->artist($cd->artist);
203   $new_cd->insert; # Auto-increment primary key filled in after INSERT
204   $new_cd->title('Fork');
205
206   $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
207
208   # change the year of all the millennium CDs at once
209   $millennium_cds_rs->update({ year => 2002 });
210
211 =head1 DESCRIPTION
212
213 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
214 (with a compatibility layer as a springboard for porting) and a resultset API
215 that allows abstract encapsulation of database operations. It aims to make
216 representing queries in your code as perl-ish as possible while still
217 providing access to as many of the capabilities of the database as possible,
218 including retrieving related records from multiple tables in a single query,
219 C<JOIN>, C<LEFT JOIN>, C<COUNT>, C<DISTINCT>, C<GROUP BY>, C<ORDER BY> and
220 C<HAVING> support.
221
222 DBIx::Class can handle multi-column primary and foreign keys, complex
223 queries and database-level paging, and does its best to only query the
224 database in order to return something you've directly asked for. If a
225 resultset is used as an iterator it only fetches rows off the statement
226 handle as requested in order to minimise memory usage. It has auto-increment
227 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
228 known to be used in production on at least the first four, and is fork-
229 and thread-safe out of the box (although
230 L<your DBD may not be|DBI/Threads and Thread Safety>).
231
232 This project is still under rapid development, so large new features may be
233 marked B<experimental> - such APIs are still usable but may have edge bugs.
234 Failing test cases are I<always> welcome and point releases are put out rapidly
235 as bugs are found and fixed.
236
237 We do our best to maintain full backwards compatibility for published
238 APIs, since DBIx::Class is used in production in many organisations,
239 and even backwards incompatible changes to non-published APIs will be fixed
240 if they're reported and doing so doesn't cost the codebase anything.
241
242 The test suite is quite substantial, and several developer releases
243 are generally made to CPAN before the branch for the next release is
244 merged back to trunk for a major release.
245
246 =head1 HOW TO CONTRIBUTE
247
248 Contributions are always welcome, in all usable forms (we especially
249 welcome documentation improvements). The delivery methods include git-
250 or unified-diff formatted patches, GitHub pull requests, or plain bug
251 reports either via RT or the Mailing list. Contributors are generally
252 granted full access to the official repository after their first patch
253 passes successful review.
254
255 =for comment
256 FIXME: Getty, frew and jnap need to get off their asses and finish the contrib section so we can link it here ;)
257
258 This project is maintained in a git repository. The code and related tools are
259 accessible at the following locations:
260
261 =over
262
263 =item * Official repo: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
264
265 =item * Official gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
266
267 =item * GitHub mirror: L<https://github.com/dbsrgits/DBIx-Class>
268
269 =item * Authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/DBIx-Class.git>
270
271 =item * Travis-CI log: L<https://travis-ci.org/dbsrgits/dbix-class/builds>
272
273 =for html
274 &#x21AA; Stable branch CI status: <img src="https://secure.travis-ci.org/dbsrgits/dbix-class.png?branch=master"></img>
275
276 =back
277
278 =head1 AUTHOR
279
280 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
281
282 (I mostly consider myself "project founder" these days but the AUTHOR heading
283 is traditional :)
284
285 =head1 CONTRIBUTORS
286
287 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
288
289 acca: Alexander Kuznetsov <acca@cpan.org>
290
291 aherzog: Adam Herzog <adam@herzogdesigns.com>
292
293 Alexander Keusch <cpan@keusch.at>
294
295 alexrj: Alessandro Ranellucci <aar@cpan.org>
296
297 alnewkirk: Al Newkirk <we@ana.im>
298
299 amiri: Amiri Barksdale <amiri@metalabel.com>
300
301 amoore: Andrew Moore <amoore@cpan.org>
302
303 Andrew Mehta <Andrew@unitedgames.co.uk>
304
305 andrewalker: Andre Walker <andre@andrewalker.net>
306
307 andyg: Andy Grundman <andy@hybridized.org>
308
309 ank: Andres Kievsky
310
311 arc: Aaron Crane <arc@cpan.org>
312
313 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
314
315 ash: Ash Berlin <ash@cpan.org>
316
317 bert: Norbert Csongrádi <bert@cpan.org>
318
319 bfwg: Colin Newell <colin.newell@gmail.com>
320
321 blblack: Brandon L. Black <blblack@gmail.com>
322
323 bluefeet: Aran Deltac <bluefeet@cpan.org>
324
325 bphillips: Brian Phillips <bphillips@cpan.org>
326
327 boghead: Bryan Beeley <cpan@beeley.org>
328
329 brd: Brad Davis <brd@FreeBSD.org>
330
331 bricas: Brian Cassidy <bricas@cpan.org>
332
333 brunov: Bruno Vecchi <vecchi.b@gmail.com>
334
335 caelum: Rafael Kitover <rkitover@cpan.org>
336
337 caldrin: Maik Hentsche <maik.hentsche@amd.com>
338
339 castaway: Jess Robinson
340
341 claco: Christopher H. Laco
342
343 clkao: CL Kao
344
345 Ctrl-o L<http://ctrlo.com/>
346
347 da5id: David Jack Olrik <djo@cpan.org>
348
349 dariusj: Darius Jokilehto <dariusjokilehto@yahoo.co.uk>
350
351 davewood: David Schmidt <davewood@gmx.at>
352
353 daxim: Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim@cpan.org>
354
355 debolaz: Anders Nor Berle <berle@cpan.org>
356
357 dew: Dan Thomas <dan@godders.org>
358
359 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
360
361 dnm: Justin Wheeler <jwheeler@datademons.com>
362
363 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
364
365 duncan_dmg: Duncan Garland <Duncan.Garland@motortrak.com>
366
367 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
368
369 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
370
371 edenc: Eden Cardim <edencardim@gmail.com>
372
373 Eligo L<http://eligo.co.uk/>
374
375 ether: Karen Etheridge <ether@cpan.org>
376
377 felliott: Fitz Elliott <fitz.elliott@gmail.com>
378
379 freetime: Bill Moseley <moseley@hank.org>
380
381 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
382
383 goraxe: Gordon Irving <goraxe@cpan.org>
384
385 gphat: Cory G Watson <gphat@cpan.org>
386
387 Grant Street Group L<http://www.grantstreet.com/>
388
389 groditi: Guillermo Roditi <groditi@cpan.org>
390
391 Haarg: Graham Knop <haarg@haarg.org>
392
393 hobbs: Andrew Rodland <arodland@cpan.org>
394
395 idn: Ian Norton <i.norton@shadowcat.co.uk>
396
397 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
398
399 initself: Mike Baas <mike@initselftech.com>
400
401 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
402
403 jawnsy: Jonathan Yu <jawnsy@cpan.org>
404
405 jasonmay: Jason May <jason.a.may@gmail.com>
406
407 jesper: Jesper Krogh
408
409 jgoulah: John Goulah <jgoulah@cpan.org>
410
411 jguenther: Justin Guenther <jguenther@cpan.org>
412
413 jhannah: Jay Hannah <jay@jays.net>
414
415 jmac: Jason McIntosh <jmac@appleseed-sc.com>
416
417 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
418
419 jon: Jon Schutz <jjschutz@cpan.org>
420
421 jshirley: J. Shirley <jshirley@gmail.com>
422
423 kaare: Kaare Rasmussen
424
425 konobi: Scott McWhirter
426
427 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
428
429 lukes: Luke Saunders <luke.saunders@gmail.com>
430
431 marcus: Marcus Ramberg <mramberg@cpan.org>
432
433 mattlaw: Matt Lawrence
434
435 mattp: Matt Phillips <mattp@cpan.org>
436
437 mdk: Mark Keating <m.keating@shadowcat.co.uk>
438
439 mna: Maya
440
441 michaelr: Michael Reddick <michael.reddick@gmail.com>
442
443 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
444
445 minty: Murray Walker <perl@minty.org>
446
447 mithaldu: Christian Walde <walde.christian@gmail.com>
448
449 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
450
451 mstratman: Mark A. Stratman <stratman@gmail.com>
452
453 ned: Neil de Carteret
454
455 nigel: Nigel Metheringham <nigelm@cpan.org>
456
457 ningu: David Kamholz <dkamholz@cpan.org>
458
459 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
460
461 norbi: Norbert Buchmuller <norbi@nix.hu>
462
463 nuba: Nuba Princigalli <nuba@cpan.org>
464
465 Numa: Dan Sully <daniel@cpan.org>
466
467 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
468
469 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
470
471 paulm: Paul Makepeace
472
473 penguin: K J Cheetham
474
475 perigrin: Chris Prather <chris@prather.org>
476
477 peter: Peter Collingbourne <peter@pcc.me.uk>
478
479 Peter Siklósi <einon@einon.hu>
480
481 Peter Valdemar ME<oslash>rch <peter@morch.com>
482
483 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
484
485 plu: Johannes Plunien <plu@cpan.org>
486
487 pplu: Jose Luis Martinez <jlmartinez@capside.com>
488
489 Possum: Daniel LeWarne <possum@cpan.org>
490
491 quicksilver: Jules Bean
492
493 rafl: Florian Ragwitz <rafl@debian.org>
494
495 rainboxx: Matthias Dietrich <perl@rb.ly>
496
497 rbo: Robert Bohne <rbo@cpan.org>
498
499 rbuels: Robert Buels <rmb32@cornell.edu>
500
501 rdj: Ryan D Johnson <ryan@innerfence.com>
502
503 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
504
505 rjbs: Ricardo Signes <rjbs@cpan.org>
506
507 robkinyon: Rob Kinyon <rkinyon@cpan.org>
508
509 Robert Olson <bob@rdolson.org>
510
511 moltar: Roman Filippov <romanf@cpan.org>
512
513 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
514
515 sc_: Just Another Perl Hacker
516
517 scotty: Scotty Allen <scotty@scottyallen.com>
518
519 semifor: Marc Mims <marc@questright.com>
520
521 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
522
523 solomon: Jared Johnson <jaredj@nmgi.com>
524
525 spb: Stephen Bennett <stephen@freenode.net>
526
527 Squeeks <squeek@cpan.org>
528
529 sszabo: Stephan Szabo <sszabo@bigpanda.com>
530
531 Stephen Peters <steve@stephenpeters.me>
532
533 talexb: Alex Beamish <talexb@gmail.com>
534
535 tamias: Ronald J Kimball <rjk@tamias.net>
536
537 TBSliver: Tom Bloor <t.bloor@shadowcat.co.uk>
538
539 teejay : Aaron Trevena <teejay@cpan.org>
540
541 theorbtwo: James Mastros <james@mastros.biz>
542
543 Todd Lipcon
544
545 Tom Hukins
546
547 tonvoon: Ton Voon <tonvoon@cpan.org>
548
549 triode: Pete Gamache <gamache@cpan.org>
550
551 typester: Daisuke Murase <typester@cpan.org>
552
553 victori: Victor Igumnov <victori@cpan.org>
554
555 wdh: Will Hawes
556
557 wesm: Wes Malone <wes@mitsi.com>
558
559 willert: Sebastian Willert <willert@cpan.org>
560
561 wreis: Wallace Reis <wreis@cpan.org>
562
563 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
564
565 uree: Oriol Soriano <oriol.soriano@capside.com>
566
567 yrlnry: Mark Jason Dominus <mjd@plover.com>
568
569 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
570
571 Zefram: Andrew Main <zefram@fysh.org>
572
573 =head1 COPYRIGHT
574
575 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
576 as listed above.
577
578 =head1 LICENSE
579
580 This library is free software and may be distributed under the same terms
581 as perl itself.