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 AUTHOR
 205
 206 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
 207
 208 (I mostly consider myself "project founder" these days but the AUTHOR heading
 209 is traditional :)
 210
 211 =head1 CONTRIBUTORS
 212
 213 abraxxa: Alexander Hartmaier <alex_hartmaier@hotmail.com>
 214
 215 aherzog: Adam Herzog <adam@herzogdesigns.com>
 216
 217 andyg: Andy Grundman <andy@hybridized.org>
 218
 219 ank: Andres Kievsky
 220
 221 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
 222
 223 ash: Ash Berlin <ash@cpan.org>
 224
 225 bert: Norbert Csongradi <bert@cpan.org>
 226
 227 blblack: Brandon L. Black <blblack@gmail.com>
 228
 229 bluefeet: Aran Deltac <bluefeet@cpan.org>
 230
 231 bricas: Brian Cassidy <bricas@cpan.org>
 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 oyse: Øystein Torget <oystein.torget@dnv.com>
 298
 299 paulm: Paul Makepeace
 300
 301 penguin: K J Cheetham
 302
 303 perigrin: Chris Prather <chris@prather.org>
 304
 305 peter: Peter Collingbourne <peter@pcc.me.uk>
 306
 307 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
 308
 309 plu: Johannes Plunien <plu@cpan.org>
 310
 311 quicksilver: Jules Bean
 312
 313 rafl: Florian Ragwitz <rafl@debian.org>
 314
 315 rbuels: Robert Buels <rmb32@cornell.edu>
 316
 317 rdj: Ryan D Johnson <ryan@innerfence.com>
 318
 319 ribasushi: Peter Rabbitson <rabbit+dbic@rabbit.us>
 320
 321 rjbs: Ricardo Signes <rjbs@cpan.org>
 322
 323 robkinyon: Rob Kinyon <rkinyon@cpan.org>
 324
 325 sc_: Just Another Perl Hacker
 326
 327 scotty: Scotty Allen <scotty@scottyallen.com>
 328
 329 semifor: Marc Mims <marc@questright.com>
 330
 331 solomon: Jared Johnson <jaredj@nmgi.com>
 332
 333 sszabo: Stephan Szabo <sszabo@bigpanda.com>
 334
 335 teejay : Aaron Trevena <teejay@cpan.org>
 336
 337 Todd Lipcon
 338
 339 Tom Hukins
 340
 341 typester: Daisuke Murase <typester@cpan.org>
 342
 343 victori: Victor Igumnov <victori@cpan.org>
 344
 345 wdh: Will Hawes
 346
 347 willert: Sebastian Willert <willert@cpan.org>
 348
 349 wreis: Wallace Reis <wreis@cpan.org>
 350
 351 zamolxes: Bogdan Lucaciu <bogdan@wiz.ro>
 352
 353 =head1 LICENSE
 354
 355 You may distribute this code under the same terms as Perl itself.
 356
 357 =cut