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