Add more documentation for create_join_table.

Explain that it doesn't create indices by default and
that it also has a block form.

2 files changed, 18 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
index b737268f61..b3e28d387e 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -192,6 +192,14 @@ module ActiveRecord
       #   Set to true to drop the table before creating it.
       #   Defaults to false.
       #
+      # Note that +create_join_table+ does not create any indices by default; you can use
+      # its block form to do so yourself:
+      #
+      #  create_join_table :products, :categories do |t|
+      #    t.index :products
+      #    t.index :categories
+      #  end
+      #
       # ====== Add a backend specific option to the generated SQL (MySQL)
       #  create_join_table(:assemblies, :parts, options: 'ENGINE=InnoDB DEFAULT CHARSET=utf8')
       # generates:
diff --git a/guides/source/migrations.md b/guides/source/migrations.md
index c4fbae8925..d738d847e9 100644
--- a/guides/source/migrations.md
+++ b/guides/source/migrations.md
@@ -344,6 +344,16 @@ create_join_table :products, :categories, column_options: {null: true}
 will create the `product_id` and `category_id` with the `:null` option as
 `true`.
 
+`create_join_table` also accepts a block, which you can use to add indices
+(which are not created by default) or additional columns:
+
+```ruby
+create_join_table :products, :categories do |t|
+  t.index :products
+  t.index :categories
+end
+```
+
 ### Changing Tables
 
 A close cousin of `create_table` is `change_table`, used for changing existing