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