lib/DBIx/Class.pm

   1 package DBIx::Class;
   2
   3 use strict;
   4 use warnings;
   5
   6 use vars qw($VERSION);
   7 use base qw/DBIx::Class::Componentised Class::Data::Accessor/;
   8
   9 sub mk_classdata { shift->mk_classaccessor(@_); }
  10 sub component_base_class { 'DBIx::Class' }
  11
  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
  16 $VERSION = '0.05999_04';
  17
  18 sub MODIFY_CODE_ATTRIBUTES {
  19     my ($class,$code,@attrs) = @_;
  20     $class->mk_classdata('__attr_cache' => {})
  21       unless $class->can('__attr_cache');
  22     $class->__attr_cache->{$code} = [@attrs];
  23     return ();
  24 }
  25
  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
  33 1;
  34
  35 =head1 NAME
  36
  37 DBIx::Class - Extensible and flexible object <-> relational mapper.
  38
  39 =head1 SYNOPSIS
  40
  41 Create a base schema class called DB/Main.pm:
  42
  43   package DB::Main;
  44   use base qw/DBIx::Class::Schema/;
  45
  46   __PACKAGE__->load_classes();
  47
  48   1;
  49
  50 Create a class the represent artists, who have many
  51 CDs, in DB/Main/Artist.pm:
  52
  53   package DB::Main::Artist;
  54   use base qw/DBIx::Class/;
  55
  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');
  61
  62   1;
  63
  64 A class to represent a CD, which belongs to an
  65 artist, in DB/Main/CD.pm:
  66
  67   package DB::Main::CD;
  68   use base qw/DBIx::Class/;
  69
  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');
  75
  76   1;
  77
  78 Then you can use these classes in your application's code:
  79
  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.
  85   my @all_artists = $ds->resultset('Artist')->all;
  86   my $all_artists_rs = $ds->resultset('Artist');
  87
  88   # Create a result set to search for artists.
  89   # This does not query the DB, yet.
  90   my $johns_rs = $ds->resultset('Artist')->search(
  91     # Build your WHERE using an SQL::Abstract structure:
  92     { 'name' => { 'like', 'John%' } }
  93   );
  94
  95   # Now the query is executed.
  96   my @all_john_cds = $johns_rs->search_related('cds')->all;
  97
  98   # Queries but only fetches one row so far.
  99   my $first_john = $johns_rs->next;
 100
 101   my $first_john_cds_by_title_rs = $first_john->cds(
 102     undef,
 103     { order_by => 'title' }
 104   );
 105
 106   my $millenium_cds_rs = $ds->resultset('CD')->search(
 107     { year => 2000 },
 108     { prefetch => 'artist' }
 109   );
 110
 111   my $cd = $millenium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
 112   my $cd_artist_name = $cd->artist->name; # Already has the data so no query
 113
 114   my $new_cd = $ds->resultset('CD')->new({ title => 'Spoon' });
 115   $new_cd->artist($cd->artist);
 116   $new_cd->insert; # Auto-increment primary key filled in after INSERT
 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>
 126 (and a compatibility layer as a springboard for porting) and a resultset API
 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
 129 providing access to as many of the capabilities of the database as possible,
 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
 167
 168 =item L<DBIx::Class::Manual> - user's manual
 169
 170 =item L<DBIx::Class::Core> - DBIC Core Classes
 171
 172 =item L<DBIx::Class::CDBICompat> - L<Class::DBI> Compat layer
 173
 174 =item L<DBIx::Class::Schema> - schema and connection container
 175
 176 =item L<DBIx::Class::ResultSource> - tables and table-like things
 177
 178 =item L<DBIx::Class::ResultSet> - encapsulates a query and its results
 179
 180 =item L<DBIx::Class::Row> - row-level methods
 181
 182 =item L<DBIx::Class::PK> - primary key methods
 183
 184 =item L<DBIx::Class::Relationship> - relationships between tables
 185
 186 =back
 187
 188 =head1 AUTHOR
 189
 190 Matt S. Trout <mst@shadowcatsystems.co.uk>
 191
 192 =head1 CONTRIBUTORS
 193
 194 Alexander Hartmaier <alex_hartmaier@hotmail.com>
 195
 196 Andy Grundman <andy@hybridized.org>
 197
 198 Andres Kievsky
 199
 200 Brandon Black
 201
 202 Brian Cassidy <bricas@cpan.org>
 203
 204 Christopher H. Laco
 205
 206 CL Kao
 207
 208 Daisuke Murase <typester@cpan.org>
 209
 210 Dan Kubb <dan.kubb-cpan@onautopilot.com>
 211
 212 Dan Sully <daniel@cpan.org>
 213
 214 Daniel Westermann-Clark <danieltwc@cpan.org>
 215
 216 David Kamholz <dkamholz@cpan.org>
 217
 218 Jesper Krogh
 219
 220 Jess Robinson
 221
 222 Jules Bean
 223
 224 Justin Guenther <guentherj@agr.gc.ca>
 225
 226 Marcus Ramberg <mramberg@cpan.org>
 227
 228 Nigel Metheringham <nigelm@cpan.org>
 229
 230 Paul Makepeace
 231
 232 Robert Sedlacek <phaylon@dunkelheit.at>
 233
 234 sc_ of irc.perl.org#dbix-class
 235
 236 Scott McWhirter (konobi)
 237
 238 Scotty Allen <scotty@scottyallen.com>
 239
 240 Todd Lipcon
 241
 242 Will Hawes
 243
 244 =head1 LICENSE
 245
 246 You may distribute this code under the same terms as Perl itself.
 247
 248 =cut
 249