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