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