added primary_key option documentation for belongs_to association

fixes issue #16698

1 files changed, 19 insertions, 0 deletions

diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index c9e0fcd939..026435b208 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -827,6 +827,7 @@ The `belongs_to` association supports these options:
 * `:counter_cache`
 * `:dependent`
 * `:foreign_key`
+* `:primary_key`
 * `:inverse_of`
 * `:polymorphic`
 * `:touch`
@@ -908,6 +909,24 @@ end
 
 TIP: In any case, Rails will not create foreign key columns for you. You need to explicitly define them as part of your migrations.
 
+##### `:primary_key`
+
+By convention, Rails assumes that the column used to hold the primary key of it's table is `id`, and `:primary_key` allows you to specify a different column.
+
+Let's say that `users` table has `guid` as the primary key. And the requirement is that `todos` table should hold `guid` column value in the foreign key `user_id`. This can be achieved like this
+
+```ruby
+class User < ActiveRecord::Base
+  self.primay_key = 'guid' # primary key is guid and not id
+end
+
+class Todo < ActiveRecord::Base
+  belongs_to :user, primary_key: 'guid'
+end
+```
+
+Now if we execute `@user.todos.create` then `@todo` record will have `user_id` value as the `guid` value of `@user`.
+
 ##### `:inverse_of`
 
 The `:inverse_of` option specifies the name of the `has_many` or `has_one` association that is the inverse of this association. Does not work in combination with the `:polymorphic` options.