Commit | Line | Data |
ea2e61bf |
1 | package DBIx::Class; |
2 | |
5d283305 |
3 | use strict; |
4 | use warnings; |
5 | |
5d283305 |
6 | use vars qw($VERSION); |
3c0068c1 |
7 | use base qw/DBIx::Class::Componentised Class::Data::Accessor/; |
8 | |
9 | sub mk_classdata { shift->mk_classaccessor(@_); } |
7411204b |
10 | sub 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 | |
5378bbdd |
16 | $VERSION = '0.07999_01'; |
b8777a0d |
17 | |
f0750722 |
18 | sub MODIFY_CODE_ATTRIBUTES { |
19 | my ($class,$code,@attrs) = @_; |
bc0c9800 |
20 | $class->mk_classdata('__attr_cache' => {}) |
21 | unless $class->can('__attr_cache'); |
da95b45f |
22 | $class->__attr_cache->{$code} = [@attrs]; |
f0750722 |
23 | return (); |
24 | } |
25 | |
da95b45f |
26 | sub _attr_cache { |
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 }; |
31 | } |
32 | |
ea2e61bf |
33 | 1; |
34d52be2 |
34 | |
75d07914 |
35 | =head1 NAME |
34d52be2 |
36 | |
7e4b2f59 |
37 | DBIx::Class - Extensible and flexible object <-> relational mapper. |
34d52be2 |
38 | |
39 | =head1 SYNOPSIS |
40 | |
2053ab2a |
41 | Create 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 |
50 | Create 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 |
63 | A 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 |
76 | Then 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 | |
127 | This 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 |
129 | that allows abstract encapsulation of database operations. It aims to make |
130 | representing queries in your code as perl-ish as possible while still |
a0638a7b |
131 | providing access to as many of the capabilities of the database as possible, |
f183eccd |
132 | including retrieving related records from multiple tables in a single query, |
133 | JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support. |
134 | |
135 | DBIx::Class can handle multi-column primary and foreign keys, complex |
136 | queries and database-level paging, and does its best to only query the |
75d07914 |
137 | database in order to return something you've directly asked for. If a |
138 | resultset is used as an iterator it only fetches rows off the statement |
139 | handle as requested in order to minimise memory usage. It has auto-increment |
2053ab2a |
140 | support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is |
141 | known to be used in production on at least the first four, and is fork- |
75d07914 |
142 | and thread-safe out of the box (although your DBD may not be). |
f183eccd |
143 | |
144 | This project is still under rapid development, so features added in the |
2053ab2a |
145 | latest major release may not work 100% yet -- check the Changes if you run |
f183eccd |
146 | into trouble, and beware of anything explicitly marked EXPERIMENTAL. Failing |
147 | test cases are *always* welcome and point releases are put out rapidly as |
148 | bugs are found and fixed. |
149 | |
86beca1d |
150 | Even so, we do our best to maintain full backwards compatibility for published |
2053ab2a |
151 | APIs, since DBIx::Class is used in production in a number of organisations. |
152 | The test suite is quite substantial, and several developer releases are |
86beca1d |
153 | generally made to CPAN before the -current branch is merged back to trunk for |
154 | a major release. |
f183eccd |
155 | |
2053ab2a |
156 | The 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 |
168 | L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and |
169 | the modules where you will find documentation. |
076652e8 |
170 | |
3942ab4d |
171 | =head1 AUTHOR |
34d52be2 |
172 | |
266bdcc3 |
173 | mst: Matt S. Trout <mst@shadowcatsystems.co.uk> |
34d52be2 |
174 | |
3942ab4d |
175 | =head1 CONTRIBUTORS |
176 | |
266bdcc3 |
177 | abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com> |
84e3c114 |
178 | |
266bdcc3 |
179 | andyg: Andy Grundman <andy@hybridized.org> |
3942ab4d |
180 | |
266bdcc3 |
181 | ank: Andres Kievsky |
3942ab4d |
182 | |
3d5bd2af |
183 | bert: Norbert Csongradi <bert@cpan.org> |
184 | |
967a4c40 |
185 | blblack: Brandon L. Black <blblack@gmail.com> |
3942ab4d |
186 | |
62eb8fe8 |
187 | bluefeet: Aran Deltac <bluefeet@cpan.org> |
188 | |
d3b0e369 |
189 | captainL: Luke Saunders <luke.saunders@gmail.com> |
190 | |
191 | castaway: Jess Robinson |
3942ab4d |
192 | |
266bdcc3 |
193 | claco: Christopher H. Laco |
ccb9c9b1 |
194 | |
266bdcc3 |
195 | clkao: CL Kao |
3942ab4d |
196 | |
266bdcc3 |
197 | dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com> |
ccb9c9b1 |
198 | |
d3b0e369 |
199 | draven: Marcus Ramberg <mramberg@cpan.org> |
4685e006 |
200 | |
266bdcc3 |
201 | dwc: Daniel Westermann-Clark <danieltwc@cpan.org> |
4685e006 |
202 | |
5cffe785 |
203 | dyfrgi: Michael Leuchtenburg <michael@slashhome.org> |
8fe164b9 |
204 | |
d3b0e369 |
205 | gphat: Cory G Watson <gphat@cpan.org> |
ad3d2d7c |
206 | |
d3b0e369 |
207 | jesper: Jesper Krogh |
5fb0c64c |
208 | |
102a2984 |
209 | jguenther: Justin Guenther <jguenther@cpan.org> |
d7c4c15c |
210 | |
d3b0e369 |
211 | konobi: Scott McWhirter |
535fc2ee |
212 | |
d3b0e369 |
213 | LTJake: Brian Cassidy <bricas@cpan.org> |
103e3e03 |
214 | |
266bdcc3 |
215 | nigel: Nigel Metheringham <nigelm@cpan.org> |
6565b410 |
216 | |
d3b0e369 |
217 | ningu: David Kamholz <dkamholz@cpan.org> |
218 | |
219 | Numa: Dan Sully <daniel@cpan.org> |
220 | |
266bdcc3 |
221 | paulm: Paul Makepeace |
4763f4b7 |
222 | |
d3b0e369 |
223 | penguin: K J Cheetham |
224 | |
266bdcc3 |
225 | phaylon: Robert Sedlacek <phaylon@dunkelheit.at> |
a53b95f1 |
226 | |
d3b0e369 |
227 | quicksilver: Jules Bean |
022e0893 |
228 | |
d3b0e369 |
229 | sc_: Just Another Perl Hacker |
ba606e58 |
230 | |
266bdcc3 |
231 | scotty: Scotty Allen <scotty@scottyallen.com> |
181a28f4 |
232 | |
637ca936 |
233 | sszabo: Stephan Szabo <sszabo@bigpanda.com> |
234 | |
84e3c114 |
235 | Todd Lipcon |
e063fe2c |
236 | |
d3b0e369 |
237 | typester: Daisuke Murase <typester@cpan.org> |
c0e7b4e5 |
238 | |
d3b0e369 |
239 | wdh: Will Hawes |
4c248161 |
240 | |
d3b0e369 |
241 | zamolxes: Bogdan Lucaciu <bogdan@wiz.ro> |
78060df8 |
242 | |
34d52be2 |
243 | =head1 LICENSE |
244 | |
245 | You may distribute this code under the same terms as Perl itself. |
246 | |
247 | =cut |