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 bbdd19ca89..5d9f13fd72 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -518,6 +518,8 @@ module ActiveRecord
# Add a new +type+ column named +column_name+ to +table_name+.
#
+ # See {ActiveRecord::ConnectionAdapters::TableDefinition.column}[rdoc-ref:ActiveRecord::ConnectionAdapters::TableDefinition#column].
+ #
# The +type+ parameter is normally one of the migrations native types,
# which is one of the following:
# :primary_key, :string, :text,
@@ -530,12 +532,17 @@ module ActiveRecord
# agnostic and should usually be avoided.
#
# Available options are (none of these exists by default):
+ # * :comment -
+ # Specifies the comment for the column. This option is ignored by some backends.
+ # * :collation -
+ # Specifies the collation for a :string or :text column.
+ # If not specified, the column will have the same collation as the table.
+ # * :default -
+ # The column's default value. Use +nil+ for +NULL+.
# * :limit -
# Requests a maximum column length. This is the number of characters for a :string column
# and number of bytes for :text, :binary, :blob, and :integer columns.
# This option is ignored by some backends.
- # * :default -
- # The column's default value. Use +nil+ for +NULL+.
# * :null -
# Allows or disallows +NULL+ values in the column.
# * :precision -
diff --git a/guides/source/active_record_migrations.md b/guides/source/active_record_migrations.md
index 165d9ff73e..73478a05ff 100644
--- a/guides/source/active_record_migrations.md
+++ b/guides/source/active_record_migrations.md
@@ -251,7 +251,9 @@ class AddUserRefToProducts < ActiveRecord::Migration[6.0]
end
```
-This migration will create a `user_id` column and appropriate index.
+This migration will create a `user_id` column, [references](#references) are a
+shorthand for creating columns, indexes, foreign keys or even polymorphic
+association columns.
There is also a generator which will produce join tables if `JoinTable` is part of the name:
@@ -347,8 +349,7 @@ create_table :products do |t|
end
```
-which creates a `products` table with a column called `name` (and as discussed
-below, an implicit `id` column).
+which creates a `products` table with a column called `name`.
By default, `create_table` will create a primary key called `id`. You can change
the name of the primary key with the `:primary_key` option (don't forget to
@@ -364,6 +365,16 @@ end
will append `ENGINE=BLACKHOLE` to the SQL statement used to create the table.
+An index can be created on the columns created within the `create_table` block
+by passing true or an options hash to the `:index` option:
+
+```ruby
+create_table :users do |t|
+ t.string :name, index: true
+ t.string :email, index: { unique: true, name: 'unique_emails' }
+end
+```
+
Also you can pass the `:comment` option with any description for the table
that will be stored in database itself and can be viewed with database administration
tools, such as MySQL Workbench or PgAdmin III. It's highly recommended to specify
@@ -469,23 +480,65 @@ example, this would make your migration irreversible.
Column modifiers can be applied when creating or changing a column:
-* `limit` Sets the maximum size of the `string/text/binary/integer` fields.
-* `precision` Defines the precision for the `decimal` fields, representing the
-total number of digits in the number.
-* `scale` Defines the scale for the `decimal` fields, representing the
-number of digits after the decimal point.
-* `polymorphic` Adds a `type` column for `belongs_to` associations.
-* `null` Allows or disallows `NULL` values in the column.
+* `comment` Adds a comment for the column.
+* `collation` Specifies the collation for a `string` or `text` column.
* `default` Allows to set a default value on the column. Note that if you
are using a dynamic value (such as a date), the default will only be calculated
-the first time (i.e. on the date the migration is applied).
-* `comment` Adds a comment for the column.
+the first time (i.e. on the date the migration is applied). Use `nil` for `NULL`.
+* `limit` Sets the maximum number of characters for a `string` column
+and the maximum number of bytes for `text/binary/integer` columns.
+* `null` Allows or disallows `NULL` values in the column.
+* `precision` Specifies the precision for `decimal/numeric/datetime/time` columns.
+* `scale` Specifies the scale for the `decimal` and `numeric` columns,
+representing the number of digits after the decimal point.
+
+NOTE: For `add_column` or `change_column` there is no option for adding indexes.
+They need to be added separately using `add_index`.
Some adapters may support additional options; see the adapter specific API docs
for further information.
NOTE: `null` and `default` cannot be specified via command line.
+### References
+
+The `add_reference` method allows the creation of an appropriately named column.
+
+```ruby
+add_reference :users, :role
+```
+
+This migration will create a `role_id` column in the users table. It creates an
+index for this column as well, unless explicitly told not with the
+`index: false` option:
+
+```ruby
+add_reference :users, :role, index: false
+```
+
+The method `add_belongs_to` is an alias of `add_reference`.
+
+```ruby
+add_belongs_to :taggings, :taggable, polymorphic: true
+```
+
+The polymorphic option will create two columns on the taggings table which can
+be used for polymorphic assocations: `taggable_type` and `taggable_id`.
+
+A foreign key can be created with the the `foreign_key` option.
+
+```ruby
+add_reference :users, :role, foreign_key: true
+```
+
+For more `add_reference` options, visit the [API documentation](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_reference).
+
+References can also be removed:
+
+```ruby
+remove_reference :products, :user, foreign_key: true, index: false
+```
+
### Foreign Keys
While it's not required you might want to add foreign key constraints to