Link to API docs in AR Migrations guide [ci-skip]
This links the first mention of each method to its API documentation, similar to a Wikipedia article. Some subsequent mentions are also linked, when it suits the surrounding text.
This commit is contained in:
Jonathan Hefner
parent
53e97f0fa0
commit
5f96fbfe1e
|
|
@ -140,8 +140,8 @@ also start fleshing out the migration.
|
|||
|
||||
If the migration name is of the form "AddColumnToTable" or
|
||||
"RemoveColumnFromTable" and is followed by a list of column names and
|
||||
types then a migration containing the appropriate `add_column` and
|
||||
`remove_column` statements will be created.
|
||||
types then a migration containing the appropriate [`add_column`][] and
|
||||
[`remove_column`][] statements will be created.
|
||||
|
||||
```bash
|
||||
$ bin/rails generate migration AddPartNumberToProducts part_number:string
|
||||
|
|
@ -157,13 +157,13 @@ class AddPartNumberToProducts < ActiveRecord::Migration[6.0]
|
|||
end
|
||||
```
|
||||
|
||||
If you'd like to add an index on the new column, you can do that as well:
|
||||
If you'd like to add an index on the new column, you can do that as well.
|
||||
|
||||
```bash
|
||||
$ bin/rails generate migration AddPartNumberToProducts part_number:string:index
|
||||
```
|
||||
|
||||
will generate
|
||||
will generate the appropriate `add_column` and [`add_index`][] statements:
|
||||
|
||||
```ruby
|
||||
class AddPartNumberToProducts < ActiveRecord::Migration[6.0]
|
||||
|
|
@ -242,7 +242,7 @@ Also, the generator accepts column type as `references` (also available as
|
|||
$ bin/rails generate migration AddUserRefToProducts user:references
|
||||
```
|
||||
|
||||
generates
|
||||
generates the following [`add_reference`][] call:
|
||||
|
||||
```ruby
|
||||
class AddUserRefToProducts < ActiveRecord::Migration[6.0]
|
||||
|
|
@ -253,7 +253,6 @@ end
|
|||
```
|
||||
|
||||
This migration will create a `user_id` column and appropriate index.
|
||||
For more `add_reference` options, visit the [API documentation](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_reference).
|
||||
|
||||
There is also a generator which will produce join tables if `JoinTable` is part of the name:
|
||||
|
||||
|
|
@ -274,6 +273,11 @@ class CreateJoinTableCustomerProduct < ActiveRecord::Migration[6.0]
|
|||
end
|
||||
```
|
||||
|
||||
[`add_column`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_column
|
||||
[`add_index`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_index
|
||||
[`add_reference`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_reference
|
||||
[`remove_column`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-remove_column
|
||||
|
||||
### Model Generators
|
||||
|
||||
The model and scaffold generators will create migrations appropriate for adding
|
||||
|
|
@ -334,7 +338,7 @@ get to work!
|
|||
|
||||
### Creating a Table
|
||||
|
||||
The `create_table` method is one of the most fundamental, but most of the time,
|
||||
The [`create_table`][] method is one of the most fundamental, but most of the time,
|
||||
will be generated for you from using a model or scaffold generator. A typical
|
||||
use would be
|
||||
|
||||
|
|
@ -368,9 +372,11 @@ comments in migrations for applications with large databases as it helps people
|
|||
to understand data model and generate documentation.
|
||||
Currently only the MySQL and PostgreSQL adapters support comments.
|
||||
|
||||
[`create_table`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-create_table
|
||||
|
||||
### Creating a Join Table
|
||||
|
||||
The migration method `create_join_table` creates an HABTM (has and belongs to
|
||||
The migration method [`create_join_table`][] creates an HABTM (has and belongs to
|
||||
many) join table. A typical use would be:
|
||||
|
||||
```ruby
|
||||
|
|
@ -406,9 +412,11 @@ create_join_table :products, :categories do |t|
|
|||
end
|
||||
```
|
||||
|
||||
[`create_join_table`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-create_join_table
|
||||
|
||||
### Changing Tables
|
||||
|
||||
A close cousin of `create_table` is `change_table`, used for changing existing
|
||||
A close cousin of `create_table` is [`change_table`][], used for changing existing
|
||||
tables. It is used in a similar fashion to `create_table` but the object
|
||||
yielded to the block knows more tricks. For example:
|
||||
|
||||
|
|
@ -424,9 +432,11 @@ end
|
|||
removes the `description` and `name` columns, creates a `part_number` string
|
||||
column and adds an index on it. Finally it renames the `upccode` column.
|
||||
|
||||
[`change_table`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-change_table
|
||||
|
||||
### Changing Columns
|
||||
|
||||
Like the `remove_column` and `add_column` Rails provides the `change_column`
|
||||
Like the `remove_column` and `add_column` Rails provides the [`change_column`][]
|
||||
migration method.
|
||||
|
||||
```ruby
|
||||
|
|
@ -436,7 +446,7 @@ change_column :products, :part_number, :text
|
|||
This changes the column `part_number` on products table to be a `:text` field.
|
||||
Note that `change_column` command is irreversible.
|
||||
|
||||
Besides `change_column`, the `change_column_null` and `change_column_default`
|
||||
Besides `change_column`, the [`change_column_null`][] and [`change_column_default`][]
|
||||
methods are used specifically to change a not null constraint and default
|
||||
values of a column.
|
||||
|
||||
|
|
@ -452,6 +462,10 @@ NOTE: You could also write the above `change_column_default` migration as
|
|||
`change_column_default :products, :approved, false`, but unlike the previous
|
||||
example, this would make your migration irreversible.
|
||||
|
||||
[`change_column`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-change_column
|
||||
[`change_column_default`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-change_column_default
|
||||
[`change_column_null`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-change_column_null
|
||||
|
||||
### Column Modifiers
|
||||
|
||||
Column modifiers can be applied when creating or changing a column:
|
||||
|
|
@ -511,7 +525,7 @@ remove_foreign_key :accounts, name: :special_fk_name
|
|||
|
||||
### When Helpers aren't Enough
|
||||
|
||||
If the helpers provided by Active Record aren't enough you can use the `execute`
|
||||
If the helpers provided by Active Record aren't enough you can use the [`execute`][]
|
||||
method to execute arbitrary SQL:
|
||||
|
||||
```ruby
|
||||
|
|
@ -528,6 +542,8 @@ and
|
|||
[`ActiveRecord::ConnectionAdapters::Table`](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html)
|
||||
(which provides the methods available on the object yielded by `change_table`).
|
||||
|
||||
[`execute`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/DatabaseStatements.html#method-i-execute
|
||||
|
||||
### Using the `change` Method
|
||||
|
||||
The `change` method is the primary way of writing migrations. It works for the
|
||||
|
|
@ -535,29 +551,29 @@ majority of cases, where Active Record knows how to reverse the migration
|
|||
automatically. Currently, the `change` method supports only these migration
|
||||
definitions:
|
||||
|
||||
* add_column
|
||||
* add_foreign_key
|
||||
* add_index
|
||||
* add_reference
|
||||
* add_timestamps
|
||||
* change_column_default (must supply a :from and :to option)
|
||||
* change_column_null
|
||||
* create_join_table
|
||||
* create_table
|
||||
* disable_extension
|
||||
* drop_join_table
|
||||
* drop_table (must supply a block)
|
||||
* enable_extension
|
||||
* remove_column (must supply a type)
|
||||
* remove_foreign_key (must supply a second table)
|
||||
* remove_index
|
||||
* remove_reference
|
||||
* remove_timestamps
|
||||
* rename_column
|
||||
* rename_index
|
||||
* rename_table
|
||||
* [`add_column`][]
|
||||
* [`add_foreign_key`][]
|
||||
* [`add_index`][]
|
||||
* [`add_reference`][]
|
||||
* [`add_timestamps`][]
|
||||
* [`change_column_default`][] (must supply a :from and :to option)
|
||||
* [`change_column_null`][]
|
||||
* [`create_join_table`][]
|
||||
* [`create_table`][]
|
||||
* `disable_extension`
|
||||
* [`drop_join_table`][]
|
||||
* [`drop_table`][] (must supply a block)
|
||||
* `enable_extension`
|
||||
* [`remove_column`][] (must supply a type)
|
||||
* [`remove_foreign_key`][] (must supply a second table)
|
||||
* [`remove_index`][]
|
||||
* [`remove_reference`][]
|
||||
* [`remove_timestamps`][]
|
||||
* [`rename_column`][]
|
||||
* [`rename_index`][]
|
||||
* [`rename_table`][]
|
||||
|
||||
`change_table` is also reversible, as long as the block does not call `change`,
|
||||
[`change_table`][] is also reversible, as long as the block does not call `change`,
|
||||
`change_default` or `remove`.
|
||||
|
||||
`remove_column` is reversible if you supply the column type as the third
|
||||
|
|
@ -571,10 +587,22 @@ remove_column :posts, :slug, :string, null: false, default: ''
|
|||
If you're going to need to use any other methods, you should use `reversible`
|
||||
or write the `up` and `down` methods instead of using the `change` method.
|
||||
|
||||
[`add_foreign_key`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_foreign_key
|
||||
[`add_timestamps`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_timestamps
|
||||
[`drop_join_table`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-drop_join_table
|
||||
[`drop_table`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-drop_table
|
||||
[`remove_foreign_key`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-remove_foreign_key
|
||||
[`remove_index`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-remove_index
|
||||
[`remove_reference`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-remove_reference
|
||||
[`remove_timestamps`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-remove_timestamps
|
||||
[`rename_column`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-rename_column
|
||||
[`rename_index`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-rename_index
|
||||
[`rename_table`]: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-rename_table
|
||||
|
||||
### Using `reversible`
|
||||
|
||||
Complex migrations may require processing that Active Record doesn't know how
|
||||
to reverse. You can use `reversible` to specify what to do when running a
|
||||
to reverse. You can use [`reversible`][] to specify what to do when running a
|
||||
migration and what else to do when reverting it. For example:
|
||||
|
||||
```ruby
|
||||
|
|
@ -618,6 +646,8 @@ example, it might destroy some data. In such cases, you can raise
|
|||
to revert your migration, an error message will be displayed saying that it
|
||||
can't be done.
|
||||
|
||||
[`reversible`]: https://api.rubyonrails.org/classes/ActiveRecord/Migration.html#method-i-reversible
|
||||
|
||||
### Using the `up`/`down` Methods
|
||||
|
||||
You can also use the old style of migration using `up` and `down` methods
|
||||
|
|
@ -669,7 +699,7 @@ can't be done.
|
|||
|
||||
### Reverting Previous Migrations
|
||||
|
||||
You can use Active Record's ability to rollback migrations using the `revert` method:
|
||||
You can use Active Record's ability to rollback migrations using the [`revert`][] method:
|
||||
|
||||
```ruby
|
||||
require_relative "20121212123456_example_migration"
|
||||
|
|
@ -725,6 +755,8 @@ of `create_table` and `reversible`, replacing `create_table`
|
|||
by `drop_table`, and finally replacing `up` by `down` and vice-versa.
|
||||
This is all taken care of by `revert`.
|
||||
|
||||
[`revert`]: https://api.rubyonrails.org/classes/ActiveRecord/Migration.html#method-i-revert
|
||||
|
||||
Running Migrations
|
||||
------------------
|
||||
|
||||
|
|
@ -843,11 +875,11 @@ A migration creating a table and adding an index might produce output like this
|
|||
|
||||
Several methods are provided in migrations that allow you to control all this:
|
||||
|
||||
| Method | Purpose
|
||||
| -------------------- | -------
|
||||
| suppress_messages | Takes a block as an argument and suppresses any output generated by the block.
|
||||
| say | Takes a message argument and outputs it as is. A second boolean argument can be passed to specify whether to indent or not.
|
||||
| say_with_time | Outputs text along with how long it took to run its block. If the block returns an integer it assumes it is the number of rows affected.
|
||||
| Method | Purpose
|
||||
| -------------------------- | -------
|
||||
| [`suppress_messages`][] | Takes a block as an argument and suppresses any output generated by the block.
|
||||
| [`say`][] | Takes a message argument and outputs it as is. A second boolean argument can be passed to specify whether to indent or not.
|
||||
| [`say_with_time`][] | Outputs text along with how long it took to run its block. If the block returns an integer it assumes it is the number of rows affected.
|
||||
|
||||
For example, this migration:
|
||||
|
||||
|
|
@ -890,6 +922,10 @@ generates the following output
|
|||
If you want Active Record to not output anything, then running `bin/rails db:migrate
|
||||
VERBOSE=false` will suppress all output.
|
||||
|
||||
[`say`]: https://api.rubyonrails.org/classes/ActiveRecord/Migration.html#method-i-say
|
||||
[`say_with_time`]: https://api.rubyonrails.org/classes/ActiveRecord/Migration.html#method-i-say_with_time
|
||||
[`suppress_messages`]: https://api.rubyonrails.org/classes/ActiveRecord/Migration.html#method-i-suppress_messages
|
||||
|
||||
Changing Existing Migrations
|
||||
----------------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue