pg guide, explain the state of using UUID primary keys. Closes #20518.

[ci skip]

The PostgreSQL 9.4 docs suggest to use `pgcrypto`.
Howerver `create_table id: :uuid` will still default to `uuid_generate_v4()`

1 files changed, 9 insertions, 3 deletions

diff --git a/guides/source/active_record_postgresql.md b/guides/source/active_record_postgresql.md
index dcc523eb0f..fe112a4708 100644
--- a/guides/source/active_record_postgresql.md
+++ b/guides/source/active_record_postgresql.md
@@ -266,13 +266,14 @@ revision = Revision.first
 revision.identifier # => "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
 ```
 
-You can use `uuid` type to define references in migrations
+You can use `uuid` type to define references in migrations:
 
 ```ruby
 # db/migrate/20150418012400_create_blog.rb
-create_table :posts, id: :uuid
+enable_extension 'pgcrypto' unless extension_enabled?('pgcrypto')
+create_table :posts, id: :uuid, default: 'gen_random_uuid()'
 
-create_table :comments, id: :uuid do |t|
+create_table :comments, id: :uuid, default: 'gen_random_uuid()' do |t|
   # t.belongs_to :post, type: :uuid
   t.references :post, type: :uuid
 end
@@ -288,6 +289,8 @@ class Comment < ActiveRecord::Base
 end
 ```
 
+See [this section](#uuid-primary-keys) for more details on using UUIDs as primary key.
+
 ### Bit String Types
 
 * [type definition](http://www.postgresql.org/docs/current/static/datatype-bit.html)
@@ -377,6 +380,9 @@ device = Device.create
 device.id # => "814865cd-5a1d-4771-9306-4268f188fe9e"
 ```
 
+NOTE: `uuid_generate_v4()` (from `uuid-ossp`) is assumed if no `:default` option was
+passed to `create_table`.
+
 Full Text Search
 ----------------