7 use base qw/DBIx::Class::Componentised Class::Data::Accessor/;
9 sub mk_classdata { shift->mk_classaccessor(@_); }
10 sub component_base_class { 'DBIx::Class' }
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
16 $VERSION = '0.05999_04';
18 sub MODIFY_CODE_ATTRIBUTES {
19 my ($class,$code,@attrs) = @_;
20 $class->mk_classdata('__attr_cache' => {}) unless $class->can('__attr_cache');
21 $class->__attr_cache->{$code} = [@attrs];
27 my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
28 my $rest = eval { $self->next::method };
29 return $@ ? $cache : { %$cache, %$rest };
36 DBIx::Class - Extensible and flexible object <-> relational mapper.
40 Create a base schema class called DB/Main.pm:
43 use base qw/DBIx::Class::Schema/;
45 __PACKAGE__->load_classes();
49 Create a class the represent artists, who have many
50 CDs, in DB/Main/Artist.pm:
52 package DB::Main::Artist;
53 use base qw/DBIx::Class/;
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');
59 __PACKAGE__->has_many('cds' => 'DB::Main::CD');
63 A class to represent a CD, which belongs to an
64 artist, in DB/Main/CD.pm:
67 use base qw/DBIx::Class/;
69 __PACKAGE__->load_components(qw/PK::Auto Core/);
70 __PACKAGE__->table('cd');
71 __PACKAGE__->add_columns(qw/ cdid artist title year/);
72 __PACKAGE__->set_primary_key('cdid');
73 __PACKAGE__->belongs_to('artist' => 'DB::Main::Artist');
77 Then you can use these classes in your application's code:
79 # Connect to your database.
80 my $ds = DB::Main->connect(@dbi_dsn);
82 # Query for all artists and put them in an array,
83 # or retrieve them as a result set object.
84 my @all_artists = $ds->resultset('Artist')->all;
85 my $all_artists_rs = $ds->resultset('Artist');
87 # Create a result set to search for artists.
88 # This does not query the DB, yet.
89 my $johns_rs = $ds->resultset('Artist')->search(
90 # Build your WHERE using an SQL::Abstract structure:
91 { 'name' => { 'like', 'John%' } }
94 # Now the query is executed.
95 my @all_john_cds = $johns_rs->search_related('cds')->all;
97 # Queries but only fetches one row so far.
98 my $first_john = $johns_rs->next;
100 my $first_john_cds_by_title_rs = $first_john->cds(
102 { order_by => 'title' }
105 my $millenium_cds_rs = $ds->resultset('CD')->search(
107 { prefetch => 'artist' }
110 my $cd = $millenium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
111 my $cd_artist_name = $cd->artist->name; # Already has the data so no query
113 my $new_cd = $ds->resultset('CD')->new({ title => 'Spoon' });
114 $new_cd->artist($cd->artist);
115 $new_cd->insert; # Auto-increment primary key filled in after INSERT
116 $new_cd->title('Fork');
118 $ds->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
120 $millenium_cds_rs->update({ year => 2002 }); # Single-query bulk update
124 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
125 (and a compatibility layer as a springboard for porting) and a resultset API
126 that allows abstract encapsulation of database operations. It aims to make
127 representing queries in your code as perl-ish as possible while still
128 providing access to as many of the capabilities of the database as possible,
129 including retrieving related records from multiple tables in a single query,
130 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support.
132 DBIx::Class can handle multi-column primary and foreign keys, complex
133 queries and database-level paging, and does its best to only query the
134 database when it actually needs to in order to return something the user's
135 asked for. If a resultset is used as an iterator it only fetches rows off
136 the statement handle as requested in order to minimise memory usage. It
137 has auto-increment support for SQLite, MySQL, PostgreSQL, Oracle, SQL
138 Server and DB2 and is known to be used in production on at least the first
139 four, and is fork- and thread-safe out of the box (although your DBD may not
142 This project is still under rapid development, so features added in the
143 latest major release may not work 100% yet - check the Changes if you run
144 into trouble, and beware of anything explicitly marked EXPERIMENTAL. Failing
145 test cases are *always* welcome and point releases are put out rapidly as
146 bugs are found and fixed.
148 Even so, we do your best to maintain full backwards compatibility for published
149 APIs since DBIx::Class is used in production in a number of organisations;
150 the test suite is now fairly substantial and several developer releases are
151 generally made to CPAN before the -current branch is merged back to trunk.
153 The community can be found via -
155 Mailing list: http://lists.rawmode.org/mailman/listinfo/dbix-class/
157 SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/
159 Wiki: http://dbix-class.shadowcatsystems.co.uk/
161 IRC: irc.perl.org#dbix-class
163 =head1 WHERE TO GO NEXT
167 =item L<DBIx::Class::Manual> - user's manual
169 =item L<DBIx::Class::Core> - DBIC Core Classes
171 =item L<DBIx::Class::CDBICompat> - L<Class::DBI> Compat layer
173 =item L<DBIx::Class::Schema> - schema and connection container
175 =item L<DBIx::Class::ResultSource> - tables and table-like things
177 =item L<DBIx::Class::ResultSet> - encapsulates a query and its results
179 =item L<DBIx::Class::Row> - row-level methods
181 =item L<DBIx::Class::PK> - primary key methods
183 =item L<DBIx::Class::Relationship> - relationships between tables
189 Matt S. Trout <mst@shadowcatsystems.co.uk>
193 Alexander Hartmaier <alex_hartmaier@hotmail.com>
195 Andy Grundman <andy@hybridized.org>
201 Brian Cassidy <bricas@cpan.org>
207 Daisuke Murase <typester@cpan.org>
209 Dan Kubb <dan.kubb-cpan@onautopilot.com>
211 Dan Sully <daniel@cpan.org>
213 Daniel Westermann-Clark <danieltwc@cpan.org>
215 David Kamholz <dkamholz@cpan.org>
223 Justin Guenther <guentherj@agr.gc.ca>
225 Marcus Ramberg <mramberg@cpan.org>
227 Nigel Metheringham <nigelm@cpan.org>
231 Robert Sedlacek <phaylon@dunkelheit.at>
233 sc_ of irc.perl.org#dbix-class
235 Scott McWhirter (konobi)
237 Scotty Allen <scotty@scottyallen.com>
245 You may distribute this code under the same terms as Perl itself.