revert part of 3220, apparently it is breaking cloning behavior in subtle ways that...
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class.pm
CommitLineData
ea2e61bf 1package DBIx::Class;
2
5d283305 3use strict;
4use warnings;
5
5d283305 6use vars qw($VERSION);
3c0068c1 7use base qw/DBIx::Class::Componentised Class::Data::Accessor/;
8
9sub mk_classdata { shift->mk_classaccessor(@_); }
7411204b 10sub component_base_class { 'DBIx::Class' }
227d4dee 11
95da6f35 12# Always remember to do all digits for the version even if they're 0
13# i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
14# brain damage and presumably various other packaging systems too
15
13f897a0 16$VERSION = '0.07006';
b8777a0d 17
f0750722 18sub MODIFY_CODE_ATTRIBUTES {
b5d2c57f 19 my ($class,$code,@attrs) = @_;
20 $class->mk_classdata('__attr_cache' => {})
21 unless $class->can('__attr_cache');
22 $class->__attr_cache->{$code} = [@attrs];
23 return ();
f0750722 24}
25
da95b45f 26sub _attr_cache {
b5d2c57f 27 my $self = shift;
28 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
29 my $rest = eval { $self->next::method };
30 return $@ ? $cache : { %$cache, %$rest };
da95b45f 31}
32
ea2e61bf 331;
34d52be2 34
75d07914 35=head1 NAME
34d52be2 36
7e4b2f59 37DBIx::Class - Extensible and flexible object <-> relational mapper.
34d52be2 38
39=head1 SYNOPSIS
40
2053ab2a 41Create a schema class called DB/Main.pm:
34d52be2 42
a0638a7b 43 package DB::Main;
44 use base qw/DBIx::Class::Schema/;
34d52be2 45
a0638a7b 46 __PACKAGE__->load_classes();
daec44b8 47
a0638a7b 48 1;
daec44b8 49
2053ab2a 50Create a table class to represent artists, who have many CDs, in DB/Main/Artist.pm:
daec44b8 51
a0638a7b 52 package DB::Main::Artist;
53 use base qw/DBIx::Class/;
daec44b8 54
a0638a7b 55 __PACKAGE__->load_components(qw/PK::Auto Core/);
56 __PACKAGE__->table('artist');
57 __PACKAGE__->add_columns(qw/ artistid name /);
58 __PACKAGE__->set_primary_key('artistid');
2053ab2a 59 __PACKAGE__->has_many(cds => 'DB::Main::CD');
daec44b8 60
a0638a7b 61 1;
daec44b8 62
2053ab2a 63A table class to represent a CD, which belongs to an artist, in DB/Main/CD.pm:
39fe0e65 64
a0638a7b 65 package DB::Main::CD;
66 use base qw/DBIx::Class/;
39fe0e65 67
a0638a7b 68 __PACKAGE__->load_components(qw/PK::Auto Core/);
69 __PACKAGE__->table('cd');
2053ab2a 70 __PACKAGE__->add_columns(qw/ cdid artist title year /);
a0638a7b 71 __PACKAGE__->set_primary_key('cdid');
2053ab2a 72 __PACKAGE__->belongs_to(artist => 'DB::Main::Artist');
39fe0e65 73
a0638a7b 74 1;
39fe0e65 75
a0638a7b 76Then you can use these classes in your application's code:
39fe0e65 77
a0638a7b 78 # Connect to your database.
2053ab2a 79 use DB::Main;
80 my $schema = DB::Main->connect($dbi_dsn, $user, $pass, \%dbi_params);
a0638a7b 81
82 # Query for all artists and put them in an array,
83 # or retrieve them as a result set object.
2053ab2a 84 my @all_artists = $schema->resultset('Artist')->all;
85 my $all_artists_rs = $schema->resultset('Artist');
126042ee 86
a0638a7b 87 # Create a result set to search for artists.
86beca1d 88 # This does not query the DB.
2053ab2a 89 my $johns_rs = $schema->resultset('Artist')->search(
6576ef54 90 # Build your WHERE using an SQL::Abstract structure:
2053ab2a 91 { name => { like => 'John%' } }
a0638a7b 92 );
39fe0e65 93
2053ab2a 94 # Execute a joined query to get the cds.
a0638a7b 95 my @all_john_cds = $johns_rs->search_related('cds')->all;
448c8424 96
2053ab2a 97 # Fetch only the next row.
a0638a7b 98 my $first_john = $johns_rs->next;
448c8424 99
2053ab2a 100 # Specify ORDER BY on the query.
a0638a7b 101 my $first_john_cds_by_title_rs = $first_john->cds(
102 undef,
103 { order_by => 'title' }
104 );
448c8424 105
2053ab2a 106 # Create a result set that will fetch the artist relationship
107 # at the same time as it fetches CDs, using only one query.
884559b1 108 my $millennium_cds_rs = $schema->resultset('CD')->search(
a0638a7b 109 { year => 2000 },
110 { prefetch => 'artist' }
111 );
448c8424 112
880a1a0c 113 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
f183eccd 114 my $cd_artist_name = $cd->artist->name; # Already has the data so no query
076652e8 115
884559b1 116 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
f183eccd 117 $new_cd->artist($cd->artist);
f183eccd 118 $new_cd->insert; # Auto-increment primary key filled in after INSERT
f183eccd 119 $new_cd->title('Fork');
120
884559b1 121 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
f183eccd 122
880a1a0c 123 $millennium_cds_rs->update({ year => 2002 }); # Single-query bulk update
f183eccd 124
125=head1 DESCRIPTION
126
127This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
a0638a7b 128(and a compatibility layer as a springboard for porting) and a resultset API
f183eccd 129that allows abstract encapsulation of database operations. It aims to make
130representing queries in your code as perl-ish as possible while still
a0638a7b 131providing access to as many of the capabilities of the database as possible,
f183eccd 132including retrieving related records from multiple tables in a single query,
133JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support.
134
135DBIx::Class can handle multi-column primary and foreign keys, complex
136queries and database-level paging, and does its best to only query the
75d07914 137database in order to return something you've directly asked for. If a
138resultset is used as an iterator it only fetches rows off the statement
139handle as requested in order to minimise memory usage. It has auto-increment
2053ab2a 140support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
141known to be used in production on at least the first four, and is fork-
75d07914 142and thread-safe out of the box (although your DBD may not be).
f183eccd 143
144This project is still under rapid development, so features added in the
2053ab2a 145latest major release may not work 100% yet -- check the Changes if you run
f183eccd 146into trouble, and beware of anything explicitly marked EXPERIMENTAL. Failing
147test cases are *always* welcome and point releases are put out rapidly as
148bugs are found and fixed.
149
86beca1d 150Even so, we do our best to maintain full backwards compatibility for published
2053ab2a 151APIs, since DBIx::Class is used in production in a number of organisations.
152The test suite is quite substantial, and several developer releases are
86beca1d 153generally made to CPAN before the -current branch is merged back to trunk for
154a major release.
f183eccd 155
2053ab2a 156The community can be found via:
f183eccd 157
158 Mailing list: http://lists.rawmode.org/mailman/listinfo/dbix-class/
159
160 SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/
161
162 Wiki: http://dbix-class.shadowcatsystems.co.uk/
163
164 IRC: irc.perl.org#dbix-class
165
166=head1 WHERE TO GO NEXT
167
2ca930b4 168L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
169the modules where you will find documentation.
076652e8 170
3942ab4d 171=head1 AUTHOR
34d52be2 172
266bdcc3 173mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
34d52be2 174
3942ab4d 175=head1 CONTRIBUTORS
176
266bdcc3 177abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
84e3c114 178
266bdcc3 179andyg: Andy Grundman <andy@hybridized.org>
3942ab4d 180
266bdcc3 181ank: Andres Kievsky
3942ab4d 182
967a4c40 183blblack: Brandon L. Black <blblack@gmail.com>
3942ab4d 184
62eb8fe8 185bluefeet: Aran Deltac <bluefeet@cpan.org>
186
d3b0e369 187captainL: Luke Saunders <luke.saunders@gmail.com>
188
189castaway: Jess Robinson
3942ab4d 190
266bdcc3 191claco: Christopher H. Laco
ccb9c9b1 192
266bdcc3 193clkao: CL Kao
3942ab4d 194
266bdcc3 195dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
ccb9c9b1 196
d3b0e369 197draven: Marcus Ramberg <mramberg@cpan.org>
4685e006 198
266bdcc3 199dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
4685e006 200
5cffe785 201dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
8fe164b9 202
d3b0e369 203gphat: Cory G Watson <gphat@cpan.org>
ad3d2d7c 204
d3b0e369 205jesper: Jesper Krogh
5fb0c64c 206
102a2984 207jguenther: Justin Guenther <jguenther@cpan.org>
d7c4c15c 208
1aec4bac 209jshirley: J. Shirley <jshirley@gmail.com>
210
d3b0e369 211konobi: Scott McWhirter
535fc2ee 212
d3b0e369 213LTJake: Brian Cassidy <bricas@cpan.org>
103e3e03 214
266bdcc3 215nigel: Nigel Metheringham <nigelm@cpan.org>
6565b410 216
d3b0e369 217ningu: David Kamholz <dkamholz@cpan.org>
218
219Numa: Dan Sully <daniel@cpan.org>
220
266bdcc3 221paulm: Paul Makepeace
4763f4b7 222
d3b0e369 223penguin: K J Cheetham
224
266bdcc3 225phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
a53b95f1 226
d3b0e369 227quicksilver: Jules Bean
022e0893 228
d3b0e369 229sc_: Just Another Perl Hacker
ba606e58 230
266bdcc3 231scotty: Scotty Allen <scotty@scottyallen.com>
181a28f4 232
637ca936 233sszabo: Stephan Szabo <sszabo@bigpanda.com>
234
84e3c114 235Todd Lipcon
e063fe2c 236
d3b0e369 237typester: Daisuke Murase <typester@cpan.org>
c0e7b4e5 238
d3b0e369 239wdh: Will Hawes
4c248161 240
00c03ced 241willert: Sebastian Willert <willert@cpan.org>
242
d3b0e369 243zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
78060df8 244
34d52be2 245=head1 LICENSE
246
247You may distribute this code under the same terms as Perl itself.
248
249=cut