lib/DBIx/Class.pm

   1 package DBIx::Class;
   2
   3 use strict;
   4 use warnings;
   5
   6 use MRO::Compat;
   7
   8 use vars qw($VERSION);
   9 use base qw/Class::C3::Componentised Class::Accessor::Grouped/;
  10 use DBIx::Class::StartupCheck;
  11
  12 sub mk_classdata {
  13   shift->mk_classaccessor(@_);
  14 }
  15
  16 sub mk_classaccessor {
  17   my $self = shift;
  18   $self->mk_group_accessors('inherited', $_[0]);
  19   $self->set_inherited(@_) if @_ > 1;
  20 }
  21
  22 sub component_base_class { 'DBIx::Class' }
  23
  24 # Always remember to do all digits for the version even if they're 0
  25 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
  26 # brain damage and presumably various other packaging systems too
  27 $VERSION = '0.08115';
  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 GETTING HELP/SUPPORT
  53
  54 The community can be found via:
  55
  56   Mailing list: http://lists.scsys.co.uk/mailman/listinfo/dbix-class/
  57
  58   SVN: http://dev.catalyst.perl.org/repos/bast/DBIx-Class/
  59
  60   SVNWeb: http://dev.catalyst.perl.org/svnweb/bast/browse/DBIx-Class/
  61
  62   IRC: irc.perl.org#dbix-class
  63
  64 =head1 SYNOPSIS
  65
  66 Create a schema class called MyDB/Schema.pm:
  67
  68   package MyDB::Schema;
  69   use base qw/DBIx::Class::Schema/;
  70
  71   __PACKAGE__->load_namespaces();
  72
  73   1;
  74
  75 Create a result class to represent artists, who have many CDs, in
  76 MyDB/Schema/Result/Artist.pm:
  77
  78 See L<DBIx::Class::ResultSource> for docs on defining result classes.
  79
  80   package MyDB::Schema::Result::Artist;
  81   use base qw/DBIx::Class::Core/;
  82
  83   __PACKAGE__->table('artist');
  84   __PACKAGE__->add_columns(qw/ artistid name /);
  85   __PACKAGE__->set_primary_key('artistid');
  86   __PACKAGE__->has_many(cds => 'MyDB::Schema::Result::CD');
  87
  88   1;
  89
  90 A result class to represent a CD, which belongs to an artist, in
  91 MyDB/Schema/Result/CD.pm:
  92
  93   package MyDB::Schema::Result::CD;
  94   use base qw/DBIx::Class::Core/;
  95
  96   __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
  97   __PACKAGE__->table('cd');
  98   __PACKAGE__->add_columns(qw/ cdid artistid title year /);
  99   __PACKAGE__->set_primary_key('cdid');
 100   __PACKAGE__->belongs_to(artist => 'MyDB::Schema::Artist', 'artistid');
 101
 102   1;
 103
 104 Then you can use these classes in your application's code:
 105
 106   # Connect to your database.
 107   use MyDB::Schema;
 108   my $schema = MyDB::Schema->connect($dbi_dsn, $user, $pass, \%dbi_params);
 109
 110   # Query for all artists and put them in an array,
 111   # or retrieve them as a result set object.
 112   # $schema->resultset returns a DBIx::Class::ResultSet
 113   my @all_artists = $schema->resultset('Artist')->all;
 114   my $all_artists_rs = $schema->resultset('Artist');
 115
 116   # Output all artists names
 117   # $artist here is a DBIx::Class::Row, which has accessors
 118   # for all its columns. Rows are also subclasses of your Result class.
 119   foreach $artist (@all_artists) {
 120     print $artist->name, "\n";
 121   }
 122
 123   # Create a result set to search for artists.
 124   # This does not query the DB.
 125   my $johns_rs = $schema->resultset('Artist')->search(
 126     # Build your WHERE using an SQL::Abstract structure:
 127     { name => { like => 'John%' } }
 128   );
 129
 130   # Execute a joined query to get the cds.
 131   my @all_john_cds = $johns_rs->search_related('cds')->all;
 132
 133   # Fetch the next available row.
 134   my $first_john = $johns_rs->next;
 135
 136   # Specify ORDER BY on the query.
 137   my $first_john_cds_by_title_rs = $first_john->cds(
 138     undef,
 139     { order_by => 'title' }
 140   );
 141
 142   # Create a result set that will fetch the artist data
 143   # at the same time as it fetches CDs, using only one query.
 144   my $millennium_cds_rs = $schema->resultset('CD')->search(
 145     { year => 2000 },
 146     { prefetch => 'artist' }
 147   );
 148
 149   my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
 150   my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
 151
 152   # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
 153   # create() is the same as new() then insert().
 154   my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
 155   $new_cd->artist($cd->artist);
 156   $new_cd->insert; # Auto-increment primary key filled in after INSERT
 157   $new_cd->title('Fork');
 158
 159   $schema->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
 160
 161   # change the year of all the millennium CDs at once
 162   $millennium_cds_rs->update({ year => 2002 });
 163
 164 =head1 DESCRIPTION
 165
 166 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
 167 (with a compatibility layer as a springboard for porting) and a resultset API
 168 that allows abstract encapsulation of database operations. It aims to make
 169 representing queries in your code as perl-ish as possible while still
 170 providing access to as many of the capabilities of the database as possible,
 171 including retrieving related records from multiple tables in a single query,
 172 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
 173
 174 DBIx::Class can handle multi-column primary and foreign keys, complex
 175 queries and database-level paging, and does its best to only query the
 176 database in order to return something you've directly asked for. If a
 177 resultset is used as an iterator it only fetches rows off the statement
 178 handle as requested in order to minimise memory usage. It has auto-increment
 179 support for SQLite, MySQL, PostgreSQL, Oracle, SQL Server and DB2 and is
 180 known to be used in production on at least the first four, and is fork-
 181 and thread-safe out of the box (although your DBD may not be).
 182
 183 This project is still under rapid development, so large new features may be
 184 marked EXPERIMENTAL - such APIs are still usable but may have edge bugs.
 185 Failing test cases are *always* welcome and point releases are put out rapidly
 186 as bugs are found and fixed.
 187
 188 We do our best to maintain full backwards compatibility for published
 189 APIs, since DBIx::Class is used in production in many organisations,
 190 and even backwards incompatible changes to non-published APIs will be fixed
 191 if they're reported and doing so doesn't cost the codebase anything.
 192
 193 The test suite is quite substantial, and several developer releases
 194 are generally made to CPAN before the branch for the next release is
 195 merged back to trunk for a major release.
 196
 197 =head1 WHERE TO GO NEXT
 198
 199 L<DBIx::Class::Manual::DocMap> lists each task you might want help on, and
 200 the modules where you will find documentation.
 201
 202 =head1 AUTHOR
 203
 204 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
 205
 206 (I mostly consider myself "project founder" these days but the AUTHOR heading
 207 is traditional :)
 208
 209 =head1 CONTRIBUTORS
 210
 211 abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
 212
 213 aherzog: Adam Herzog <adam@herzogdesigns.com>
 214
 215 andyg: Andy Grundman <andy@hybridized.org>
 216
 217 ank: Andres Kievsky
 218
 219 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
 220
 221 ash: Ash Berlin <ash@cpan.org>
 222
 223 bert: Norbert Csongradi <bert@cpan.org>
 224
 225 blblack: Brandon L. Black <blblack@gmail.com>
 226
 227 bluefeet: Aran Deltac <bluefeet@cpan.org>
 228
 229 bricas: Brian Cassidy <bricas@cpan.org>
 230
 231 brunov: Bruno Vecchi <vecchi.b@gmail.com>
 232
 233 caelum: Rafael Kitover <rkitover@cpan.org>
 234
 235 castaway: Jess Robinson
 236
 237 claco: Christopher H. Laco
 238
 239 clkao: CL Kao
 240
 241 da5id: David Jack Olrik <djo@cpan.org>
 242
 243 debolaz: Anders Nor Berle <berle@cpan.org>
 244
 245 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
 246
 247 dnm: Justin Wheeler <jwheeler@datademons.com>
 248
 249 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
 250
 251 dyfrgi: Michael Leuchtenburg <michael@slashhome.org>
 252
 253 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
 254
 255 gphat: Cory G Watson <gphat@cpan.org>
 256
 257 groditi: Guillermo Roditi <groditi@cpan.org>
 258
 259 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
 260
 261 jasonmay: Jason May <jason.a.may@gmail.com>
 262
 263 jesper: Jesper Krogh
 264
 265 jgoulah: John Goulah <jgoulah@cpan.org>
 266
 267 jguenther: Justin Guenther <jguenther@cpan.org>
 268
 269 jnapiorkowski: John Napiorkowski <jjn1056@yahoo.com>
 270
 271 jon: Jon Schutz <jjschutz@cpan.org>
 272
 273 jshirley: J. Shirley <jshirley@gmail.com>
 274
 275 konobi: Scott McWhirter
 276
 277 lukes: Luke Saunders <luke.saunders@gmail.com>
 278
 279 marcus: Marcus Ramberg <mramberg@cpan.org>
 280
 281 mattlaw: Matt Lawrence
 282
 283 michaelr: Michael Reddick <michael.reddick@gmail.com>
 284
 285 ned: Neil de Carteret
 286
 287 nigel: Nigel Metheringham <nigelm@cpan.org>
 288
 289 ningu: David Kamholz <dkamholz@cpan.org>
 290
 291 Nniuq: Ron "Quinn" Straight" <quinnfazigu@gmail.org>
 292
 293 norbi: Norbert Buchmuller <norbi@nix.hu>
 294
 295 Numa: Dan Sully <daniel@cpan.org>
 296
 297 ovid: Curtis "Ovid" Poe <ovid@cpan.org>
 298
 299 oyse: Øystein Torget <oystein.torget@dnv.com>
 300
 301 paulm: Paul Makepeace
 302
 303 penguin: K J Cheetham
 304
 305 perigrin: Chris Prather <chris@prather.org>
 306
 307 peter: Peter Collingbourne <peter@pcc.me.uk>
 308
 309 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
 310
 311 plu: Johannes Plunien <plu@cpan.org>
 312
 313 quicksilver: Jules Bean
 314
 315 rafl: Florian Ragwitz <rafl@debian.org>
 316
 317 rbuels: Robert Buels <rmb32@cornell.edu>
 318
 319 rdj: Ryan D Johnson <ryan@innerfence.com>
 320
 321 ribasushi: Peter Rabbitson <rabbit+dbic@rabbit.us>
 322
 323 rjbs: Ricardo Signes <rjbs@cpan.org>
 324
 325 robkinyon: Rob Kinyon <rkinyon@cpan.org>
 326
 327 sc_: Just Another Perl Hacker
 328
 329 scotty: Scotty Allen <scotty@scottyallen.com>
 330
 331 semifor: Marc Mims <marc@questright.com>
 332
 333 solomon: Jared Johnson <jaredj@nmgi.com>
 334
 335 spb: Stephen Bennett <stephen@freenode.net>
 336
 337 sszabo: Stephan Szabo <sszabo@bigpanda.com>
 338
 339 teejay : Aaron Trevena <teejay@cpan.org>
 340
 341 Todd Lipcon
 342
 343 Tom Hukins
 344
 345 triode: Pete Gamache <gamache@cpan.org>
 346
 347 typester: Daisuke Murase <typester@cpan.org>
 348
 349 victori: Victor Igumnov <victori@cpan.org>
 350
 351 wdh: Will Hawes
 352
 353 willert: Sebastian Willert <willert@cpan.org>
 354
 355 wreis: Wallace Reis <wreis@cpan.org>
 356
 357 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
 358
 359 =head1 COPYRIGHT
 360
 361 Copyright (c) 2005 - 2009 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
 362 as listed above.
 363
 364 =head1 LICENSE
 365
 366 This library is free software and may be distributed under the same terms
 367 as perl itself.
 368
 369 =cut