Can not return from within a try block
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class.pm
CommitLineData
ea2e61bf 1package DBIx::Class;
2
5d283305 3use strict;
4use warnings;
5
329d7385 6use MRO::Compat;
d38cd95c 7use mro 'c3';
329d7385 8
2527233b 9use DBIx::Class::Optional::Dependencies;
10
5d283305 11use vars qw($VERSION);
d38cd95c 12use base qw/DBIx::Class::Componentised Class::Accessor::Grouped/;
11736b4c 13use DBIx::Class::StartupCheck;
3e110410 14
ade0fe3b 15sub mk_classdata {
77d518d1 16 shift->mk_classaccessor(@_);
17}
18
19sub mk_classaccessor {
20 my $self = shift;
ade0fe3b 21 $self->mk_group_accessors('inherited', $_[0]);
77d518d1 22 $self->set_inherited(@_) if @_ > 1;
3e110410 23}
3c0068c1 24
7411204b 25sub component_base_class { 'DBIx::Class' }
227d4dee 26
95da6f35 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
a3356adb 30$VERSION = '0.08121_01';
748ab0dc 31
033955f9 32$VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
b8777a0d 33
f0750722 34sub MODIFY_CODE_ATTRIBUTES {
b5d2c57f 35 my ($class,$code,@attrs) = @_;
36 $class->mk_classdata('__attr_cache' => {})
37 unless $class->can('__attr_cache');
38 $class->__attr_cache->{$code} = [@attrs];
39 return ();
f0750722 40}
41
da95b45f 42sub _attr_cache {
b5d2c57f 43 my $self = shift;
44 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
9780718f 45
46 return {
47 %$cache,
48 %{ $self->maybe::next::method || {} },
20674fcd 49 };
da95b45f 50}
51
ea2e61bf 521;
34d52be2 53
75d07914 54=head1 NAME
34d52be2 55
7e4b2f59 56DBIx::Class - Extensible and flexible object <-> relational mapper.
34d52be2 57
3b1c2bbd 58=head1 GETTING HELP/SUPPORT
59
60The community can be found via:
61
a06e1181 62=over
3b1c2bbd 63
a06e1181 64=item * IRC: L<irc.perl.org#dbix-class (click for instant chatroom login)
65|http://mibbit.com/chat/#dbix-class@irc.perl.org>
3b1c2bbd 66
a06e1181 67=item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
3b1c2bbd 68
a06e1181 69=item * RT Bug Tracker: L<https://rt.cpan.org/Dist/Display.html?Queue=DBIx-Class>
70
71=item * SVNWeb: L<http://dev.catalyst.perl.org/svnweb/bast/browse/DBIx-Class/0.08>
72
73=item * SVN: L<http://dev.catalyst.perl.org/repos/bast/DBIx-Class/0.08>
74
75=back
3b1c2bbd 76
34d52be2 77=head1 SYNOPSIS
78
bd077b47 79Create a schema class called MyDB/Schema.pm:
34d52be2 80
bd077b47 81 package MyDB::Schema;
a0638a7b 82 use base qw/DBIx::Class::Schema/;
34d52be2 83
f0bb26f3 84 __PACKAGE__->load_namespaces();
daec44b8 85
a0638a7b 86 1;
daec44b8 87
30e1753a 88Create a result class to represent artists, who have many CDs, in
f0bb26f3 89MyDB/Schema/Result/Artist.pm:
daec44b8 90
30e1753a 91See L<DBIx::Class::ResultSource> for docs on defining result classes.
92
f0bb26f3 93 package MyDB::Schema::Result::Artist;
d88ecca6 94 use base qw/DBIx::Class::Core/;
daec44b8 95
a0638a7b 96 __PACKAGE__->table('artist');
97 __PACKAGE__->add_columns(qw/ artistid name /);
98 __PACKAGE__->set_primary_key('artistid');
f0bb26f3 99 __PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD');
daec44b8 100
a0638a7b 101 1;
daec44b8 102
30e1753a 103A result class to represent a CD, which belongs to an artist, in
f0bb26f3 104MyDB/Schema/Result/CD.pm:
39fe0e65 105
f0bb26f3 106 package MyDB::Schema::Result::CD;
d88ecca6 107 use base qw/DBIx::Class::Core/;
39fe0e65 108
d88ecca6 109 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
a0638a7b 110 __PACKAGE__->table('cd');
bd077b47 111 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
a0638a7b 112 __PACKAGE__->set_primary_key('cdid');
bd077b47 113 __PACKAGE__->belongs_to(artist => 'MyDB::Schema::Artist', 'artistid');
39fe0e65 114
a0638a7b 115 1;
39fe0e65 116
a0638a7b 117Then you can use these classes in your application's code:
39fe0e65 118
a0638a7b 119 # Connect to your database.
bd077b47 120 use MyDB::Schema;
121 my $schema = MyDB::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
a0638a7b 122
123 # Query for all artists and put them in an array,
124 # or retrieve them as a result set object.
30e1753a 125 # $schema->resultset returns a DBIx::Class::ResultSet
2053ab2a 126 my @all_artists = $schema->resultset('Artist')->all;
127 my $all_artists_rs = $schema->resultset('Artist');
126042ee 128
30e1753a 129 # Output all artists names
4e8ffded 130 # $artist here is a DBIx::Class::Row, which has accessors
16ccb4fe 131 # for all its columns. Rows are also subclasses of your Result class.
85067746 132 foreach $artist (@all_artists) {
30e1753a 133 print $artist->name, "\n";
134 }
135
a0638a7b 136 # Create a result set to search for artists.
86beca1d 137 # This does not query the DB.
2053ab2a 138 my $johns_rs = $schema->resultset('Artist')->search(
6576ef54 139 # Build your WHERE using an SQL::Abstract structure:
2053ab2a 140 { name => { like => 'John%' } }
a0638a7b 141 );
39fe0e65 142
2053ab2a 143 # Execute a joined query to get the cds.
a0638a7b 144 my @all_john_cds = $johns_rs->search_related('cds')->all;
448c8424 145
f0bb26f3 146 # Fetch the next available row.
a0638a7b 147 my $first_john = $johns_rs->next;
448c8424 148
2053ab2a 149 # Specify ORDER BY on the query.
a0638a7b 150 my $first_john_cds_by_title_rs = $first_john->cds(
151 undef,
152 { order_by => 'title' }
153 );
448c8424 154
bd077b47 155 # Create a result set that will fetch the artist data
2053ab2a 156 # at the same time as it fetches CDs, using only one query.
884559b1 157 my $millennium_cds_rs = $schema->resultset('CD')->search(
a0638a7b 158 { year => 2000 },
159 { prefetch => 'artist' }
160 );
448c8424 161
880a1a0c 162 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
bd077b47 163 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
076652e8 164
264f1571 165 # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
166 # create() is the same as new() then insert().
884559b1 167 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
f183eccd 168 $new_cd->artist($cd->artist);
f183eccd 169 $new_cd->insert; # Auto-increment primary key filled in after INSERT
f183eccd 170 $new_cd->title('Fork');
171
884559b1 172 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
f183eccd 173
bd077b47 174 # change the year of all the millennium CDs at once
175 $millennium_cds_rs->update({ year => 2002 });
f183eccd 176
177=head1 DESCRIPTION
178
179This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
bd077b47 180(with a compatibility layer as a springboard for porting) and a resultset API
f183eccd 181that allows abstract encapsulation of database operations. It aims to make
182representing queries in your code as perl-ish as possible while still
a0638a7b 183providing access to as many of the capabilities of the database as possible,
f183eccd 184including retrieving related records from multiple tables in a single query,
bd077b47 185JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
f183eccd 186
187DBIx::Class can handle multi-column primary and foreign keys, complex
188queries and database-level paging, and does its best to only query the
75d07914 189database in order to return something you've directly asked for. If a
190resultset is used as an iterator it only fetches rows off the statement
191handle as requested in order to minimise memory usage. It has auto-increment
2053ab2a 192support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
193known to be used in production on at least the first four, and is fork-
75d07914 194and thread-safe out of the box (although your DBD may not be).
f183eccd 195
dfccde48 196This project is still under rapid development, so large new features may be
197marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
198Failing test cases are *always* welcome and point releases are put out rapidly
199as bugs are found and fixed.
200
201We do our best to maintain full backwards compatibility for published
202APIs, since DBIx::Class is used in production in many organisations,
203and even backwards incompatible changes to non-published APIs will be fixed
204if they're reported and doing so doesn't cost the codebase anything.
205
264f1571 206The test suite is quite substantial, and several developer releases
207are generally made to CPAN before the branch for the next release is
208merged back to trunk for a major release.
f183eccd 209
f183eccd 210=head1 WHERE TO GO NEXT
211
2ca930b4 212L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
213the modules where you will find documentation.
076652e8 214
3942ab4d 215=head1 AUTHOR
34d52be2 216
266bdcc3 217mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
34d52be2 218
dfccde48 219(I mostly consider myself "project founder" these days but the AUTHOR heading
220is traditional :)
221
3942ab4d 222=head1 CONTRIBUTORS
223
907ed671 224abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
84e3c114 225
6d84db2c 226aherzog: Adam Herzog <adam@herzogdesigns.com>
227
b703fec7 228amoore: Andrew Moore <amoore@cpan.org>
229
266bdcc3 230andyg: Andy Grundman <andy@hybridized.org>
3942ab4d 231
266bdcc3 232ank: Andres Kievsky
3942ab4d 233
624764ae 234arcanez: Justin Hunter <justin.d.hunter@gmail.com>
235
ce4c07df 236ash: Ash Berlin <ash@cpan.org>
237
3d5bd2af 238bert: Norbert Csongradi <bert@cpan.org>
239
967a4c40 240blblack: Brandon L. Black <blblack@gmail.com>
3942ab4d 241
62eb8fe8 242bluefeet: Aran Deltac <bluefeet@cpan.org>
243
f856fe01 244boghead: Bryan Beeley <cpan@beeley.org>
245
bcb8f3ed 246bricas: Brian Cassidy <bricas@cpan.org>
247
3d7e3e05 248brunov: Bruno Vecchi <vecchi.b@gmail.com>
249
281719d2 250caelum: Rafael Kitover <rkitover@cpan.org>
251
d3b0e369 252castaway: Jess Robinson
3942ab4d 253
266bdcc3 254claco: Christopher H. Laco
ccb9c9b1 255
266bdcc3 256clkao: CL Kao
3942ab4d 257
e21dfd6a 258da5id: David Jack Olrik <djo@cpan.org>
18360aed 259
13de943d 260debolaz: Anders Nor Berle <berle@cpan.org>
261
d1f542db 262dew: Dan Thomas <dan@godders.org>
263
266bdcc3 264dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
ccb9c9b1 265
9382ad07 266dnm: Justin Wheeler <jwheeler@datademons.com>
267
0818c9a7 268dpetrov: Dimitar Petrov <mitakaa@gmail.com>
269
266bdcc3 270dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
4685e006 271
5cffe785 272dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
8fe164b9 273
ade0fe3b 274frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
275
b4987ed0 276goraxe: Gordon Irving <goraxe@cpan.org>
277
d3b0e369 278gphat: Cory G Watson <gphat@cpan.org>
ad3d2d7c 279
e758ffe6 280groditi: Guillermo Roditi <groditi@cpan.org>
281
157ce0cf 282hobbs: Andrew Rodland <arodland@cpan.org>
283
5d779578 284ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
285
bee21976 286jasonmay: Jason May <jason.a.may@gmail.com>
287
d3b0e369 288jesper: Jesper Krogh
5fb0c64c 289
4a743a00 290jgoulah: John Goulah <jgoulah@cpan.org>
291
102a2984 292jguenther: Justin Guenther <jguenther@cpan.org>
d7c4c15c 293
a14a46e2 294jhannah: Jay Hannah <jay@jays.net>
295
8b93a938 296jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
297
11736b4c 298jon: Jon Schutz <jjschutz@cpan.org>
299
1aec4bac 300jshirley: J. Shirley <jshirley@gmail.com>
301
d3b0e369 302konobi: Scott McWhirter
535fc2ee 303
4367679a 304lukes: Luke Saunders <luke.saunders@gmail.com>
305
709ea492 306marcus: Marcus Ramberg <mramberg@cpan.org>
307
114780ee 308mattlaw: Matt Lawrence
309
58755bba 310michaelr: Michael Reddick <michael.reddick@gmail.com>
311
77e7e47d 312ned: Neil de Carteret
313
266bdcc3 314nigel: Nigel Metheringham <nigelm@cpan.org>
6565b410 315
d3b0e369 316ningu: David Kamholz <dkamholz@cpan.org>
317
66cf3a84 318Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
319
20b4c148 320norbi: Norbert Buchmuller <norbi@nix.hu>
321
48580715 322nuba: Nuba Princigalli <nuba@cpan.org>
323
d3b0e369 324Numa: Dan Sully <daniel@cpan.org>
325
dc571b76 326ovid: Curtis "Ovid" Poe <ovid@cpan.org>
327
bf356c54 328oyse: Øystein Torget <oystein.torget@dnv.com>
329
266bdcc3 330paulm: Paul Makepeace
4763f4b7 331
d3b0e369 332penguin: K J Cheetham
333
8cfef6f5 334perigrin: Chris Prather <chris@prather.org>
335
14899528 336peter: Peter Collingbourne <peter@pcc.me.uk>
caac1708 337
266bdcc3 338phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
a53b95f1 339
56fadd8f 340plu: Johannes Plunien <plu@cpan.org>
341
d3b0e369 342quicksilver: Jules Bean
022e0893 343
4ed01b34 344rafl: Florian Ragwitz <rafl@debian.org>
345
7ff0dace 346rbuels: Robert Buels <rmb32@cornell.edu>
347
0da8b7da 348rdj: Ryan D Johnson <ryan@innerfence.com>
349
66b1e361 350ribasushi: Peter Rabbitson <ribasushi@cpan.org>
d76e282a 351
b487918c 352rjbs: Ricardo Signes <rjbs@cpan.org>
353
6ffb5be5 354robkinyon: Rob Kinyon <rkinyon@cpan.org>
355
e4c9f3f0 356Roman: Roman Filippov <romanf@cpan.org>
357
d3b0e369 358sc_: Just Another Perl Hacker
ba606e58 359
266bdcc3 360scotty: Scotty Allen <scotty@scottyallen.com>
181a28f4 361
1c133e22 362semifor: Marc Mims <marc@questright.com>
363
20b4c148 364solomon: Jared Johnson <jaredj@nmgi.com>
365
88f937fb 366spb: Stephen Bennett <stephen@freenode.net>
367
637ca936 368sszabo: Stephan Szabo <sszabo@bigpanda.com>
369
386c2272 370teejay : Aaron Trevena <teejay@cpan.org>
371
84e3c114 372Todd Lipcon
e063fe2c 373
6eb6264e 374Tom Hukins
375
2e4b6d78 376tonvoon: Ton Voon <tonvoon@cpan.org>
377
d15e3fc5 378triode: Pete Gamache <gamache@cpan.org>
379
d3b0e369 380typester: Daisuke Murase <typester@cpan.org>
c0e7b4e5 381
4740bdb7 382victori: Victor Igumnov <victori@cpan.org>
383
d3b0e369 384wdh: Will Hawes
4c248161 385
00c03ced 386willert: Sebastian Willert <willert@cpan.org>
387
66d2a14e 388wreis: Wallace Reis <wreis@cpan.org>
389
d3b0e369 390zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
78060df8 391
c1807ed5 392Possum: Daniel LeWarne <possum@cpan.org>
393
b38e10bd 394=head1 COPYRIGHT
395
48580715 396Copyright (c) 2005 - 2010 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
b38e10bd 397as listed above.
398
96154ef7 399=head1 LICENSE
400
401This library is free software and may be distributed under the same terms
402as perl itself.
403
34d52be2 404=cut