Normalize _parse_rs_attrs - no functional changes
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class.pm
CommitLineData
ea2e61bf 1package DBIx::Class;
2
5d283305 3use strict;
4use warnings;
5
f9cc85ce 6our $VERSION;
7# Always remember to do all digits for the version even if they're 0
8# i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
9# brain damage and presumably various other packaging systems too
10
11# $VERSION declaration must stay up here, ahead of any other package
12# declarations, as to not confuse various modules attempting to determine
13# this ones version, whether that be s.c.o. or Module::Metadata, etc
c6b73be9 14$VERSION = '0.082899_15';
f9cc85ce 15
16$VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
17
37873f78 18use DBIx::Class::_Util;
d38cd95c 19use mro 'c3';
329d7385 20
2527233b 21use DBIx::Class::Optional::Dependencies;
22
db29433c 23use base qw/DBIx::Class::Componentised DBIx::Class::AccessorGroup/;
11736b4c 24use DBIx::Class::StartupCheck;
f9080e45 25use DBIx::Class::Exception;
3e110410 26
70c28808 27__PACKAGE__->mk_group_accessors(inherited => '_skip_namespace_frames');
8b60b921 28__PACKAGE__->_skip_namespace_frames('^DBIx::Class|^SQL::Abstract|^Try::Tiny|^Class::Accessor::Grouped|^Context::Preserve|^Moose::Meta::');
70c28808 29
e1d9e578 30# FIXME - this is not really necessary, and is in
31# fact going to slow things down a bit
32# However it is the right thing to do in order to get
33# various install bases to highlight their brokenness
34# Remove at some unknown point in the future
35sub DESTROY { &DBIx::Class::_Util::detected_reinvoked_destructor }
36
ade0fe3b 37sub mk_classdata {
77d518d1 38 shift->mk_classaccessor(@_);
39}
40
41sub mk_classaccessor {
42 my $self = shift;
ade0fe3b 43 $self->mk_group_accessors('inherited', $_[0]);
77d518d1 44 $self->set_inherited(@_) if @_ > 1;
3e110410 45}
3c0068c1 46
7411204b 47sub component_base_class { 'DBIx::Class' }
227d4dee 48
f0750722 49sub MODIFY_CODE_ATTRIBUTES {
b5d2c57f 50 my ($class,$code,@attrs) = @_;
51 $class->mk_classdata('__attr_cache' => {})
52 unless $class->can('__attr_cache');
53 $class->__attr_cache->{$code} = [@attrs];
54 return ();
f0750722 55}
56
da95b45f 57sub _attr_cache {
b5d2c57f 58 my $self = shift;
59 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
9780718f 60
61 return {
62 %$cache,
63 %{ $self->maybe::next::method || {} },
20674fcd 64 };
da95b45f 65}
66
d095c62d 67# *DO NOT* change this URL nor the identically named =head1 below
68# it is linked throughout the ecosystem
69sub DBIx::Class::_ENV_::HELP_URL () {
70 'http://p3rl.org/DBIx::Class#GETTING_HELP/SUPPORT'
71}
72
ea2e61bf 731;
34d52be2 74
d095c62d 75__END__
76
75d07914 77=head1 NAME
34d52be2 78
7e4b2f59 79DBIx::Class - Extensible and flexible object <-> relational mapper.
34d52be2 80
06752a03 81=head1 WHERE TO START READING
3b1c2bbd 82
06752a03 83See L<DBIx::Class::Manual::DocMap> for an overview of the exhaustive documentation.
84To get the most out of DBIx::Class with the least confusion it is strongly
85recommended to read (at the very least) the
86L<Manuals|DBIx::Class::Manual::DocMap/Manuals> in the order presented there.
87
32250d01 88=cut
89
32250d01 90=head1 GETTING HELP/SUPPORT
06752a03 91
32250d01 92Due to the sheer size of its problem domain, DBIx::Class is a relatively
06752a03 93complex framework. After you start using DBIx::Class questions will inevitably
94arise. If you are stuck with a problem or have doubts about a particular
32250d01 95approach do not hesitate to contact us via any of the following options (the
96list is sorted by "fastest response time"):
3b1c2bbd 97
a06e1181 98=over
3b1c2bbd 99
c6fdaf2a 100=item * IRC: irc.perl.org#dbix-class
101
102=for html
e1ddfc8a 103<a href="https://chat.mibbit.com/#dbix-class@irc.perl.org">(click for instant chatroom login)</a>
3b1c2bbd 104
a06e1181 105=item * Mailing list: L<http://lists.scsys.co.uk/mailman/listinfo/dbix-class>
3b1c2bbd 106
e1ddfc8a 107=item * RT Bug Tracker: L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-Class>
86a23587 108
e1ddfc8a 109=item * Twitter: L<https://www.twitter.com/dbix_class>
86a23587 110
86a23587 111=item * Web Site: L<http://www.dbix-class.org/>
a06e1181 112
86a23587 113=back
114
34d52be2 115=head1 SYNOPSIS
116
113e8d16 117For the very impatient: L<DBIx::Class::Manual::QuickStart>
118
119This code in the next step can be generated automatically from an existing
120database, see L<dbicdump> from the distribution C<DBIx-Class-Schema-Loader>.
121
5b56d1ac 122=head2 Schema classes preparation
123
53aa53f3 124Create a schema class called F<MyApp/Schema.pm>:
34d52be2 125
03460bef 126 package MyApp::Schema;
a0638a7b 127 use base qw/DBIx::Class::Schema/;
34d52be2 128
f0bb26f3 129 __PACKAGE__->load_namespaces();
daec44b8 130
a0638a7b 131 1;
daec44b8 132
30e1753a 133Create a result class to represent artists, who have many CDs, in
53aa53f3 134F<MyApp/Schema/Result/Artist.pm>:
daec44b8 135
30e1753a 136See L<DBIx::Class::ResultSource> for docs on defining result classes.
137
03460bef 138 package MyApp::Schema::Result::Artist;
d88ecca6 139 use base qw/DBIx::Class::Core/;
daec44b8 140
a0638a7b 141 __PACKAGE__->table('artist');
142 __PACKAGE__->add_columns(qw/ artistid name /);
143 __PACKAGE__->set_primary_key('artistid');
326dacbf 144 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artistid');
daec44b8 145
a0638a7b 146 1;
daec44b8 147
30e1753a 148A result class to represent a CD, which belongs to an artist, in
53aa53f3 149F<MyApp/Schema/Result/CD.pm>:
39fe0e65 150
03460bef 151 package MyApp::Schema::Result::CD;
d88ecca6 152 use base qw/DBIx::Class::Core/;
39fe0e65 153
d88ecca6 154 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
a0638a7b 155 __PACKAGE__->table('cd');
bd077b47 156 __PACKAGE__->add_columns(qw/ cdid artistid title year /);
a0638a7b 157 __PACKAGE__->set_primary_key('cdid');
03460bef 158 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
39fe0e65 159
a0638a7b 160 1;
39fe0e65 161
5b56d1ac 162=head2 API usage
163
a0638a7b 164Then you can use these classes in your application's code:
39fe0e65 165
a0638a7b 166 # Connect to your database.
03460bef 167 use MyApp::Schema;
168 my $schema = MyApp::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
a0638a7b 169
170 # Query for all artists and put them in an array,
171 # or retrieve them as a result set object.
30e1753a 172 # $schema->resultset returns a DBIx::Class::ResultSet
2053ab2a 173 my @all_artists = $schema->resultset('Artist')->all;
174 my $all_artists_rs = $schema->resultset('Artist');
126042ee 175
30e1753a 176 # Output all artists names
4e8ffded 177 # $artist here is a DBIx::Class::Row, which has accessors
16ccb4fe 178 # for all its columns. Rows are also subclasses of your Result class.
85067746 179 foreach $artist (@all_artists) {
30e1753a 180 print $artist->name, "\n";
181 }
182
a0638a7b 183 # Create a result set to search for artists.
86beca1d 184 # This does not query the DB.
2053ab2a 185 my $johns_rs = $schema->resultset('Artist')->search(
6576ef54 186 # Build your WHERE using an SQL::Abstract structure:
2053ab2a 187 { name => { like => 'John%' } }
a0638a7b 188 );
39fe0e65 189
2053ab2a 190 # Execute a joined query to get the cds.
a0638a7b 191 my @all_john_cds = $johns_rs->search_related('cds')->all;
448c8424 192
f0bb26f3 193 # Fetch the next available row.
a0638a7b 194 my $first_john = $johns_rs->next;
448c8424 195
2053ab2a 196 # Specify ORDER BY on the query.
a0638a7b 197 my $first_john_cds_by_title_rs = $first_john->cds(
198 undef,
199 { order_by => 'title' }
200 );
448c8424 201
bd077b47 202 # Create a result set that will fetch the artist data
2053ab2a 203 # at the same time as it fetches CDs, using only one query.
884559b1 204 my $millennium_cds_rs = $schema->resultset('CD')->search(
a0638a7b 205 { year => 2000 },
206 { prefetch => 'artist' }
207 );
448c8424 208
880a1a0c 209 my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
bd077b47 210 my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
076652e8 211
fb13a49f 212 # new() makes a Result object but doesnt insert it into the DB.
264f1571 213 # create() is the same as new() then insert().
884559b1 214 my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
f183eccd 215 $new_cd->artist($cd->artist);
f183eccd 216 $new_cd->insert; # Auto-increment primary key filled in after INSERT
f183eccd 217 $new_cd->title('Fork');
218
884559b1 219 $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
f183eccd 220
bd077b47 221 # change the year of all the millennium CDs at once
222 $millennium_cds_rs->update({ year => 2002 });
f183eccd 223
224=head1 DESCRIPTION
225
226This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
bd077b47 227(with a compatibility layer as a springboard for porting) and a resultset API
f183eccd 228that allows abstract encapsulation of database operations. It aims to make
229representing queries in your code as perl-ish as possible while still
a0638a7b 230providing access to as many of the capabilities of the database as possible,
f183eccd 231including retrieving related records from multiple tables in a single query,
53aa53f3 232C<JOIN>, C<LEFT JOIN>, C<COUNT>, C<DISTINCT>, C<GROUP BY>, C<ORDER BY> and
233C<HAVING> support.
f183eccd 234
235DBIx::Class can handle multi-column primary and foreign keys, complex
236queries and database-level paging, and does its best to only query the
75d07914 237database in order to return something you've directly asked for. If a
238resultset is used as an iterator it only fetches rows off the statement
239handle as requested in order to minimise memory usage. It has auto-increment
2053ab2a 240support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
241known to be used in production on at least the first four, and is fork-
ec6415a9 242and thread-safe out of the box (although
9361b05d 243L<your DBD may not be|DBI/Threads and Thread Safety>).
f183eccd 244
dfccde48 245This project is still under rapid development, so large new features may be
53aa53f3 246marked B<experimental> - such APIs are still usable but may have edge bugs.
247Failing test cases are I<always> welcome and point releases are put out rapidly
dfccde48 248as bugs are found and fixed.
249
250We do our best to maintain full backwards compatibility for published
251APIs, since DBIx::Class is used in production in many organisations,
252and even backwards incompatible changes to non-published APIs will be fixed
253if they're reported and doing so doesn't cost the codebase anything.
254
264f1571 255The test suite is quite substantial, and several developer releases
256are generally made to CPAN before the branch for the next release is
257merged back to trunk for a major release.
f183eccd 258
6ed05cfd 259=head1 HOW TO CONTRIBUTE
260
261Contributions are always welcome, in all usable forms (we especially
262welcome documentation improvements). The delivery methods include git-
263or unified-diff formatted patches, GitHub pull requests, or plain bug
264reports either via RT or the Mailing list. Contributors are generally
cb32addc 265granted access to the official repository after their first several
266patches pass successful review. Don't hesitate to
267L<contact|/GETTING HELP/SUPPORT> either of the L</CAT HERDERS> with
268any further questions you may have.
6ed05cfd 269
270=for comment
271FIXME: Getty, frew and jnap need to get off their asses and finish the contrib section so we can link it here ;)
272
273This project is maintained in a git repository. The code and related tools are
274accessible at the following locations:
275
276=over
277
278=item * Official repo: L<git://git.shadowcat.co.uk/dbsrgits/DBIx-Class.git>
279
280=item * Official gitweb: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class.git>
281
282=item * GitHub mirror: L<https://github.com/dbsrgits/DBIx-Class>
283
284=item * Authorized committers: L<ssh://dbsrgits@git.shadowcat.co.uk/DBIx-Class.git>
285
286=item * Travis-CI log: L<https://travis-ci.org/dbsrgits/dbix-class/builds>
287
288=for html
289&#x21AA; Stable branch CI status: <img src="https://secure.travis-ci.org/dbsrgits/dbix-class.png?branch=master"></img>
290
291=back
292
3440100b 293=head1 AUTHORS
34d52be2 294
3440100b 295Even though a large portion of the source I<appears> to be written by just a
296handful of people, this library continues to remain a collaborative effort -
297perhaps one of the most successful such projects on L<CPAN|http://cpan.org>.
298It is important to remember that ideas do not always result in a direct code
299contribution, but deserve acknowledgement just the same. Time and time again
300the seemingly most insignificant questions and suggestions have been shown
301to catalyze monumental improvements in consistency, accuracy and performance.
34d52be2 302
3440100b 303=for comment this line is replaced with the author list at dist-building time
dfccde48 304
3440100b 305The canonical source of authors and their details is the F<AUTHORS> file at
306the root of this distribution (or repository). The canonical source of
307per-line authorship is the L<git repository|/HOW TO CONTRIBUTE> history
308itself.
f9139687 309
cb32addc 310=head1 CAT HERDERS
311
312The fine folks nudging the project in a particular direction:
313
314=over
315
f06eb015 316B<ribasushi>: Peter Rabbitson <ribasushi@cpan.org>
cb32addc 317(present day maintenance and controlled evolution)
318
f06eb015 319B<castaway>: Jess Robinson <castaway@desert-island.me.uk>
cb32addc 320(lions share of the reference documentation and manuals)
321
f06eb015 322B<mst>: Matt S Trout <mst@shadowcat.co.uk> (project founder -
cb32addc 323original idea, architecture and implementation)
324
325=back
326
a2bd3796 327=head1 COPYRIGHT AND LICENSE
b38e10bd 328
a2bd3796 329Copyright (c) 2005 by mst, castaway, ribasushi, and other DBIx::Class
330L</AUTHORS> as listed above and in F<AUTHORS>.
96154ef7 331
332This library is free software and may be distributed under the same terms
a2bd3796 333as perl5 itself. See F<LICENSE> for the complete licensing terms.