Clarify no support for non PK id columns

[ci skip]

2 files changed, 8 insertions, 5 deletions

diff --git a/activerecord/lib/active_record/attribute_methods/primary_key.rb b/activerecord/lib/active_record/attribute_methods/primary_key.rb
index 9b267bb7c0..6af5346fa7 100644
--- a/activerecord/lib/active_record/attribute_methods/primary_key.rb
+++ b/activerecord/lib/active_record/attribute_methods/primary_key.rb
@@ -14,38 +14,39 @@ module ActiveRecord
         [key] if key
       end
 
-      # Returns the primary key value.
+      # Returns the primary key column's value.
       def id
         sync_with_transaction_state
         primary_key = self.class.primary_key
         _read_attribute(primary_key) if primary_key
       end
 
-      # Sets the primary key value.
+      # Sets the primary key column's value.
       def id=(value)
         sync_with_transaction_state
         primary_key = self.class.primary_key
         _write_attribute(primary_key, value) if primary_key
       end
 
-      # Queries the primary key value.
+      # Queries the primary key column's value.
       def id?
         sync_with_transaction_state
         query_attribute(self.class.primary_key)
       end
 
-      # Returns the primary key value before type cast.
+      # Returns the primary key column's value before type cast.
       def id_before_type_cast
         sync_with_transaction_state
         read_attribute_before_type_cast(self.class.primary_key)
       end
 
-      # Returns the primary key previous value.
+      # Returns the primary key column's previous value.
       def id_was
         sync_with_transaction_state
         attribute_was(self.class.primary_key)
       end
 
+      # Returns the primary key column's value from the database.
       def id_in_database
         sync_with_transaction_state
         attribute_in_database(self.class.primary_key)
diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md
index b9e24099b1..a67e2924d7 100644
--- a/guides/source/active_record_basics.md
+++ b/guides/source/active_record_basics.md
@@ -202,6 +202,8 @@ class Product < ApplicationRecord
 end
 ```
 
+NOTE: Active Record does not support using non-primary key columns named `id`.
+
 CRUD: Reading and Writing Data
 ------------------------------