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::Data::Accessor/;
   8
   9 sub mk_classdata { shift->mk_classaccessor(@_); }
  10 sub component_base_class { 'DBIx::Class' }
  11
  12 # Always remember to do all digits for the version even if they're 0
  13 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
  14 # brain damage and presumably various other packaging systems too
  15
  16 $VERSION = '0.05999_04';
  17
  18 sub MODIFY_CODE_ATTRIBUTES {
  19     my ($class,$code,@attrs) = @_;
  20     $class->mk_classdata('__attr_cache' => {}) unless $class->can('__attr_cache');
  21     $class->__attr_cache->{$code} = [@attrs];
  22     return ();
  23 }
  24
  25 sub _attr_cache {
  26     my $self = shift;
  27     my $cache = $self->can('__attr_cache') ? $self->__attr_cache : {};
  28     my $rest = eval { $self->next::method };
  29     return $@ ? $cache : { %$cache, %$rest };
  30 }
  31
  32 1;
  33
  34 =head1 NAME
  35
  36 DBIx::Class - Extensible and flexible object <-> relational mapper.
  37
  38 =head1 SYNOPSIS
  39
  40 Create a base schema class called DB/Main.pm:
  41
  42   package DB::Main;
  43   use base qw/DBIx::Class::Schema/;
  44
  45   __PACKAGE__->load_classes();
  46
  47   1;
  48
  49 Create a class the represent artists, who have many
  50 CDs, in DB/Main/Artist.pm:
  51
  52   package DB::Main::Artist;
  53   use base qw/DBIx::Class/;
  54
  55   __PACKAGE__->load_components(qw/PK::Auto Core/);
  56   __PACKAGE__->table('artist');
  57   __PACKAGE__->add_columns(qw/ artistid name /);
  58   __PACKAGE__->set_primary_key('artistid');
  59   __PACKAGE__->has_many('cds' => 'DB::Main::CD');
  60
  61   1;
  62
  63 A class to represent a CD, which belongs to an
  64 artist, in DB/Main/CD.pm:
  65
  66   package DB::Main::CD;
  67   use base qw/DBIx::Class/;
  68
  69   __PACKAGE__->load_components(qw/PK::Auto Core/);
  70   __PACKAGE__->table('cd');
  71   __PACKAGE__->add_columns(qw/ cdid artist title year/);
  72   __PACKAGE__->set_primary_key('cdid');
  73   __PACKAGE__->belongs_to('artist' => 'DB::Main::Artist');
  74
  75   1;
  76
  77 Then you can use these classes in your application's code:
  78
  79   # Connect to your database.
  80   my $ds = DB::Main->connect(@dbi_dsn);
  81
  82   # Query for all artists and put them in an array,
  83   # or retrieve them as a result set object.
  84   my @all_artists = $ds->resultset('Artist')->all;
  85   my $all_artists_rs = $ds->resultset('Artist');
  86
  87   # Create a result set to search for artists.
  88   # This does not query the DB, yet.
  89   my $johns_rs = $ds->resultset('Artist')->search(
  90     # Build your WHERE using an SQL::Abstract structure:
  91     { 'name' => { 'like', 'John%' } }
  92   );
  93
  94   # Now the query is executed.
  95   my @all_john_cds = $johns_rs->search_related('cds')->all;
  96
  97   # Queries but only fetches one row so far.
  98   my $first_john = $johns_rs->next;
  99
 100   my $first_john_cds_by_title_rs = $first_john->cds(
 101     undef,
 102     { order_by => 'title' }
 103   );
 104
 105   my $millenium_cds_rs = $ds->resultset('CD')->search(
 106     { year => 2000 },
 107     { prefetch => 'artist' }
 108   );
 109
 110   my $cd = $millenium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
 111   my $cd_artist_name = $cd->artist->name; # Already has the data so no query
 112
 113   my $new_cd = $ds->resultset('CD')->new({ title => 'Spoon' });
 114   $new_cd->artist($cd->artist);
 115   $new_cd->insert; # Auto-increment primary key filled in after INSERT
 116   $new_cd->title('Fork');
 117
 118   $ds->txn_do(sub { $new_cd->update }); # Runs the update in a transaction
 119
 120   $millenium_cds_rs->update({ year => 2002 }); # Single-query bulk update
 121
 122 =head1 DESCRIPTION
 123
 124 This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
 125 (and a compatibility layer as a springboard for porting) and a resultset API
 126 that allows abstract encapsulation of database operations. It aims to make
 127 representing queries in your code as perl-ish as possible while still
 128 providing access to as many of the capabilities of the database as possible,
 129 including retrieving related records from multiple tables in a single query,
 130 JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY and HAVING support.
 131
 132 DBIx::Class can handle multi-column primary and foreign keys, complex
 133 queries and database-level paging, and does its best to only query the
 134 database when it actually needs to in order to return something the user's
 135 asked for. If a resultset is used as an iterator it only fetches rows off
 136 the statement handle as requested in order to minimise memory usage. It
 137 has auto-increment support for SQLite, MySQL, PostgreSQL, Oracle, SQL
 138 Server and DB2 and is known to be used in production on at least the first
 139 four, and is fork- and thread-safe out of the box (although your DBD may not
 140 be).
 141
 142 This project is still under rapid development, so features added in the
 143 latest major release may not work 100% yet - check the Changes if you run
 144 into trouble, and beware of anything explicitly marked EXPERIMENTAL. Failing
 145 test cases are *always* welcome and point releases are put out rapidly as
 146 bugs are found and fixed.
 147
 148 Even so, we do your best to maintain full backwards compatibility for published
 149 APIs since DBIx::Class is used in production in a number of organisations;
 150 the test suite is now fairly substantial and several developer releases are
 151 generally made to CPAN before the -current branch is merged back to trunk.
 152
 153 The community can be found via -
 154
 155   Mailing list: http://lists.rawmode.org/mailman/listinfo/dbix-class/
 156
 157   SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/
 158
 159   Wiki: http://dbix-class.shadowcatsystems.co.uk/
 160
 161   IRC: irc.perl.org#dbix-class
 162
 163 =head1 WHERE TO GO NEXT
 164
 165 =over 4
 166
 167 =item L<DBIx::Class::Manual> - user's manual
 168
 169 =item L<DBIx::Class::Core> - DBIC Core Classes
 170
 171 =item L<DBIx::Class::CDBICompat> - L<Class::DBI> Compat layer
 172
 173 =item L<DBIx::Class::Schema> - schema and connection container
 174
 175 =item L<DBIx::Class::ResultSource> - tables and table-like things
 176
 177 =item L<DBIx::Class::ResultSet> - encapsulates a query and its results
 178
 179 =item L<DBIx::Class::Row> - row-level methods
 180
 181 =item L<DBIx::Class::PK> - primary key methods
 182
 183 =item L<DBIx::Class::Relationship> - relationships between tables
 184
 185 =back
 186
 187 =head1 AUTHOR
 188
 189 Matt S. Trout <mst@shadowcatsystems.co.uk>
 190
 191 =head1 CONTRIBUTORS
 192
 193 Alexander Hartmaier <alex_hartmaier@hotmail.com>
 194
 195 Andy Grundman <andy@hybridized.org>
 196
 197 Andres Kievsky
 198
 199 Brandon Black
 200
 201 Brian Cassidy <bricas@cpan.org>
 202
 203 Christopher H. Laco
 204
 205 CL Kao
 206
 207 Daisuke Murase <typester@cpan.org>
 208
 209 Dan Kubb <dan.kubb-cpan@onautopilot.com>
 210
 211 Dan Sully <daniel@cpan.org>
 212
 213 Daniel Westermann-Clark <danieltwc@cpan.org>
 214
 215 David Kamholz <dkamholz@cpan.org>
 216
 217 Jesper Krogh
 218
 219 Jess Robinson
 220
 221 Jules Bean
 222
 223 Justin Guenther <guentherj@agr.gc.ca>
 224
 225 Marcus Ramberg <mramberg@cpan.org>
 226
 227 Nigel Metheringham <nigelm@cpan.org>
 228
 229 Paul Makepeace
 230
 231 Robert Sedlacek <phaylon@dunkelheit.at>
 232
 233 sc_ of irc.perl.org#dbix-class
 234
 235 Scott McWhirter (konobi)
 236
 237 Scotty Allen <scotty@scottyallen.com>
 238
 239 Todd Lipcon
 240
 241 Will Hawes
 242
 243 =head1 LICENSE
 244
 245 You may distribute this code under the same terms as Perl itself.
 246
 247 =cut
 248