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 to represent artists, who have many CDs, in DB/Main/Artist.pm:
  51
  52   package DB::Main::Artist;
  53   use base qw/DBIx::Class/;
  54
  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');
  60
  61   1;
  62
  63 A class to represent a CD, which belongs to an artist, in DB/Main/CD.pm:
  64
  65   package DB::Main::CD;
  66   use base qw/DBIx::Class/;
  67
  68   __PACKAGE__->load_components(qw/PK::Auto Core/);
  69   __PACKAGE__->table('cd');
  70   __PACKAGE__->add_columns(qw/ cdid artist title year/);
  71   __PACKAGE__->set_primary_key('cdid');
  72   __PACKAGE__->belongs_to('artist' => 'DB::Main::Artist');
  73
  74   1;
  75
  76 Then you can use these classes in your application's code:
  77
  78   # Connect to your database.
  79   my $ds = DB::Main->connect(@dbi_dsn);
  80
  81   # Query for all artists and put them in an array,
  82   # or retrieve them as a result set object.
  83   my @all_artists = $ds->resultset('Artist')->all;
  84   my $all_artists_rs = $ds->resultset('Artist');
  85
  86   # Create a result set to search for artists.
  87   # This does not query the DB.
  88   my $johns_rs = $ds->resultset('Artist')->search(
  89     # Build your WHERE using an SQL::Abstract structure:
  90     { 'name' => { 'like', 'John%' } }
  91   );
  92
  93   # This executes a joined query to get the cds
  94   my @all_john_cds = $johns_rs->search_related('cds')->all;
  95
  96   # Queries but only fetches one row so far.
  97   my $first_john = $johns_rs->next;
  98
  99   my $first_john_cds_by_title_rs = $first_john->cds(
 100     undef,
 101     { order_by => 'title' }
 102   );
 103
 104   my $millennium_cds_rs = $ds->resultset('CD')->search(
 105     { year => 2000 },
 106     { prefetch => 'artist' }
 107   );
 108
 109   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
 110   my $cd_artist_name = $cd->artist->name; # Already has the data so no query
 111
 112   my $new_cd = $ds->resultset('CD')->new({ title => 'Spoon' });
 113   $new_cd->artist($cd->artist);
 114   $new_cd->insert; # Auto-increment primary key filled in after INSERT
 115   $new_cd->title('Fork');
 116
 117   $ds->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
 118
 119   $millennium_cds_rs->update({ year => 2002 }); # Single-query bulk update
 120
 121 =head1 DESCRIPTION
 122
 123 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
 124 (and a compatibility layer as a springboard for porting) and a resultset API
 125 that allows abstract encapsulation of database operations. It aims to make
 126 representing queries in your code as perl-ish as possible while still
 127 providing access to as many of the capabilities of the database as possible,
 128 including retrieving related records from multiple tables in a single query,
 129 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support.
 130
 131 DBIx::Class can handle multi-column primary and foreign keys, complex
 132 queries and database-level paging, and does its best to only query the
 133 database when it actually needs to in order to return something you've directly
 134 asked for. If a resultset is used as an iterator it only fetches rows off
 135 the statement handle as requested in order to minimise memory usage. It
 136 has auto-increment support for SQLite, MySQL, PostgreSQL, Oracle, SQL
 137 Server and DB2 and is known to be used in production on at least the first
 138 four, and is fork- and thread-safe out of the box (although your DBD may not
 139 be).
 140
 141 This project is still under rapid development, so features added in the
 142 latest major release may not work 100% yet - check the Changes if you run
 143 into trouble, and beware of anything explicitly marked EXPERIMENTAL. Failing
 144 test cases are *always* welcome and point releases are put out rapidly as
 145 bugs are found and fixed.
 146
 147 Even so, we do our best to maintain full backwards compatibility for published
 148 APIs since DBIx::Class is used in production in a number of organisations;
 149 the test suite is now fairly substantial and several developer releases are
 150 generally made to CPAN before the -current branch is merged back to trunk for
 151 a major release.
 152
 153 The community can be found via -
 154
 155   Mailing list: http://lists.rawmode.org/mailman/listinfo/dbix-class/
 156
 157   SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/
 158
 159   Wiki: http://dbix-class.shadowcatsystems.co.uk/
 160
 161   IRC: irc.perl.org#dbix-class
 162
 163 =head1 WHERE TO GO NEXT
 164
 165 =over 4
 166
 167 =item L<DBIx::Class::Manual> - user's manual
 168
 169 =item L<DBIx::Class::Core> - DBIC Core Classes
 170
 171 =item L<DBIx::Class::CDBICompat> - L<Class::DBI> Compat layer
 172
 173 =item L<DBIx::Class::Schema> - schema and connection container
 174
 175 =item L<DBIx::Class::ResultSource> - tables and table-like things
 176
 177 =item L<DBIx::Class::ResultSet> - encapsulates a query and its results
 178
 179 =item L<DBIx::Class::Row> - row-level methods
 180
 181 =item L<DBIx::Class::PK> - primary key methods
 182
 183 =item L<DBIx::Class::Relationship> - relationships between tables
 184
 185 =back
 186
 187 =head1 AUTHOR
 188
 189 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
 190
 191 =head1 CONTRIBUTORS
 192
 193 abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
 194
 195 andyg: Andy Grundman <andy@hybridized.org>
 196
 197 ank: Andres Kievsky
 198
 199 blblack: Brandon Black
 200
 201 LTJake: Brian Cassidy <bricas@cpan.org>
 202
 203 claco: Christopher H. Laco
 204
 205 clkao: CL Kao
 206
 207 typester: Daisuke Murase <typester@cpan.org>
 208
 209 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
 210
 211 Numa: Dan Sully <daniel@cpan.org>
 212
 213 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
 214
 215 ningu: David Kamholz <dkamholz@cpan.org>
 216
 217 jesper: Jesper Krogh
 218
 219 castaway: Jess Robinson
 220
 221 quicksilver: Jules Bean
 222
 223 jguenther: Justin Guenther <guentherj@agr.gc.ca>
 224
 225 draven: Marcus Ramberg <mramberg@cpan.org>
 226
 227 nigel: Nigel Metheringham <nigelm@cpan.org>
 228
 229 paulm: Paul Makepeace
 230
 231 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
 232
 233 sc_: Just Another Perl Hacker
 234
 235 konobi: Scott McWhirter
 236
 237 scotty: Scotty Allen <scotty@scottyallen.com>
 238
 239 Todd Lipcon
 240
 241 wdh: Will Hawes
 242
 243 =head1 LICENSE
 244
 245 You may distribute this code under the same terms as Perl itself.
 246
 247 =cut
 248