[Bast-commits] r8474 - DBIx-Class/0.08/branches/pod_fixes/lib/DBIx/Class/Manual

[ribasushi at dev.catalyst.perl.org]

Author: ribasushi
Date: 2010-01-30 12:11:18 +0000 (Sat, 30 Jan 2010)
New Revision: 8474

Modified:
   DBIx-Class/0.08/branches/pod_fixes/lib/DBIx/Class/Manual/Intro.pod
Log:
Draft PK explanation

Modified: DBIx-Class/0.08/branches/pod_fixes/lib/DBIx/Class/Manual/Intro.pod
===================================================================
--- DBIx-Class/0.08/branches/pod_fixes/lib/DBIx/Class/Manual/Intro.pod	2010-01-30 08:57:26 UTC (rev 8473)
+++ DBIx-Class/0.08/branches/pod_fixes/lib/DBIx/Class/Manual/Intro.pod	2010-01-30 12:11:18 UTC (rev 8474)
@@ -397,6 +397,40 @@
 
 =head1 NOTES
 
+=head2 The Significance and Importance of Primary Keys
+
+The concept of a L<primary key|DBIx::Class::ResultSource/set_primary_key> in
+DBIx::Class warrants special discussion. The formal definition (which somewhat
+resembles that of a classic RDBMS) is I<a unique constraint that is least
+likely to change after initial row creation>. However this is where the
+similarity ends. While in a RDBMS you can safely change any column within a
+row, you can not do the same in DBIC because B<you will be breaking the tie
+between a specific L<DBIx::Class::Row> object and a specific row in your
+database>. Any time you call a CRUD operation on a row (e.g.
+L<delete|DBIx::Class::Row/delete>,
+L<update|DBIx::Class::Row/update>,
+L<discard_changes|DBIx::Class::Row/discard_changes>,
+etc.) DBIx::Class will use the B<current values> of the
+L<primary key|DBIx::Class::ResultSource/set_primary_key> columns to populate
+the C<WHERE> clause necessary to accomplish the operation.
+
+This is why it is important to declare a
+L<primary key|DBIx::Class::ResultSource/set_primary_key> on all your result
+sources B<even if the underlying RDBMS does not have one>. In a pinch one can
+always declare each row identifiable by all its columns:
+
+ __PACKAGE__->set_primary_keys (__PACKAGE__->columns);
+
+If you elect not to declare a C<primary key>, DBIx::Class will behave correctly
+by throwing exceptions on any row operation that relies on unique identifiable
+rows. If you inherited datasets with multiple identical rows in them, you can
+still operate with such sets provided you only utilize
+L<DBIx::Class::ResultSet> CRUD methods:
+L<search|DBIx::Class::ResultSet/search>,
+L<update|DBIx::Class::ResultSet/update>,
+L<delete|DBIx::Class::ResultSet/delete>
+
+
 =head2 Problems on RHEL5/CentOS5
 
 There used to be an issue with the system perl on Red Hat Enterprise