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.08007';
  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 blblack: Brandon L. Black <blblack@gmail.com>
 206
 207 bluefeet: Aran Deltac <bluefeet@cpan.org>
 208
 209 captainL: Luke Saunders <luke.saunders@gmail.com>
 210
 211 castaway: Jess Robinson
 212
 213 claco: Christopher H. Laco
 214
 215 clkao: CL Kao
 216
 217 da5id: David Jack Olrik <djo@cpan.org>
 218
 219 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
 220
 221 dnm: Justin Wheeler <jwheeler@datademons.com>
 222
 223 draven: Marcus Ramberg <mramberg@cpan.org>
 224
 225 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
 226
 227 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
 228
 229 gphat: Cory G Watson <gphat@cpan.org>
 230
 231 jesper: Jesper Krogh
 232
 233 jguenther: Justin Guenther <jguenther@cpan.org>
 234
 235 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
 236
 237 jon: Jon Schutz <jjschutz@cpan.org>
 238
 239 jshirley: J. Shirley <jshirley@gmail.com>
 240
 241 konobi: Scott McWhirter
 242
 243 LTJake: Brian Cassidy <bricas@cpan.org>
 244
 245 mattlaw: Matt Lawrence
 246
 247 ned: Neil de Carteret
 248
 249 nigel: Nigel Metheringham <nigelm@cpan.org>
 250
 251 ningu: David Kamholz <dkamholz@cpan.org>
 252
 253 Numa: Dan Sully <daniel@cpan.org>
 254
 255 paulm: Paul Makepeace
 256
 257 penguin: K J Cheetham
 258
 259 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
 260
 261 quicksilver: Jules Bean
 262
 263 sc_: Just Another Perl Hacker
 264
 265 scotty: Scotty Allen <scotty@scottyallen.com>
 266
 267 semifor: Marc Mims <marc@questright.com>
 268
 269 sszabo: Stephan Szabo <sszabo@bigpanda.com>
 270
 271 Todd Lipcon
 272
 273 Tom Hukins
 274
 275 typester: Daisuke Murase <typester@cpan.org>
 276
 277 victori: Victor Igumnov <victori@cpan.org>
 278
 279 wdh: Will Hawes
 280
 281 willert: Sebastian Willert <willert@cpan.org>
 282
 283 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
 284
 285 =head1 LICENSE
 286
 287 You may distribute this code under the same terms as Perl itself.
 288
 289 =cut