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 | |
1346e22d |
16 | $VERSION = '0.05999_04'; |
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 | |
35 | =head1 NAME |
36 | |
7e4b2f59 |
37 | DBIx::Class - Extensible and flexible object <-> relational mapper. |
34d52be2 |
38 | |
39 | =head1 SYNOPSIS |
40 | |
a0638a7b |
41 | Create a base 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 | |
a0638a7b |
50 | Create a class the represent artists, who have many |
51 | CDs, in DB/Main/Artist.pm: |
daec44b8 |
52 | |
a0638a7b |
53 | package DB::Main::Artist; |
54 | use base qw/DBIx::Class/; |
daec44b8 |
55 | |
a0638a7b |
56 | __PACKAGE__->load_components(qw/PK::Auto Core/); |
57 | __PACKAGE__->table('artist'); |
58 | __PACKAGE__->add_columns(qw/ artistid name /); |
59 | __PACKAGE__->set_primary_key('artistid'); |
60 | __PACKAGE__->has_many('cds' => 'DB::Main::CD'); |
daec44b8 |
61 | |
a0638a7b |
62 | 1; |
daec44b8 |
63 | |
a0638a7b |
64 | A class to represent a CD, which belongs to an |
65 | artist, in DB/Main/CD.pm: |
39fe0e65 |
66 | |
a0638a7b |
67 | package DB::Main::CD; |
68 | use base qw/DBIx::Class/; |
39fe0e65 |
69 | |
a0638a7b |
70 | __PACKAGE__->load_components(qw/PK::Auto Core/); |
71 | __PACKAGE__->table('cd'); |
72 | __PACKAGE__->add_columns(qw/ cdid artist title year/); |
73 | __PACKAGE__->set_primary_key('cdid'); |
74 | __PACKAGE__->belongs_to('artist' => 'DB::Main::Artist'); |
39fe0e65 |
75 | |
a0638a7b |
76 | 1; |
39fe0e65 |
77 | |
a0638a7b |
78 | Then you can use these classes in your application's code: |
39fe0e65 |
79 | |
a0638a7b |
80 | # Connect to your database. |
81 | my $ds = DB::Main->connect(@dbi_dsn); |
82 | |
83 | # Query for all artists and put them in an array, |
84 | # or retrieve them as a result set object. |
f183eccd |
85 | my @all_artists = $ds->resultset('Artist')->all; |
a0638a7b |
86 | my $all_artists_rs = $ds->resultset('Artist'); |
126042ee |
87 | |
a0638a7b |
88 | # Create a result set to search for artists. |
89 | # This does not query the DB, yet. |
f183eccd |
90 | my $johns_rs = $ds->resultset('Artist')->search( |
a0638a7b |
91 | # Build your WHERE using an SQL::Abstract structure: |
92 | { 'name' => { 'like', 'John%' } } |
93 | ); |
39fe0e65 |
94 | |
a0638a7b |
95 | # Now the query is executed. |
96 | my @all_john_cds = $johns_rs->search_related('cds')->all; |
448c8424 |
97 | |
a0638a7b |
98 | # Queries but only fetches one row so far. |
99 | my $first_john = $johns_rs->next; |
448c8424 |
100 | |
a0638a7b |
101 | my $first_john_cds_by_title_rs = $first_john->cds( |
102 | undef, |
103 | { order_by => 'title' } |
104 | ); |
448c8424 |
105 | |
f183eccd |
106 | my $millenium_cds_rs = $ds->resultset('CD')->search( |
a0638a7b |
107 | { year => 2000 }, |
108 | { prefetch => 'artist' } |
109 | ); |
448c8424 |
110 | |
f183eccd |
111 | my $cd = $millenium_cds_rs->next; # SELECT ... FROM cds JOIN artists ... |
f183eccd |
112 | my $cd_artist_name = $cd->artist->name; # Already has the data so no query |
076652e8 |
113 | |
f183eccd |
114 | my $new_cd = $ds->resultset('CD')->new({ title => 'Spoon' }); |
f183eccd |
115 | $new_cd->artist($cd->artist); |
f183eccd |
116 | $new_cd->insert; # Auto-increment primary key filled in after INSERT |
f183eccd |
117 | $new_cd->title('Fork'); |
118 | |
119 | $ds->txn_do(sub { $new_cd->update }); # Runs the update in a transaction |
120 | |
121 | $millenium_cds_rs->update({ year => 2002 }); # Single-query bulk update |
122 | |
123 | =head1 DESCRIPTION |
124 | |
125 | This is an SQL to OO mapper with an object API inspired by L<Class::DBI> |
a0638a7b |
126 | (and a compatibility layer as a springboard for porting) and a resultset API |
f183eccd |
127 | that allows abstract encapsulation of database operations. It aims to make |
128 | representing queries in your code as perl-ish as possible while still |
a0638a7b |
129 | providing access to as many of the capabilities of the database as possible, |
f183eccd |
130 | including retrieving related records from multiple tables in a single query, |
131 | JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support. |
132 | |
133 | DBIx::Class can handle multi-column primary and foreign keys, complex |
134 | queries and database-level paging, and does its best to only query the |
135 | database when it actually needs to in order to return something the user's |
136 | asked for. If a resultset is used as an iterator it only fetches rows off |
137 | the statement handle as requested in order to minimise memory usage. It |
138 | has auto-increment support for SQLite, MySQL, PostgreSQL, Oracle, SQL |
139 | Server and DB2 and is known to be used in production on at least the first |
140 | four, and is fork- and thread-safe out of the box (although your DBD may not |
141 | be). |
142 | |
143 | This project is still under rapid development, so features added in the |
144 | latest major release may not work 100% yet - check the Changes if you run |
145 | into trouble, and beware of anything explicitly marked EXPERIMENTAL. Failing |
146 | test cases are *always* welcome and point releases are put out rapidly as |
147 | bugs are found and fixed. |
148 | |
149 | Even so, we do your best to maintain full backwards compatibility for published |
150 | APIs since DBIx::Class is used in production in a number of organisations; |
151 | the test suite is now fairly substantial and several developer releases are |
152 | generally made to CPAN before the -current branch is merged back to trunk. |
153 | |
154 | The community can be found via - |
155 | |
156 | Mailing list: http://lists.rawmode.org/mailman/listinfo/dbix-class/ |
157 | |
158 | SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/ |
159 | |
160 | Wiki: http://dbix-class.shadowcatsystems.co.uk/ |
161 | |
162 | IRC: irc.perl.org#dbix-class |
163 | |
164 | =head1 WHERE TO GO NEXT |
165 | |
166 | =over 4 |
8091aa91 |
167 | |
a0638a7b |
168 | =item L<DBIx::Class::Manual> - user's manual |
8091aa91 |
169 | |
f183eccd |
170 | =item L<DBIx::Class::Core> - DBIC Core Classes |
171 | |
a39e84a3 |
172 | =item L<DBIx::Class::CDBICompat> - L<Class::DBI> Compat layer |
076652e8 |
173 | |
f183eccd |
174 | =item L<DBIx::Class::Schema> - schema and connection container |
076652e8 |
175 | |
f183eccd |
176 | =item L<DBIx::Class::ResultSource> - tables and table-like things |
076652e8 |
177 | |
f183eccd |
178 | =item L<DBIx::Class::ResultSet> - encapsulates a query and its results |
076652e8 |
179 | |
a39e84a3 |
180 | =item L<DBIx::Class::Row> - row-level methods |
4db53147 |
181 | |
a39e84a3 |
182 | =item L<DBIx::Class::PK> - primary key methods |
183 | |
184 | =item L<DBIx::Class::Relationship> - relationships between tables |
185 | |
186 | =back |
076652e8 |
187 | |
3942ab4d |
188 | =head1 AUTHOR |
34d52be2 |
189 | |
daec44b8 |
190 | Matt S. Trout <mst@shadowcatsystems.co.uk> |
34d52be2 |
191 | |
3942ab4d |
192 | =head1 CONTRIBUTORS |
193 | |
84e3c114 |
194 | Alexander Hartmaier <alex_hartmaier@hotmail.com> |
195 | |
3942ab4d |
196 | Andy Grundman <andy@hybridized.org> |
197 | |
84e3c114 |
198 | Andres Kievsky |
3942ab4d |
199 | |
84e3c114 |
200 | Brandon Black |
3942ab4d |
201 | |
84e3c114 |
202 | Brian Cassidy <bricas@cpan.org> |
3942ab4d |
203 | |
84e3c114 |
204 | Christopher H. Laco |
ccb9c9b1 |
205 | |
84e3c114 |
206 | CL Kao |
3942ab4d |
207 | |
84e3c114 |
208 | Daisuke Murase <typester@cpan.org> |
3942ab4d |
209 | |
84e3c114 |
210 | Dan Kubb <dan.kubb-cpan@onautopilot.com> |
ccb9c9b1 |
211 | |
84e3c114 |
212 | Dan Sully <daniel@cpan.org> |
4685e006 |
213 | |
84e3c114 |
214 | Daniel Westermann-Clark <danieltwc@cpan.org> |
4685e006 |
215 | |
84e3c114 |
216 | David Kamholz <dkamholz@cpan.org> |
4685e006 |
217 | |
84e3c114 |
218 | Jesper Krogh |
8fe164b9 |
219 | |
84e3c114 |
220 | Jess Robinson |
ad3d2d7c |
221 | |
84e3c114 |
222 | Jules Bean |
5fb0c64c |
223 | |
84e3c114 |
224 | Justin Guenther <guentherj@agr.gc.ca> |
d7c4c15c |
225 | |
84e3c114 |
226 | Marcus Ramberg <mramberg@cpan.org> |
103e3e03 |
227 | |
6565b410 |
228 | Nigel Metheringham <nigelm@cpan.org> |
229 | |
84e3c114 |
230 | Paul Makepeace |
4763f4b7 |
231 | |
84e3c114 |
232 | Robert Sedlacek <phaylon@dunkelheit.at> |
a53b95f1 |
233 | |
84e3c114 |
234 | sc_ of irc.perl.org#dbix-class |
022e0893 |
235 | |
84e3c114 |
236 | Scott McWhirter (konobi) |
ba606e58 |
237 | |
84e3c114 |
238 | Scotty Allen <scotty@scottyallen.com> |
181a28f4 |
239 | |
84e3c114 |
240 | Todd Lipcon |
e063fe2c |
241 | |
84e3c114 |
242 | Will Hawes |
c0e7b4e5 |
243 | |
34d52be2 |
244 | =head1 LICENSE |
245 | |
246 | You may distribute this code under the same terms as Perl itself. |
247 | |
248 | =cut |
249 | |