· 8 years ago · Mar 06, 2018, 10:18 AM
1# ActiveRecord::Migration API Notes
2
3The `ActiveRecord::Migration` class is used to manage Rails migration scripts. When writing these scripts, there are many class methods that can be used to make schema changes, which are described below in several sections.
4
5## Migration Methods
6
7| Create Methods | Arguments | Notes | Rev |
8| ------------------- | ---------------------------------------- | ---------------------------------- | ----- |
9| create_join_table | table1, table2, options | Creates a join table | Y |
10| create_table | name, options | Creates a table | Y |
11| add_column | table_name, column_name, type, options | Adds a new column | Y |
12| add_foreign_key | from_table, to_table, options | Adds a new foreign key | Y |
13| add_index | table_name, column_names, options | Adds a new index | Y |
14| add_reference | table_name, reference_name | Adds a new column `reference_id` | Y |
15| add_belongs_to | table_name, reference_name | same as `add_reference` | Y |
16| add_timestamps | table_name, options | adds timestamp columns | Y |
17
18
19
20| Change Methods | Arguments | Notes | Rev |
21| ----------------------- | --------------------------------------------- | ---------------------------------- | -------- |
22| change_column | table_name, column_name, type, options | Changes the column type | N |
23| change_column_default | table_name, column_name, default_or_changes | Changes the default value | Note 1 |
24| change_column_null | table_name, column_name, null, default =nil | Sets/removes NOT NULL constraint | Y |
25| change_table | name, options, &block | Make some changes on a table | |
26| rename_column | table_name, column_name, new_column_name | Renames a column | Y |
27| rename_index | table_name, old_name, new_name | Renames an index | Y |
28| rename_table | old_name, new_name | Renames a table | Y |
29
30
31| Deletion Methods | Arguments | Notes | Rev |
32| -------------------- | ---------------------------------------- | ----------------------------------------- | -------- |
33| drop_table | name | Drops the table | Note 2 |
34| drop_join_tale | table1, table2, options | Drops the join table | Y |
35| remove_column | table_name, column_name, type, options | Removes the column | Note 3 |
36| remove_columns | table_name, *column_names | Removes one or more columns | N |
37| remove_foreign_key | from_table, options_or_to_table | Removes the FK by options or to-table | Note 4 |
38| remove_index | table_name, column: column_names | Removes the index given by column_names | Y |
39| remove_index | table_name, name: index_name | Removes the index with the given name | Y |
40| remove_reference | table_name, ref_name, options | Removes the reference | Y |
41| remove_timestamps | table_name, options | Removes the timestamps | Y |
42
43
44| # | Migration Method Notes on Reversability |
45| --- | -------------------------------------- |
46| 1 | must supply a `:from` and `:to` option |
47| 2 | must supply a block |
48| 3 | must supply a type |
49| 4 | must supply a second table |
50
51
52### General DBMS Column Types
53
54These are the generic rails column types that are supported across all DBMS.
55
56The _column type_ is used on `add_column` and `change_column` methods. In order for a `remove_column` to be reversible, the _type_ should also be provided.
57
58| Rails Type | PG SQL Type | Notes |
59| ---------------------------------- | --------------- | ----------------------------------------------- |
60| `:bigint` | `BIGINT` | a 64-bit integer number |
61| `:binary` | `BYTEA` | a binary object |
62| `:boolean` | `BOOLEAN` | a boolean value: true or false |
63| `:date` | `DATE` | a date value |
64| `:datetime` | `TIMESTAMP` | date and time value |
65| `:decimal, precision: p, scale: s` | `DECIMAL(p,s)` | a decimal number, with precision p, and scale s |
66| `:float, limit: n` | `FLOAT(n)` | a real-number, with n digits of precision |
67| `:primary_key` | `PRIMARY KEY` | a bigserial (bigint serial) value |
68| `:string` | `VARCHAR(255)` | a variable length one-line string |
69| `:text` | `TEXT` | generally, a multi-line string |
70| `:time` | `TIME` | a time value |
71
72### PostgreSQL-Specific Column Types
73
74| Rails Type | PG SQL Type | Notes |
75| ---------------------------------- | --------------- | ----------------------------------------------- |
76| `:cidr` | `CIDR` | an Internet address range spec (7 or 19 bytes) |
77| `:daterange` | `DATERANGE` | a range of date values |
78| `:hstore` | `HSTORE` | a hash (key, value) store |
79| `:inet` | `INET` | an internet address (7 or 19 bytes) |
80| `:int4range` | `INT4RANGE` | a range of 4-byte (32-bit) integers |
81| `:int8range` | `INT8RANGE` | a range of 8-byte (64-bit) bigint integers |
82| `:integer, limit: 2` | `SMALLINT` | a 16-bit integer number |
83| `:integer, limit: 4` | `INT` | a 32-bit integer number |
84| `:json` | `JSON` | a Javascript Object Notiation |
85| `:jsonb` | `JSONB` | a binary JSON |
86| `:macaddr` | `MACADDR` | an Ethernet address |
87| `:money` | `MONEY` | a currency value |
88| `:numeric, precision: p, scale: s` | `NUMERIC(p,s)` | a number, with precision p, and scale s |
89| `:numrange` | `NUMRANGE` | a range of numeric values |
90| `:timestamp` | `TIMESTAMP` | date and time value |
91| `:tsrange` | `TSRANGE` | a range of timestamp values |
92| `:tstzrange` | `TSTZRANGE` | a time range with timezones |
93| `:tsvector` | `TSVECTOR` | a text-search vector |
94| `:uuid` | `UUID` | a globally-unique ID |
95| `:xml` | `XML` | an XML data type |
96
97
98### Notes on Types
99
100- With PostgreSQL, unless there is a strong requirement for the specific character length that `string` provides, the `text` type should be preferred, because there is actually a slight performance hit on fixed-length character strings.
101
102
103## Options on Migration Methods
104
105| Method | Options | Description |
106| ----------------------- | ----------------- | ------------------------------------------------------- |
107| create_join_table | :table_name | |
108| | :column_options | options to be applied to columns |
109| | :options | for table definition |
110| | :temporary | make a temporary table |
111| | :force | if true, drop table before creating it |
112| add_column | :limit | maximum column limit; = bytes for :integer |
113| | :default | column's default value; use nil for NULL |
114| | :null | allows NULL values |
115| | :precision | number of fractional digits for :decimal and :numeric |
116| | :scale | the scale for :decimal and :numeric columns |
117| add_foreign_key | :column | The FK on from_table; defaults to `{to_table}_id` |
118| | :primary_key | the PK on the to_table; defaults to `id` |
119| | :name | the constraint name; defaults to `fk_rails_<ident>` |
120| | :on_delete | Action for DELETE: :nullify, :cascade, and :restrict |
121| | :on_update | Action for UPDATE: :nullify, :cascade, and :restrict |
122| add_index | :name | the name of the index |
123| | :unique | true indicates that the index must have unique keys |
124| | :length | the length or lengths of the index |
125| | :order | specify ordering with `{column_name: :asc/:desc}` pairs |
126| | :where | conditional index |
127| | :using | algorithm: 'btree' |
128| add_reference | :type | reference column type; default: :integer |
129| (aka `belongs_to`) | :index | add an index; default to true |
130| | :foreign_key | add an appropriate FK constraint; default is false |
131| | | `{to_table: table_name}` |
132| | :null | whether the column allow nulls; default is true |
133| add_timestamps | :null | whether or not the timestamp columns can be NULL |
134| change_column | | same as `add_column` |
135| change_column_default | :from | old default (allows reversibility) |
136| change_table | :bulk | make multiple changes on a single ALTER TABLE |
137
138
139## Conditional Methods
140
141| Method | Arguments | Description |
142|--------------------------|--------------------------------------------|------------------------------------------|
143| column_exists? | table_name, column_name, type=nil, options | True if the named column exists |
144| data_source_exists? | table_name | True if the given SQL object exist |
145| foreign_key_exists? | table_name, options_or_to_table | True if FK exists from_table to to_table |
146| index_exists? | table_name, column_name(s) | True if index exist on given column(s) |
147| index_name_exists? | table_name, index_name | True if named index exists |
148| options_include_default? | options | true if options includes :default |
149| table_exists? | table_name | true if the given table name exists |
150| view_exists? | view_name | true if the given view exists |
151
152## Information Methods
153
154| Method | Arguments | Description |
155| ----------------------- | ------------ | -------------------------------------------------------------------- |
156| columns | table_name | an array of Column objects for the given table |
157| data_sources | | returns the data sources in the current database |
158| foreign_keys | table_name | an array of foreign key objects on the given table |
159| indexes | table_name | array of indexes on the given table |
160| native_database_types | | hash of mappings from abstract data types to native database types |
161| primary_key | table_name | the primary key for the table |
162| table_alias_for | table_name | return a suitable table alias |
163| table_comment | table_name | return a comment on the table (if any) |
164| table_options | table_name | return the options on the given table |
165| tables | | returns all the tables in the database |
166| views | | returns all the views in the database |