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