instance method `add_column`

Ruby on Rails 7.0.10

Since v2.2.3

Available in: v2.2.3 v2.3.18 v3.0.20 v3.1.12 v3.2.22.5 v4.0.13 v4.1.16 v4.2.9 v5.2.8.1 v6.0.6 v6.1.7.10 v7.0.10 v7.1.6 v7.2.3 v8.0.4 v8.1.2

Compare with:

add_column(table_name, column_name, type, **options)

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.
:collation - Specifies the collation for a :string or :text column. If not specified, the column will have the same collation as the table.
:comment - Specifies the comment for the column. This option is ignored by some backends.
: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..63], :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)

Parameters

table_name req
column_name req
type req
options keyrest

Source

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 617
      def add_column(table_name, column_name, type, **options)
        return if options[:if_not_exists] == true && column_exists?(table_name, column_name)

        if supports_datetime_with_precision?
          if type == :datetime && !options.key?(:precision)
            options[:precision] = 6
          end
        end

        at = create_alter_table table_name
        at.add_column(column_name, type, **options)
        execute schema_creation.accept at
      end

Defined in activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb line 617 · View on GitHub · Improve this page · Find usages on GitHub

Defined in ActiveRecord::ConnectionAdapters::SchemaStatements

Signature

Examples

Parameters