ActiveRecord Migration actions (methods)

README-migration-apis.md

ActiveRecord::Migration API Notes

The 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.

Migration Methods

Create Methods	Arguments	Notes	Rev
create_join_table	table1, table2, options	Creates a join table	Y
create_table	name, options	Creates a table	Y
add_column	table_name, column_name, type, options	Adds a new column	Y
add_foreign_key	from_table, to_table, options	Adds a new foreign key	Y
add_index	table_name, column_names, options	Adds a new index	Y
add_reference	table_name, reference_name	Adds a new column reference_id	Y
add_belongs_to	table_name, reference_name	same as add_reference	Y
add_timestamps	table_name, options	adds timestamp columns	Y

Change Methods	Arguments	Notes	Rev
change_column	table_name, column_name, type, options	Changes the column type	N
change_column_default	table_name, column_name, default_or_changes	Changes the default value	Note 1
change_column_null	table_name, column_name, null, default =nil	Sets/removes NOT NULL constraint	Y
change_table	name, options, &block	Make some changes on a table
rename_column	table_name, column_name, new_column_name	Renames a column	Y
rename_index	table_name, old_name, new_name	Renames an index	Y
rename_table	old_name, new_name	Renames a table	Y

Deletion Methods	Arguments	Notes	Rev
drop_table	name	Drops the table	Note 2
drop_join_tale	table1, table2, options	Drops the join table	Y
remove_column	table_name, column_name, type, options	Removes the column	Note 3
remove_columns	table_name, *column_names	Removes one or more columns	N
remove_foreign_key	from_table, options_or_to_table	Removes the FK by options or to-table	Note 4
remove_index	table_name, column: column_names	Removes the index given by column_names	Y
remove_index	table_name, name: index_name	Removes the index with the given name	Y
remove_reference	table_name, ref_name, options	Removes the reference	Y
remove_timestamps	table_name, options	Removes the timestamps	Y

#	Migration Method Notes on Reversability
1	must supply a :from and :to option
2	must supply a block
3	must supply a type
4	must supply a second table

General DBMS Column Types

These are the generic rails column types that are supported across all DBMS.

The 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.

Rails Type	PG SQL Type	Notes
:bigint	BIGINT	a 64-bit integer number
:binary	BYTEA	a binary object
:boolean	BOOLEAN	a boolean value: true or false
:date	DATE	a date value
:datetime	TIMESTAMP	date and time value
:decimal, precision: p, scale: s	DECIMAL(p,s)	a decimal number, with precision p, and scale s
:float, limit: n	FLOAT(n)	a real-number, with n digits of precision
:primary_key	PRIMARY KEY	a bigserial (bigint serial) value
:string	VARCHAR(255)	a variable length one-line string
:text	TEXT	generally, a multi-line string
:time	TIME	a time value

PostgreSQL-Specific Column Types

Rails Type	PG SQL Type	Notes
:cidr	CIDR	an Internet address range spec (7 or 19 bytes)
:daterange	DATERANGE	a range of date values
:hstore	HSTORE	a hash (key, value) store
:inet	INET	an internet address (7 or 19 bytes)
:int4range	INT4RANGE	a range of 4-byte (32-bit) integers
:int8range	INT8RANGE	a range of 8-byte (64-bit) bigint integers
:integer, limit: 2	SMALLINT	a 16-bit integer number
:integer, limit: 4	INT	a 32-bit integer number
:json	JSON	a Javascript Object Notiation
:jsonb	JSONB	a binary JSON
:macaddr	MACADDR	an Ethernet address
:money	MONEY	a currency value
:numeric, precision: p, scale: s	NUMERIC(p,s)	a number, with precision p, and scale s
:numrange	NUMRANGE	a range of numeric values
:timestamp	TIMESTAMP	date and time value
:tsrange	TSRANGE	a range of timestamp values
:tstzrange	TSTZRANGE	a time range with timezones
:tsvector	TSVECTOR	a text-search vector
:uuid	UUID	a globally-unique ID
:xml	XML	an XML data type

Notes on Types

• 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.

Options on Migration Methods

Method	Options	Description
create_join_table	:table_name
	:column_options	options to be applied to columns
	:options	for table definition
	:temporary	make a temporary table
	:force	if true, drop table before creating it
add_column	:limit	maximum column limit; = bytes for :integer
	:default	column's default value; use nil for NULL
	:null	allows NULL values
	:precision	number of fractional digits for :decimal and :numeric
	:scale	the scale for :decimal and :numeric columns
add_foreign_key	:column	The FK on from_table; defaults to {to_table}_id
	:primary_key	the PK on the to_table; defaults to id
	:name	the constraint name; defaults to fk_rails_<ident>
	:on_delete	Action for DELETE: :nullify, :cascade, and :restrict
	:on_update	Action for UPDATE: :nullify, :cascade, and :restrict
add_index	:name	the name of the index
	:unique	true indicates that the index must have unique keys
	:length	the length or lengths of the index
	:order	specify ordering with {column_name: :asc/:desc} pairs
	:where	conditional index
	:using	algorithm: 'btree'
add_reference	:type	reference column type; default: :integer
(aka belongs_to)	:index	add an index; default to true
	:foreign_key	add an appropriate FK constraint; default is false
		{to_table: table_name}
	:null	whether the column allow nulls; default is true
add_timestamps	:null	whether or not the timestamp columns can be NULL
change_column		same as add_column
change_column_default	:from	old default (allows reversibility)
change_table	:bulk	make multiple changes on a single ALTER TABLE

Conditional Methods

Method	Arguments	Description
column_exists?	table_name, column_name, type=nil, options	True if the named column exists
data_source_exists?	table_name	True if the given SQL object exist
foreign_key_exists?	table_name, options_or_to_table	True if FK exists from_table to to_table
index_exists?	table_name, column_name(s)	True if index exist on given column(s)
index_name_exists?	table_name, index_name	True if named index exists
options_include_default?	options	true if options includes :default
table_exists?	table_name	true if the given table name exists
view_exists?	view_name	true if the given view exists

Information Methods

Method	Arguments	Description
columns	table_name	an array of Column objects for the given table
data_sources		returns the data sources in the current database
foreign_keys	table_name	an array of foreign key objects on the given table
indexes	table_name	array of indexes on the given table
native_database_types		hash of mappings from abstract data types to native database types
primary_key	table_name	the primary key for the table
table_alias_for	table_name	return a suitable table alias
table_comment	table_name	return a comment on the table (if any)
table_options	table_name	return the options on the given table
tables		returns all the tables in the database
views		returns all the views in the database