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