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