Report correct mismatching inode in the deletion guard on fixed perls
[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.08250';
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 andrewalker: Andre Walker <andre@andrewalker.net>
304
305 andyg: Andy Grundman <andy@hybridized.org>
306
307 ank: Andres Kievsky
308
309 arc: Aaron Crane <arc@cpan.org>
310
311 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
312
313 ash: Ash Berlin <ash@cpan.org>
314
315 bert: Norbert Csongrádi <bert@cpan.org>
316
317 blblack: Brandon L. Black <blblack@gmail.com>
318
319 bluefeet: Aran Deltac <bluefeet@cpan.org>
320
321 bphillips: Brian Phillips <bphillips@cpan.org>
322
323 boghead: Bryan Beeley <cpan@beeley.org>
324
325 brd: Brad Davis <brd@FreeBSD.org>
326
327 bricas: Brian Cassidy <bricas@cpan.org>
328
329 brunov: Bruno Vecchi <vecchi.b@gmail.com>
330
331 caelum: Rafael Kitover <rkitover@cpan.org>
332
333 caldrin: Maik Hentsche <maik.hentsche@amd.com>
334
335 castaway: Jess Robinson
336
337 claco: Christopher H. Laco
338
339 clkao: CL Kao
340
341 da5id: David Jack Olrik <djo@cpan.org>
342
343 dariusj: Darius Jokilehto <dariusjokilehto@yahoo.co.uk>
344
345 davewood: David Schmidt <davewood@gmx.at>
346
347 daxim: Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim@cpan.org>
348
349 debolaz: Anders Nor Berle <berle@cpan.org>
350
351 dew: Dan Thomas <dan@godders.org>
352
353 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
354
355 dnm: Justin Wheeler <jwheeler@datademons.com>
356
357 dpetrov: Dimitar Petrov <mitakaa@gmail.com>
358
359 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
360
361 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
362
363 edenc: Eden Cardim <edencardim@gmail.com>
364
365 ether: Karen Etheridge <ether@cpan.org>
366
367 felliott: Fitz Elliott <fitz.elliott@gmail.com>
368
369 freetime: Bill Moseley <moseley@hank.org>
370
371 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
372
373 goraxe: Gordon Irving <goraxe@cpan.org>
374
375 gphat: Cory G Watson <gphat@cpan.org>
376
377 Grant Street Group L<http://www.grantstreet.com/>
378
379 groditi: Guillermo Roditi <groditi@cpan.org>
380
381 Haarg: Graham Knop <haarg@haarg.org>
382
383 hobbs: Andrew Rodland <arodland@cpan.org>
384
385 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
386
387 initself: Mike Baas <mike@initselftech.com>
388
389 ironcamel: Naveed Massjouni <naveedm9@gmail.com>
390
391 jawnsy: Jonathan Yu <jawnsy@cpan.org>
392
393 jasonmay: Jason May <jason.a.may@gmail.com>
394
395 jesper: Jesper Krogh
396
397 jgoulah: John Goulah <jgoulah@cpan.org>
398
399 jguenther: Justin Guenther <jguenther@cpan.org>
400
401 jhannah: Jay Hannah <jay@jays.net>
402
403 jmac: Jason McIntosh <jmac@appleseed-sc.com>
404
405 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
406
407 jon: Jon Schutz <jjschutz@cpan.org>
408
409 jshirley: J. Shirley <jshirley@gmail.com>
410
411 kaare: Kaare Rasmussen
412
413 konobi: Scott McWhirter
414
415 littlesavage: Alexey Illarionov <littlesavage@orionet.ru>
416
417 lukes: Luke Saunders <luke.saunders@gmail.com>
418
419 marcus: Marcus Ramberg <mramberg@cpan.org>
420
421 mattlaw: Matt Lawrence
422
423 mattp: Matt Phillips <mattp@cpan.org>
424
425 michaelr: Michael Reddick <michael.reddick@gmail.com>
426
427 milki: Jonathan Chu <milki@rescomp.berkeley.edu>
428
429 mithaldu: Christian Walde <walde.christian@gmail.com>
430
431 mjemmeson: Michael Jemmeson <michael.jemmeson@gmail.com>
432
433 mstratman: Mark A. Stratman <stratman@gmail.com>
434
435 ned: Neil de Carteret
436
437 nigel: Nigel Metheringham <nigelm@cpan.org>
438
439 ningu: David Kamholz <dkamholz@cpan.org>
440
441 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
442
443 norbi: Norbert Buchmuller <norbi@nix.hu>
444
445 nuba: Nuba Princigalli <nuba@cpan.org>
446
447 Numa: Dan Sully <daniel@cpan.org>
448
449 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
450
451 oyse: E<Oslash>ystein Torget <oystein.torget@dnv.com>
452
453 paulm: Paul Makepeace
454
455 penguin: K J Cheetham
456
457 perigrin: Chris Prather <chris@prather.org>
458
459 peter: Peter Collingbourne <peter@pcc.me.uk>
460
461 Peter Siklósi <einon@einon.hu>
462
463 Peter Valdemar ME<oslash>rch <peter@morch.com>
464
465 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
466
467 plu: Johannes Plunien <plu@cpan.org>
468
469 Possum: Daniel LeWarne <possum@cpan.org>
470
471 quicksilver: Jules Bean
472
473 rafl: Florian Ragwitz <rafl@debian.org>
474
475 rainboxx: Matthias Dietrich <perl@rb.ly>
476
477 rbo: Robert Bohne <rbo@cpan.org>
478
479 rbuels: Robert Buels <rmb32@cornell.edu>
480
481 rdj: Ryan D Johnson <ryan@innerfence.com>
482
483 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
484
485 rjbs: Ricardo Signes <rjbs@cpan.org>
486
487 robkinyon: Rob Kinyon <rkinyon@cpan.org>
488
489 Robert Olson <bob@rdolson.org>
490
491 moltar: Roman Filippov <romanf@cpan.org>
492
493 Sadrak: Felix Antonius Wilhelm Ostmann <sadrak@cpan.org>
494
495 sc_: Just Another Perl Hacker
496
497 scotty: Scotty Allen <scotty@scottyallen.com>
498
499 semifor: Marc Mims <marc@questright.com>
500
501 SineSwiper: Brendan Byrd <bbyrd@cpan.org>
502
503 solomon: Jared Johnson <jaredj@nmgi.com>
504
505 spb: Stephen Bennett <stephen@freenode.net>
506
507 Squeeks <squeek@cpan.org>
508
509 sszabo: Stephan Szabo <sszabo@bigpanda.com>
510
511 talexb: Alex Beamish <talexb@gmail.com>
512
513 tamias: Ronald J Kimball <rjk@tamias.net>
514
515 teejay : Aaron Trevena <teejay@cpan.org>
516
517 Todd Lipcon
518
519 Tom Hukins
520
521 tonvoon: Ton Voon <tonvoon@cpan.org>
522
523 triode: Pete Gamache <gamache@cpan.org>
524
525 typester: Daisuke Murase <typester@cpan.org>
526
527 victori: Victor Igumnov <victori@cpan.org>
528
529 wdh: Will Hawes
530
531 wesm: Wes Malone <wes@mitsi.com>
532
533 willert: Sebastian Willert <willert@cpan.org>
534
535 wreis: Wallace Reis <wreis@cpan.org>
536
537 xenoterracide: Caleb Cushing <xenoterracide@gmail.com>
538
539 yrlnry: Mark Jason Dominus <mjd@plover.com>
540
541 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
542
543 Zefram: Andrew Main <zefram@fysh.org>
544
545 =head1 COPYRIGHT
546
547 Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
548 as listed above.
549
550 =head1 LICENSE
551
552 This library is free software and may be distributed under the same terms
553 as perl itself.