Add NoObjectIndex which turns the live object index off and removes all the
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class.pm
1 package DBIx::Class;
2
3 use strict;
4 use warnings;
5
6 use vars qw($VERSION);
7 use base qw/DBIx::Class::Componentised Class::Accessor::Grouped/;
8 use DBIx::Class::StartupCheck;
9
10
11 sub mk_classdata { 
12   shift->mk_classaccessor(@_);
13 }
14
15 sub mk_classaccessor {
16   my $self = shift;
17   $self->mk_group_accessors('inherited', $_[0]); 
18   $self->set_inherited(@_) if @_ > 1;
19 }
20
21 sub component_base_class { 'DBIx::Class' }
22
23 # Always remember to do all digits for the version even if they're 0
24 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
25 # brain damage and presumably various other packaging systems too
26
27 $VERSION = '0.08009';
28
29 sub MODIFY_CODE_ATTRIBUTES {
30   my ($class,$code,@attrs) = @_;
31   $class->mk_classdata('__attr_cache' => {})
32     unless $class->can('__attr_cache');
33   $class->__attr_cache->{$code} = [@attrs];
34   return ();
35 }
36
37 sub _attr_cache {
38   my $self = shift;
39   my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
40   my $rest = eval { $self->next::method };
41   return $@ ? $cache : { %$cache, %$rest };
42 }
43
44 1;
45
46 =head1 NAME
47
48 DBIx::Class - Extensible and flexible object <-> relational mapper.
49
50 =head1 SYNOPSIS
51
52 Create a schema class called DB/Main.pm:
53
54   package DB::Main;
55   use base qw/DBIx::Class::Schema/;
56
57   __PACKAGE__->load_classes();
58
59   1;
60
61 Create a table class to represent artists, who have many CDs, in DB/Main/Artist.pm:
62
63   package DB::Main::Artist;
64   use base qw/DBIx::Class/;
65
66   __PACKAGE__->load_components(qw/PK::Auto Core/);
67   __PACKAGE__->table('artist');
68   __PACKAGE__->add_columns(qw/ artistid name /);
69   __PACKAGE__->set_primary_key('artistid');
70   __PACKAGE__->has_many(cds => 'DB::Main::CD');
71
72   1;
73
74 A table class to represent a CD, which belongs to an artist, in DB/Main/CD.pm:
75
76   package DB::Main::CD;
77   use base qw/DBIx::Class/;
78
79   __PACKAGE__->load_components(qw/PK::Auto Core/);
80   __PACKAGE__->table('cd');
81   __PACKAGE__->add_columns(qw/ cdid artist title year /);
82   __PACKAGE__->set_primary_key('cdid');
83   __PACKAGE__->belongs_to(artist => 'DB::Main::Artist');
84
85   1;
86
87 Then you can use these classes in your application's code:
88
89   # Connect to your database.
90   use DB::Main;
91   my $schema = DB::Main->connect($dbi_dsn, $user, $pass, \%dbi_params);
92
93   # Query for all artists and put them in an array,
94   # or retrieve them as a result set object.
95   my @all_artists = $schema->resultset('Artist')->all;
96   my $all_artists_rs = $schema->resultset('Artist');
97
98   # Create a result set to search for artists.
99   # This does not query the DB.
100   my $johns_rs = $schema->resultset('Artist')->search(
101     # Build your WHERE using an SQL::Abstract structure:
102     { name => { like => 'John%' } }
103   );
104
105   # Execute a joined query to get the cds.
106   my @all_john_cds = $johns_rs->search_related('cds')->all;
107
108   # Fetch only the next row.
109   my $first_john = $johns_rs->next;
110
111   # Specify ORDER BY on the query.
112   my $first_john_cds_by_title_rs = $first_john->cds(
113     undef,
114     { order_by => 'title' }
115   );
116
117   # Create a result set that will fetch the artist relationship
118   # at the same time as it fetches CDs, using only one query.
119   my $millennium_cds_rs = $schema->resultset('CD')->search(
120     { year => 2000 },
121     { prefetch => 'artist' }
122   );
123
124   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
125   my $cd_artist_name = $cd->artist->name; # Already has the data so no query
126
127   # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
128   # create() is the same as new() then insert().
129   my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
130   $new_cd->artist($cd->artist);
131   $new_cd->insert; # Auto-increment primary key filled in after INSERT
132   $new_cd->title('Fork');
133
134   $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
135
136   $millennium_cds_rs->update({ year => 2002 }); # Single-query bulk update
137
138 =head1 DESCRIPTION
139
140 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
141 (and a compatibility layer as a springboard for porting) and a resultset API
142 that allows abstract encapsulation of database operations. It aims to make
143 representing queries in your code as perl-ish as possible while still
144 providing access to as many of the capabilities of the database as possible,
145 including retrieving related records from multiple tables in a single query,
146 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support.
147
148 DBIx::Class can handle multi-column primary and foreign keys, complex
149 queries and database-level paging, and does its best to only query the
150 database in order to return something you've directly asked for. If a
151 resultset is used as an iterator it only fetches rows off the statement
152 handle as requested in order to minimise memory usage. It has auto-increment
153 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
154 known to be used in production on at least the first four, and is fork-
155 and thread-safe out of the box (although your DBD may not be).
156
157 This project is still under rapid development, so large new features may be
158 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
159 Failing test cases are *always* welcome and point releases are put out rapidly
160 as bugs are found and fixed.
161
162 We do our best to maintain full backwards compatibility for published
163 APIs, since DBIx::Class is used in production in many organisations,
164 and even backwards incompatible changes to non-published APIs will be fixed
165 if they're reported and doing so doesn't cost the codebase anything.
166
167 The test suite is quite substantial, and several developer releases
168 are generally made to CPAN before the branch for the next release is
169 merged back to trunk for a major release.
170
171 The community can be found via:
172
173   Mailing list: http://lists.scsys.co.uk/mailman/listinfo/dbix-class/
174
175   SVN: http://dev.catalyst.perl.org/repos/bast/DBIx-Class/
176
177   SVNWeb: http://dev.catalyst.perl.org/svnweb/bast/browse/DBIx-Class/
178
179   IRC: irc.perl.org#dbix-class
180
181 =head1 WHERE TO GO NEXT
182
183 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
184 the modules where you will find documentation.
185
186 =head1 AUTHOR
187
188 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
189
190 (I mostly consider myself "project founder" these days but the AUTHOR heading
191 is traditional :)
192
193 =head1 CONTRIBUTORS
194
195 abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
196
197 aherzog: Adam Herzog <adam@herzogdesigns.com>
198
199 andyg: Andy Grundman <andy@hybridized.org>
200
201 ank: Andres Kievsky
202
203 ash: Ash Berlin <ash@cpan.org>
204
205 bert: Norbert Csongradi <bert@cpan.org>
206
207 blblack: Brandon L. Black <blblack@gmail.com>
208
209 bluefeet: Aran Deltac <bluefeet@cpan.org>
210
211 captainL: Luke Saunders <luke.saunders@gmail.com>
212
213 castaway: Jess Robinson
214
215 claco: Christopher H. Laco
216
217 clkao: CL Kao
218
219 da5id: David Jack Olrik <djo@cpan.org>
220
221 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
222
223 dnm: Justin Wheeler <jwheeler@datademons.com>
224
225 draven: Marcus Ramberg <mramberg@cpan.org>
226
227 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
228
229 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
230
231 gphat: Cory G Watson <gphat@cpan.org>
232
233 jesper: Jesper Krogh
234
235 jguenther: Justin Guenther <jguenther@cpan.org>
236
237 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
238
239 jon: Jon Schutz <jjschutz@cpan.org>
240
241 jshirley: J. Shirley <jshirley@gmail.com>
242
243 konobi: Scott McWhirter
244
245 LTJake: Brian Cassidy <bricas@cpan.org>
246
247 mattlaw: Matt Lawrence
248
249 ned: Neil de Carteret
250
251 nigel: Nigel Metheringham <nigelm@cpan.org>
252
253 ningu: David Kamholz <dkamholz@cpan.org>
254
255 Numa: Dan Sully <daniel@cpan.org>
256
257 oyse: Ã˜ystein Torget <oystein.torget@dnv.com>
258
259 paulm: Paul Makepeace
260
261 penguin: K J Cheetham
262
263 perigrin: Chris Prather <chris@prather.org>
264
265 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
266
267 quicksilver: Jules Bean
268
269 sc_: Just Another Perl Hacker
270
271 scotty: Scotty Allen <scotty@scottyallen.com>
272
273 semifor: Marc Mims <marc@questright.com>
274
275 sszabo: Stephan Szabo <sszabo@bigpanda.com>
276
277 Todd Lipcon
278
279 Tom Hukins
280
281 typester: Daisuke Murase <typester@cpan.org>
282
283 victori: Victor Igumnov <victori@cpan.org>
284
285 wdh: Will Hawes
286
287 willert: Sebastian Willert <willert@cpan.org>
288
289 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
290
291 =head1 LICENSE
292
293 You may distribute this code under the same terms as Perl itself.
294
295 =cut