Method: ActiveRecord::ConnectionAdapters::SchemaStatements#add_column

Defined in:

activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb

#add_column(table_name, column_name, type, **options) ⇒ Object

Add a new type column named column_name to table_name.

See 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, :integer, :bigint, :float, :decimal, :numeric, :datetime, :time, :date, :binary, :blob, :boolean.

You may use a type not in this list as long as it is supported by your database (for example, “polygon” in MySQL), but this will not be database 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.

• :null - Allows or disallows NULL values in the column.

• :precision - Specifies the precision for the :decimal, :numeric, :datetime, and :time columns.

• :scale - Specifies the scale for the :decimal and :numeric columns.

• :if_not_exists - Specifies if the column already exists to not try to re-add it. This will avoid duplicate column errors.

Note: The precision is the total number of significant digits, and the scale is the number of digits that can be stored following the decimal point. For example, the number 123.45 has a precision of 5 and a scale of 2. A decimal with a precision of 5 and a scale of 2 can range from -999.99 to 999.99.

Please be aware of different RDBMS implementations behavior with :decimal columns:

• The SQL standard says the default scale should be 0, :scale <= :precision, and makes no comments about the requirements of :precision.

• MySQL: :precision [1..65], :scale [0..30]. Default is (10,0).

• PostgreSQL: :precision [1..infinity], :scale [0..infinity]. No default.

• SQLite3: No restrictions on :precision and :scale, but the maximum supported :precision is 16. No default.

• Oracle: :precision [1..38], :scale [-84..127]. Default is (38,0).

• SqlServer: :precision [1..38], :scale [0..38]. Default (38,0).

Examples

add_column(:users, :picture, :binary, limit: 2.megabytes)
# ALTER TABLE "users" ADD "picture" blob(2097152)

add_column(:articles, :status, :string, limit: 20, default: 'draft', null: false)
# ALTER TABLE "articles" ADD "status" varchar(20) DEFAULT 'draft' NOT NULL

add_column(:answers, :bill_gates_money, :decimal, precision: 15, scale: 2)
# ALTER TABLE "answers" ADD "bill_gates_money" decimal(15,2)

add_column(:measurements, :sensor_reading, :decimal, precision: 30, scale: 20)
# ALTER TABLE "measurements" ADD "sensor_reading" decimal(30,20)

# While :scale defaults to zero on most databases, it
# probably wouldn't hurt to include it.
add_column(:measurements, :huge_integer, :decimal, precision: 30)
# ALTER TABLE "measurements" ADD "huge_integer" decimal(30)

# Defines a column that stores an array of a type.
add_column(:users, :skills, :text, array: true)
# ALTER TABLE "users" ADD "skills" text[]

# Defines a column with a database-specific type.
add_column(:shapes, :triangle, 'polygon')
# ALTER TABLE "shapes" ADD "triangle" polygon

# Ignores the method call if the column exists
add_column(:shapes, :triangle, 'polygon', if_not_exists: true)

# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 625

def add_column(table_name, column_name, type, **options)
  add_column_def = build_add_column_definition(table_name, column_name, type, **options)
  return unless add_column_def

  execute schema_creation.accept(add_column_def)
end