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