Module: ActiveRecord::ConnectionAdapters::SchemaStatements

Includes:
Migration::JoinTable
Included in:
AbstractAdapter
Defined in:
activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb

Instance Method Summary collapse

Instance Method Details

#add_check_constraint(table_name, expression, if_not_exists: false, **options) ⇒ Object

Adds a new check constraint to the table. expression is a String representation of verifiable boolean condition.

add_check_constraint :products, "price > 0", name: "price_check"

generates:

ALTER TABLE "products" ADD CONSTRAINT price_check CHECK (price > 0)

The options hash can include the following keys:

:name

The constraint name. Defaults to chk_rails_<identifier>.

:if_not_exists

Silently ignore if the constraint already exists, rather than raise an error.

:validate

(PostgreSQL only) Specify whether or not the constraint should be validated. Defaults to true.



1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1322

def add_check_constraint(table_name, expression, if_not_exists: false, **options)
  return unless supports_check_constraints?

  options = check_constraint_options(table_name, expression, options)
  return if if_not_exists && check_constraint_exists?(table_name, **options)

  at = create_alter_table(table_name)
  at.add_check_constraint(expression, options)

  execute schema_creation.accept(at)
end

#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 migration’s 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)



651
652
653
654
655
656
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 651

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

#add_columns(table_name, *column_names, type:, **options) ⇒ Object

:nodoc:



658
659
660
661
662
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 658

def add_columns(table_name, *column_names, type:, **options) # :nodoc:
  column_names.each do |column_name|
    add_column(table_name, column_name, type, **options)
  end
end

#add_foreign_key(from_table, to_table, **options) ⇒ Object

Adds a new foreign key. from_table is the table with the key column, to_table contains the referenced primary key.

The foreign key will be named after the following pattern: fk_rails_<identifier>. identifier is a 10 character long string which is deterministically generated from the from_table and column. A custom name can be specified with the :name option.

Creating a simple foreign key
add_foreign_key :articles, :authors

generates:

ALTER TABLE "articles" ADD CONSTRAINT fk_rails_e74ce85cbc FOREIGN KEY ("author_id") REFERENCES "authors" ("id")
Creating a foreign key, ignoring method call if the foreign key exists
add_foreign_key(:articles, :authors, if_not_exists: true)
Creating a foreign key on a specific column
add_foreign_key :articles, :users, column: :author_id, primary_key: "lng_id"

generates:

ALTER TABLE "articles" ADD CONSTRAINT fk_rails_58ca3d3a82 FOREIGN KEY ("author_id") REFERENCES "users" ("lng_id")
Creating a composite foreign key
Assuming "carts" table has "(shop_id, user_id)" as a primary key.

add_foreign_key :orders, :carts, primary_key: [:shop_id, :user_id]

generates:

ALTER TABLE "orders" ADD CONSTRAINT fk_rails_6f5e4cb3a4 FOREIGN KEY ("cart_shop_id", "cart_user_id") REFERENCES "carts" ("shop_id", "user_id")
Creating a cascading foreign key
add_foreign_key :articles, :authors, on_delete: :cascade

generates:

ALTER TABLE "articles" ADD CONSTRAINT fk_rails_e74ce85cbc FOREIGN KEY ("author_id") REFERENCES "authors" ("id") ON DELETE CASCADE

The options hash can include the following keys:

:column

The foreign key column name on from_table. Defaults to to_table.singularize + "_id". Pass an array to create a composite foreign key.

:primary_key

The primary key column name on to_table. Defaults to id. Pass an array to create a composite foreign key.

:name

The constraint name. Defaults to fk_rails_<identifier>.

:on_delete

Action that happens ON DELETE. Valid values are :nullify, :cascade, and :restrict

:on_update

Action that happens ON UPDATE. Valid values are :nullify, :cascade, and :restrict

:if_not_exists

Specifies if the foreign key already exists to not try to re-add it. This will avoid duplicate column errors.

:validate

(PostgreSQL only) Specify whether or not the constraint should be validated. Defaults to true.

:deferrable

(PostgreSQL only) Specify whether or not the foreign key should be deferrable. Valid values are booleans or :deferred or :immediate to specify the default behavior. Defaults to false.



1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1201

def add_foreign_key(from_table, to_table, **options)
  return unless use_foreign_keys?

  options = foreign_key_options(from_table, to_table, options)
  return if options[:if_not_exists] == true && foreign_key_exists?(from_table, to_table, **options.slice(:column, :primary_key))

  at = create_alter_table from_table
  at.add_foreign_key to_table, options

  execute schema_creation.accept(at)
end

#add_index(table_name, column_name, **options) ⇒ Object

Adds a new index to the table. column_name can be a single Symbol, or an Array of Symbols.

The index will be named after the table and the column name(s), unless you pass :name as an option.

Creating a simple index
add_index(:suppliers, :name)

generates:

CREATE INDEX index_suppliers_on_name ON suppliers(name)
Creating a index which already exists
add_index(:suppliers, :name, if_not_exists: true)

generates:

CREATE INDEX IF NOT EXISTS index_suppliers_on_name ON suppliers(name)

Note: Not supported by MySQL.

Creating a unique index
add_index(:accounts, [:branch_id, :party_id], unique: true)

generates:

CREATE UNIQUE INDEX index_accounts_on_branch_id_and_party_id ON accounts(branch_id, party_id)
Creating a named index
add_index(:accounts, [:branch_id, :party_id], unique: true, name: 'by_branch_party')

generates:

CREATE UNIQUE INDEX by_branch_party ON accounts(branch_id, party_id)
Creating an index with specific key length
add_index(:accounts, :name, name: 'by_name', length: 10)

generates:

CREATE INDEX by_name ON accounts(name(10))
Creating an index with specific key lengths for multiple keys
add_index(:accounts, [:name, :surname], name: 'by_name_surname', length: {name: 10, surname: 15})

generates:

CREATE INDEX by_name_surname ON accounts(name(10), surname(15))

Note: only supported by MySQL

Creating an index with a sort order (desc or asc, asc is the default)
add_index(:accounts, [:branch_id, :party_id, :surname], name: 'by_branch_desc_party', order: {branch_id: :desc, party_id: :asc})

generates:

CREATE INDEX by_branch_desc_party ON accounts(branch_id DESC, party_id ASC, surname)

Note: MySQL only supports index order from 8.0.1 onwards (earlier versions accepted the syntax but ignored it).

Creating a partial index
add_index(:accounts, [:branch_id, :party_id], unique: true, where: "active")

generates:

CREATE UNIQUE INDEX index_accounts_on_branch_id_and_party_id ON accounts(branch_id, party_id) WHERE active

Note: Partial indexes are only supported for PostgreSQL and SQLite.

Creating an index that includes additional columns
add_index(:accounts, :branch_id,  include: :party_id)

generates:

CREATE INDEX index_accounts_on_branch_id ON accounts USING btree(branch_id) INCLUDE (party_id)

Note: only supported by PostgreSQL.

Creating an index where NULLs are treated equally
add_index(:people, :last_name, nulls_not_distinct: true)

generates:

CREATE INDEX index_people_on_last_name ON people (last_name) NULLS NOT DISTINCT

Note: only supported by PostgreSQL version 15.0.0 and greater.

Creating an index with a specific method
add_index(:developers, :name, using: 'btree')

generates:

CREATE INDEX index_developers_on_name ON developers USING btree (name) -- PostgreSQL
CREATE INDEX index_developers_on_name USING btree ON developers (name) -- MySQL

Note: only supported by PostgreSQL and MySQL

Creating an index with a specific operator class
add_index(:developers, :name, using: 'gist', opclass: :gist_trgm_ops)
# CREATE INDEX developers_on_name ON developers USING gist (name gist_trgm_ops) -- PostgreSQL

add_index(:developers, [:name, :city], using: 'gist', opclass: { city: :gist_trgm_ops })
# CREATE INDEX developers_on_name_and_city ON developers USING gist (name, city gist_trgm_ops) -- PostgreSQL

add_index(:developers, [:name, :city], using: 'gist', opclass: :gist_trgm_ops)
# CREATE INDEX developers_on_name_and_city ON developers USING gist (name gist_trgm_ops, city gist_trgm_ops) -- PostgreSQL

Note: only supported by PostgreSQL

Creating an index with a specific type
add_index(:developers, :name, type: :fulltext)

generates:

CREATE FULLTEXT INDEX index_developers_on_name ON developers (name) -- MySQL

Note: only supported by MySQL.

Creating an index with a specific algorithm
add_index(:developers, :name, algorithm: :concurrently)
# CREATE INDEX CONCURRENTLY developers_on_name on developers (name) -- PostgreSQL

add_index(:developers, :name, algorithm: :inplace)
# CREATE INDEX `index_developers_on_name` ON `developers` (`name`) ALGORITHM = INPLACE -- MySQL

Note: only supported by PostgreSQL and MySQL.

Concurrently adding an index is not supported in a transaction.

For more information see the “Transactional Migrations” section.

Creating an index that is not used by queries
add_index(:developers, :name, enabled: false)

generates:

CREATE INDEX index_developers_on_name ON developers (name) INVISIBLE -- MySQL

CREATE INDEX index_developers_on_name ON developers (name) IGNORED -- MariaDB

Note: only supported by MySQL version 8.0.0 and greater, and MariaDB version 10.6.0 and greater.



943
944
945
946
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 943

def add_index(table_name, column_name, **options)
  create_index = build_create_index_definition(table_name, column_name, **options)
  execute schema_creation.accept(create_index)
end

#add_index_options(table_name, column_name, name: nil, if_not_exists: false, internal: false, **options) ⇒ Object

:nodoc:



1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1505

def add_index_options(table_name, column_name, name: nil, if_not_exists: false, internal: false, **options) # :nodoc:
  options.assert_valid_keys(valid_index_options)

  column_names = index_column_names(column_name)

  index_name = name&.to_s
  index_name ||= index_name(table_name, column_names)

  validate_index_length!(table_name, index_name, internal)

  index = create_index_definition(
    table_name, index_name,
    options[:unique],
    column_names,
    lengths: options[:length] || {},
    orders: options[:order] || {},
    opclasses: options[:opclass] || {},
    where: options[:where],
    type: options[:type],
    using: options[:using],
    include: options[:include],
    nulls_not_distinct: options[:nulls_not_distinct],
    comment: options[:comment]
  )

  [index, index_algorithm(options[:algorithm]), if_not_exists]
end

#add_reference(table_name, ref_name, **options) ⇒ Object Also known as: add_belongs_to

Adds a reference. The reference column is a bigint by default, the :type option can be used to specify a different type. Optionally adds a _type column, if :polymorphic option is provided.

The options hash can include the following keys:

:type

The reference column type. Defaults to :bigint.

:index

Add an appropriate index. Defaults to true. See #add_index for usage of this option.

:foreign_key

Add an appropriate foreign key constraint. Defaults to false, pass true to add. In case the join table can’t be inferred from the association pass :to_table with the appropriate table name.

:polymorphic

Whether an additional _type column should be added. Defaults to false.

:null

Whether the column allows nulls. Defaults to true.

Create a user_id bigint column without an index
add_reference(:products, :user, index: false)
Create a user_id string column
add_reference(:products, :user, type: :string)
Create supplier_id, supplier_type columns
add_reference(:products, :supplier, polymorphic: true)
Create a supplier_id column with a unique index
add_reference(:products, :supplier, index: { unique: true })
Create a supplier_id column with a named index
add_reference(:products, :supplier, index: { name: "my_supplier_index" })
Create a supplier_id column and appropriate foreign key
add_reference(:products, :supplier, foreign_key: true)
Create a supplier_id column and a foreign key to the firms table
add_reference(:products, :supplier, foreign_key: { to_table: :firms })



1091
1092
1093
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1091

def add_reference(table_name, ref_name, **options)
  ReferenceDefinition.new(ref_name, **options).add(table_name, self)
end

#add_timestamps(table_name, **options) ⇒ Object

Adds timestamps (created_at and updated_at) columns to table_name. Additional options (like :null) are forwarded to #add_column.

add_timestamps(:suppliers, null: true)



1488
1489
1490
1491
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1488

def add_timestamps(table_name, **options)
  fragments = add_timestamps_for_alter(table_name, **options)
  execute "ALTER TABLE #{quote_table_name(table_name)} #{fragments.join(', ')}"
end

#assume_migrated_upto_version(version) ⇒ Object 



1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1393

def assume_migrated_upto_version(version)
  version = version.to_i
  sm_table = quote_table_name(pool.schema_migration.table_name)

  migration_context = pool.migration_context
  migrated = migration_context.get_all_versions
  versions = migration_context.migrations.map(&:version)

  unless migrated.include?(version)
    execute "INSERT INTO #{sm_table} (version) VALUES (#{quote(version)})"
  end

  inserting = (versions - migrated).select { |v| v < version }
  if inserting.any?
    if (duplicate = inserting.detect { |v| inserting.count(v) > 1 })
      raise "Duplicate migration #{duplicate}. Please renumber your migrations to resolve the conflict."
    end
    execute insert_versions_sql(inserting)
  end
end

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

Builds an AlterTable object for adding a column to a table.

This definition object contains information about the column that would be created if the same arguments were passed to #add_column. See #add_column for information about passing a table_name, column_name, type and other options that can be passed.



669
670
671
672
673
674
675
676
677
678
679
680
681
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 669

def build_add_column_definition(table_name, column_name, type, **options) # :nodoc:
  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

  alter_table = create_alter_table(table_name)
  alter_table.add_column(column_name, type, **options)
  alter_table
end

#build_change_column_default_definition(table_name, column_name, default_or_changes) ⇒ Object

Builds a ChangeColumnDefaultDefinition object.

This definition object contains information about the column change that would occur if the same arguments were passed to #change_column_default. See #change_column_default for information about passing a table_name, column_name, type and other options that can be passed.

Raises:

  • (NotImplementedError) 


753
754
755
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 753

def build_change_column_default_definition(table_name, column_name, default_or_changes) # :nodoc:
  raise NotImplementedError, "build_change_column_default_definition is not implemented"
end

#build_create_index_definition(table_name, column_name, **options) ⇒ Object

Builds a CreateIndexDefinition object.

This definition object contains information about the index that would be created if the same arguments were passed to #add_index. See #add_index for information about passing a table_name, column_name, and other additional options that can be passed.



953
954
955
956
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 953

def build_create_index_definition(table_name, column_name, **options) # :nodoc:
  index, algorithm, if_not_exists = add_index_options(table_name, column_name, **options)
  CreateIndexDefinition.new(index, algorithm, if_not_exists)
end

#build_create_join_table_definition(table_1, table_2, column_options: {}, **options) ⇒ Object

Builds a TableDefinition object for a join table.

This definition object contains information about the table that would be created if the same arguments were passed to #create_join_table. See #create_join_table for information about what arguments should be passed.



423
424
425
426
427
428
429
430
431
432
433
434
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 423

def build_create_join_table_definition(table_1, table_2, column_options: {}, **options) # :nodoc:
  join_table_name = find_join_table_name(table_1, table_2, options)
  column_options.reverse_merge!(null: false, index: false)

  t1_ref, t2_ref = [table_1, table_2].map { |t| reference_name_for_table(t) }

  build_create_table_definition(join_table_name, **options.merge!(id: false)) do |td|
    td.references t1_ref, **column_options
    td.references t2_ref, **column_options
    yield td if block_given?
  end
end

#build_create_table_definition(table_name, id: :primary_key, primary_key: nil, force: nil, **options) {|table_definition| ... } ⇒ Object

Returns a TableDefinition object containing information about the table that would be created if the same arguments were passed to #create_table. See #create_table for information about passing a table_name, and other additional options that can be passed.

Yields:

  • (table_definition) 


333
334
335
336
337
338
339
340
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 333

def build_create_table_definition(table_name, id: :primary_key, primary_key: nil, force: nil, **options)
  table_definition = create_table_definition(table_name, **options.extract!(*valid_table_definition_options, :_skip_validate_options))
  table_definition.set_primary_key(table_name, id, primary_key, **options.extract!(*valid_primary_key_options, :_skip_validate_options))

  yield table_definition if block_given?

  table_definition
end

#bulk_change_table(table_name, operations) ⇒ Object

:nodoc:



1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1598

def bulk_change_table(table_name, operations) # :nodoc:
  sql_fragments = []
  non_combinable_operations = []

  operations.each do |command, args|
    table, arguments = args.shift, args
    method = :"#{command}_for_alter"

    if respond_to?(method, true)
      sqls, procs = Array(send(method, table, *arguments)).partition { |v| v.is_a?(String) }
      sql_fragments.concat(sqls)
      non_combinable_operations.concat(procs)
    else
      execute "ALTER TABLE #{quote_table_name(table_name)} #{sql_fragments.join(", ")}" unless sql_fragments.empty?
      non_combinable_operations.each(&:call)
      sql_fragments = []
      non_combinable_operations = []
      send(command, table, *arguments)
    end
  end

  execute "ALTER TABLE #{quote_table_name(table_name)} #{sql_fragments.join(", ")}" unless sql_fragments.empty?
  non_combinable_operations.each(&:call)
end

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

Changes the column’s definition according to the new options. See TableDefinition#column for details of the options you can use.

change_column(:suppliers, :name, :string, limit: 80)
change_column(:accounts, :description, :text)

Raises:

  • (NotImplementedError) 


726
727
728
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 726

def change_column(table_name, column_name, type, **options)
  raise NotImplementedError, "change_column is not implemented"
end

#change_column_comment(table_name, column_name, comment_or_changes) ⇒ Object

Changes the comment for a column or removes it if nil.

Passing a hash containing :from and :to will make this change reversible in migration:

change_column_comment(:posts, :state, from: "old_comment", to: "new_comment")

Raises:

  • (NotImplementedError) 


1566
1567
1568
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1566

def change_column_comment(table_name, column_name, comment_or_changes)
  raise NotImplementedError, "#{self.class} does not support changing column comments"
end

#change_column_default(table_name, column_name, default_or_changes) ⇒ Object

Sets a new default value for a column:

change_column_default(:suppliers, :qualification, 'new')
change_column_default(:accounts, :authorized, 1)

Setting the default to nil effectively drops the default:

change_column_default(:users, :email, nil)

Passing a hash containing :from and :to will make this change reversible in migration:

change_column_default(:posts, :state, from: nil, to: "draft")

Raises:

  • (NotImplementedError) 


744
745
746
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 744

def change_column_default(table_name, column_name, default_or_changes)
  raise NotImplementedError, "change_column_default is not implemented"
end

#change_column_null(table_name, column_name, null, default = nil) ⇒ Object

Sets or removes a NOT NULL constraint on a column. The null flag indicates whether the value can be NULL. For example

change_column_null(:users, :nickname, false)

says nicknames cannot be NULL (adds the constraint), whereas

change_column_null(:users, :nickname, true)

allows them to be NULL (drops the constraint).

The method accepts an optional fourth argument to replace existing NULLs with some other value. Use that one when enabling the constraint if needed, since otherwise those rows would not be valid.

Please note the fourth argument does not set a column’s default.

Raises:

  • (NotImplementedError) 


773
774
775
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 773

def change_column_null(table_name, column_name, null, default = nil)
  raise NotImplementedError, "change_column_null is not implemented"
end

#change_table(table_name, base = self, **options) ⇒ Object

A block for changing columns in table.

# change_table() yields a Table instance
change_table(:suppliers) do |t|
  t.column :name, :string, limit: 60
  # Other column alterations here
end

The options hash can include the following keys:

:bulk

Set this to true to make this a bulk alter query, such as

ALTER TABLE `users` ADD COLUMN age INT, ADD COLUMN birthdate DATETIME ...

Defaults to false.

Only supported on the MySQL and PostgreSQL adapter, ignored elsewhere.

Add a column
change_table(:suppliers) do |t|
  t.column :name, :string, limit: 60
end
Change type of a column
change_table(:suppliers) do |t|
  t.change :metadata, :json
end
Add 2 integer columns
change_table(:suppliers) do |t|
  t.integer :width, :height, null: false, default: 0
end
Add created_at/updated_at columns
change_table(:suppliers) do |t|
  t.timestamps
end
Add a foreign key column
change_table(:suppliers) do |t|
  t.references :company
end

Creates a company_id(bigint) column.

Add a polymorphic foreign key column
change_table(:suppliers) do |t|
  t.belongs_to :company, polymorphic: true
end

Creates company_type(varchar) and company_id(bigint) columns.

Remove a column
change_table(:suppliers) do |t|
  t.remove :company
end
Remove several columns
change_table(:suppliers) do |t|
  t.remove :company_id
  t.remove :width, :height
end
Remove an index
change_table(:suppliers) do |t|
  t.remove_index :company_id
end

See also Table for details on all of the various column transformations.



525
526
527
528
529
530
531
532
533
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 525

def change_table(table_name, base = self, **options)
  if supports_bulk_alter? && options[:bulk]
    recorder = ActiveRecord::Migration::CommandRecorder.new(self)
    yield update_table_definition(table_name, recorder)
    bulk_change_table(table_name, recorder.commands)
  else
    yield update_table_definition(table_name, base)
  end
end

#change_table_comment(table_name, comment_or_changes) ⇒ Object

Changes the comment for a table or removes it if nil.

Passing a hash containing :from and :to will make this change reversible in migration:

change_table_comment(:posts, from: "old_comment", to: "new_comment")

Raises:

  • (NotImplementedError) 


1556
1557
1558
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1556

def change_table_comment(table_name, comment_or_changes)
  raise NotImplementedError, "#{self.class} does not support changing table comments"
end

#check_constraint_exists?(table_name, **options) ⇒ Boolean

Checks to see if a check constraint exists on a table for a given check constraint definition.

check_constraint_exists?(:products, name: "price_check")

Returns:

  • (Boolean) 


1370
1371
1372
1373
1374
1375
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1370

def check_constraint_exists?(table_name, **options)
  if !options.key?(:name) && !options.key?(:expression)
    raise ArgumentError, "At least one of :name or :expression must be supplied"
  end
  check_constraint_for(table_name, **options).present?
end

#check_constraint_options(table_name, expression, options) ⇒ Object

:nodoc:



1334
1335
1336
1337
1338
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1334

def check_constraint_options(table_name, expression, options) # :nodoc:
  options = options.dup
  options[:name] ||= check_constraint_name(table_name, expression: expression, **options)
  options
end

#check_constraints(table_name) ⇒ Object

Returns an array of check constraints for the given table. The check constraints are represented as CheckConstraintDefinition objects.

Raises:

  • (NotImplementedError) 


1302
1303
1304
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1302

def check_constraints(table_name)
  raise NotImplementedError
end

#column_exists?(table_name, column_name, type = nil, **options) ⇒ Boolean

Checks to see if a column exists in a given table.

# Check a column exists
column_exists?(:suppliers, :name)

# Check a column exists of a particular type
#
# This works for standard non-casted types (eg. string) but is unreliable
# for types that may get cast to something else (eg. char, bigint).
column_exists?(:suppliers, :name, :string)

# Check a column exists with a specific definition
column_exists?(:suppliers, :name, :string, limit: 100)
column_exists?(:suppliers, :name, :string, default: 'default')
column_exists?(:suppliers, :name, :string, null: false)
column_exists?(:suppliers, :tax, :decimal, precision: 8, scale: 2)

Returns:

  • (Boolean) 


132
133
134
135
136
137
138
139
140
141
142
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 132

def column_exists?(table_name, column_name, type = nil, **options)
  column_name = column_name.to_s
  checks = []
  checks << lambda { |c| c.name == column_name }
  checks << lambda { |c| c.type == type.to_sym rescue nil } if type
  column_options_keys.each do |attr|
    checks << lambda { |c| c.send(attr) == options[attr] } if options.key?(attr)
  end

  columns(table_name).any? { |c| checks.all? { |check| check[c] } }
end

#columns(table_name) ⇒ Object

Returns an array of Column objects for the table specified by table_name.



107
108
109
110
111
112
113
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 107

def columns(table_name)
  table_name = table_name.to_s
  definitions = column_definitions(table_name)
  definitions.map do |field|
    new_column_from_field(table_name, field, definitions)
  end
end

#columns_for_distinct(columns, orders) ⇒ Object

Given a set of columns and an ORDER BY clause, returns the columns for a SELECT DISTINCT. PostgreSQL, MySQL, and Oracle override this for custom DISTINCT syntax - they require the order columns appear in the SELECT.

columns_for_distinct("posts.id", ["posts.created_at desc"])



1454
1455
1456
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1454

def columns_for_distinct(columns, orders) # :nodoc:
  columns
end

#create_join_table(table_1, table_2, column_options: {}, **options) ⇒ Object

Creates a new join table with the name created using the lexical order of the first two arguments. These arguments can be a String or a Symbol.

# Creates a table called 'assemblies_parts' with no id.
create_join_table(:assemblies, :parts)

# Creates a table called 'paper_boxes_papers' with no id.
create_join_table('papers', 'paper_boxes')

A duplicate prefix is combined into a single prefix. This is useful for namespaced models like Music::Artist and Music::Record:

# Creates a table called 'music_artists_records' with no id.
create_join_table('music_artists', 'music_records')

See connection.add_reference for details of the options you can use in column_options. column_options will be applied to both columns.

You can pass an options hash which can include the following keys:

:table_name

Sets the table name, overriding the default.

:options

Any extra options you want appended to the table definition.

:temporary

Make a temporary table.

:force

Set to true to drop the table before creating it. Defaults to false.

Note that #create_join_table does not create any indices by default; you can use its block form to do so yourself:

create_join_table :products, :categories do |t|
  t.index :product_id
  t.index :category_id
end
Add foreign keys with delete cascade
create_join_table(:assemblies, :parts, column_options: { foreign_key: { on_delete: :cascade } })

generates:

CREATE TABLE assemblies_parts (
  assembly_id bigint NOT NULL,
  part_id bigint NOT NULL,
  CONSTRAINT fk_rails_0d8a572d89 FOREIGN KEY ("assembly_id") REFERENCES "assemblies" ("id") ON DELETE CASCADE,
  CONSTRAINT fk_rails_ec7b48402b FOREIGN KEY ("part_id") REFERENCES "parts" ("id") ON DELETE CASCADE
)
Add a backend specific option to the generated SQL (MySQL)
create_join_table(:assemblies, :parts, options: 'ENGINE=InnoDB DEFAULT CHARSET=utf8')

generates:

CREATE TABLE assemblies_parts (
  assembly_id bigint NOT NULL,
  part_id bigint NOT NULL,
) ENGINE=InnoDB DEFAULT CHARSET=utf8



404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 404

def create_join_table(table_1, table_2, column_options: {}, **options)
  join_table_name = find_join_table_name(table_1, table_2, options)

  column_options.reverse_merge!(null: false, index: false)

  t1_ref, t2_ref = [table_1, table_2].map { |t| reference_name_for_table(t) }

  create_table(join_table_name, **options.merge!(id: false)) do |td|
    td.references t1_ref, **column_options
    td.references t2_ref, **column_options
    yield td if block_given?
  end
end

#create_schema_dumper(options) ⇒ Object

:nodoc:



1584
1585
1586
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1584

def create_schema_dumper(options) # :nodoc:
  SchemaDumper.create(self, options)
end

#create_table(table_name, id: :primary_key, primary_key: nil, force: nil, **options, &block) ⇒ Object

Creates a new table with the name table_name. table_name may either be a String or a Symbol.

There are two ways to work with #create_table. You can use the block form or the regular form, like this:

Block form

# create_table() passes a TableDefinition object to the block.
# This form will not only create the table, but also columns for the
# table.

create_table(:suppliers) do |t|
  t.column :name, :string, limit: 60
  # Other fields here
end

Block form, with shorthand

# You can also use the column types as method calls, rather than calling the column method.
create_table(:suppliers) do |t|
  t.string :name, limit: 60
  # Other fields here
end

Regular form

# Creates a table called 'suppliers' with no columns.
create_table(:suppliers)
# Add a column to 'suppliers'.
add_column(:suppliers, :name, :string, {limit: 60})

The options hash can include the following keys:

:id

Whether to automatically add a primary key column. Defaults to true. Join tables for ActiveRecord::Base.has_and_belongs_to_many should set it to false.

A Symbol can be used to specify the type of the generated primary key column.

:primary_key

The name of the primary key, if one is to be added automatically. Defaults to id. If :id is false, then this option is ignored.

If an array is passed, a composite primary key will be created.

Note that Active Record models will automatically detect their primary key. This can be avoided by using self.primary_key= on the model to define the key explicitly.

:options

Any extra options you want appended to the table definition.

:temporary

Make a temporary table.

:force

Set to true to drop the table before creating it. Set to :cascade to drop dependent objects as well. Defaults to false.

:if_not_exists

Set to true to avoid raising an error when the table already exists. Defaults to false.

:as

SQL to use to generate the table. When this option is used, the block is ignored, as are the :id and :primary_key options.

Add a backend specific option to the generated SQL (MySQL)
create_table(:suppliers, options: 'ENGINE=InnoDB DEFAULT CHARSET=utf8mb4')

generates:

CREATE TABLE suppliers (
  id bigint auto_increment PRIMARY KEY
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
Rename the primary key column
create_table(:objects, primary_key: 'guid') do |t|
  t.column :name, :string, limit: 80
end

generates:

CREATE TABLE objects (
  guid bigint auto_increment PRIMARY KEY,
  name varchar(80)
)
Change the primary key column type
create_table(:tags, id: :string) do |t|
  t.column :label, :string
end

generates:

CREATE TABLE tags (
  id varchar PRIMARY KEY,
  label varchar
)
Create a composite primary key
create_table(:orders, primary_key: [:product_id, :client_id]) do |t|
  t.belongs_to :product
  t.belongs_to :client
end

generates:

CREATE TABLE orders (
    product_id bigint NOT NULL,
    client_id bigint NOT NULL
);

ALTER TABLE ONLY "orders"
  ADD CONSTRAINT orders_pkey PRIMARY KEY (product_id, client_id);
Do not add a primary key column
create_table(:categories_suppliers, id: false) do |t|
  t.column :category_id, :bigint
  t.column :supplier_id, :bigint
end

generates:

CREATE TABLE categories_suppliers (
  category_id bigint,
  supplier_id bigint
)
Create a temporary table based on a query
create_table(:long_query, temporary: true,
  as: "SELECT * FROM orders INNER JOIN line_items ON order_id=orders.id")

generates:

CREATE TEMPORARY TABLE long_query AS
  SELECT * FROM orders INNER JOIN line_items ON order_id=orders.id

See also TableDefinition#column for details on how to create columns.



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 293

def create_table(table_name, id: :primary_key, primary_key: nil, force: nil, **options, &block)
  validate_create_table_options!(options)
  validate_table_length!(table_name) unless options[:_uses_legacy_table_name]

  if force && options.key?(:if_not_exists)
    raise ArgumentError, "Options `:force` and `:if_not_exists` cannot be used simultaneously."
  end

  td = build_create_table_definition(table_name, id: id, primary_key: primary_key, force: force, **options, &block)

  if force
    drop_table(table_name, force: force, if_exists: true)
  else
    schema_cache.clear_data_source_cache!(table_name.to_s)
  end

  result = execute schema_creation.accept(td)

  unless supports_indexes_in_create?
    td.indexes.each do |column_name, index_options|
      add_index(table_name, column_name, **index_options, if_not_exists: td.if_not_exists)
    end
  end

  if supports_comments? && !supports_comments_in_create?
    if table_comment = td.comment.presence
      change_table_comment(table_name, table_comment)
    end

    td.columns.each do |column|
      change_column_comment(table_name, column.name, column.comment) if column.comment.present?
    end
  end

  result
end

#data_source_exists?(name) ⇒ Boolean

Checks to see if the data source name exists on the database.

data_source_exists?(:ebooks)

Returns:

  • (Boolean) 


44
45
46
47
48
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 44

def data_source_exists?(name)
  query_values(data_source_sql(name), "SCHEMA").any? if name.present?
rescue NotImplementedError
  data_sources.include?(name.to_s)
end

#data_sources ⇒ Object

Returns the relation names usable to back Active Record models. For most adapters this means all #tables and #views.



34
35
36
37
38
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 34

def data_sources
  query_values(data_source_sql, "SCHEMA")
rescue NotImplementedError
  tables | views
end

#disable_index(table_name, index_name) ⇒ Object

Prevents an index from being used by queries.

disable_index(:users, :email)

Raises:

  • (NotImplementedError) 


1580
1581
1582
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1580

def disable_index(table_name, index_name)
  raise NotImplementedError, "#{self.class} does not support disabling indexes"
end

#distinct_relation_for_primary_key(relation) ⇒ Object

:nodoc:



1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1458

def distinct_relation_for_primary_key(relation) # :nodoc:
  primary_key_columns = Array(relation.primary_key).map do |column|
    visitor.compile(relation.table[column])
  end

  values = columns_for_distinct(
    primary_key_columns,
    relation.order_values
  )

  limited = relation.reselect(values).distinct!
  limited_ids = select_rows(limited.arel, "SQL").map do |results|
    results.last(Array(relation.primary_key).length) # ignores order values for MySQL and PostgreSQL
  end

  if limited_ids.empty?
    relation.none!
  else
    relation.where!(**Array(relation.primary_key).zip(limited_ids.transpose).to_h)
  end

  relation.limit_value = relation.offset_value = nil
  relation
end

#drop_join_table(table_1, table_2, **options) ⇒ Object

Drops the join table specified by the given arguments. See #create_join_table and #drop_table for details.

Although this command ignores the block if one is given, it can be helpful to provide one in a migration’s change method so it can be reverted. In that case, the block will be used by #create_join_table.



442
443
444
445
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 442

def drop_join_table(table_1, table_2, **options)
  join_table_name = find_join_table_name(table_1, table_2, options)
  drop_table(join_table_name, **options)
end

#drop_table(*table_names, **options) ⇒ Object

Drops a table or tables from the database.

:force

Set to :cascade to drop dependent objects as well. Defaults to false.

:if_exists

Set to true to only drop the table if it exists. Defaults to false.

Although this command ignores most options and the block if one is given, it can be helpful to provide these in a migration’s change method so it can be reverted. In that case, options and the block will be used by #create_table except if you provide more than one table which is not supported.



555
556
557
558
559
560
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 555

def drop_table(*table_names, **options)
  table_names.each do |table_name|
    schema_cache.clear_data_source_cache!(table_name.to_s)
    execute "DROP TABLE#{' IF EXISTS' if options[:if_exists]} #{quote_table_name(table_name)}"
  end
end

#dump_schema_versions ⇒ Object

:nodoc:



1384
1385
1386
1387
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1384

def dump_schema_versions # :nodoc:
  versions = pool.schema_migration.versions
  insert_versions_sql(versions) if versions.any?
end

#enable_index(table_name, index_name) ⇒ Object

Enables an index to be used by queries.

enable_index(:users, :email)

Raises:

  • (NotImplementedError) 


1573
1574
1575
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1573

def enable_index(table_name, index_name)
  raise NotImplementedError, "#{self.class} does not support enabling indexes"
end

#foreign_key_column_for(table_name, column_name) ⇒ Object

:nodoc:



1270
1271
1272
1273
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1270

def foreign_key_column_for(table_name, column_name) # :nodoc:
  name = strip_table_name_prefix_and_suffix(table_name)
  "#{name.singularize}_#{column_name}"
end

#foreign_key_exists?(from_table, to_table = nil, **options) ⇒ Boolean

Checks to see if a foreign key exists on a table for a given foreign key definition.

# Checks to see if a foreign key exists.
foreign_key_exists?(:accounts, :branches)

# Checks to see if a foreign key on a specified column exists.
foreign_key_exists?(:accounts, column: :owner_id)

# Checks to see if a foreign key with a custom name exists.
foreign_key_exists?(:accounts, name: "special_fk_name")

Returns:

  • (Boolean) 


1266
1267
1268
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1266

def foreign_key_exists?(from_table, to_table = nil, **options)
  foreign_key_for(from_table, to_table: to_table, **options).present?
end

#foreign_key_options(from_table, to_table, options) ⇒ Object

:nodoc:



1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1275

def foreign_key_options(from_table, to_table, options) # :nodoc:
  options = options.dup

  if options[:primary_key].is_a?(Array)
    options[:column] ||= options[:primary_key].map do |pk_column|
      foreign_key_column_for(to_table, pk_column)
    end
  else
    options[:column] ||= foreign_key_column_for(to_table, "id")
  end

  options[:name]   ||= foreign_key_name(from_table, options)

  if options[:column].is_a?(Array) || options[:primary_key].is_a?(Array)
    if Array(options[:primary_key]).size != Array(options[:column]).size
      raise ArgumentError, <<~MSG.squish
        For composite primary keys, specify :column and :primary_key, where
        :column must reference all the :primary_key columns from #{to_table.inspect}
      MSG
    end
  end

  options
end

#foreign_keys(table_name) ⇒ Object

Returns an array of foreign keys for the given table. The foreign keys are represented as ForeignKeyDefinition objects.

Raises:

  • (NotImplementedError) 


1131
1132
1133
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1131

def foreign_keys(table_name)
  raise NotImplementedError, "foreign_keys is not implemented"
end

#index_algorithm(algorithm) ⇒ Object

:nodoc:



1533
1534
1535
1536
1537
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1533

def index_algorithm(algorithm) # :nodoc:
  index_algorithms.fetch(algorithm) do
    raise ArgumentError, "Algorithm must be one of the following: #{index_algorithms.keys.map(&:inspect).join(', ')}"
  end if algorithm
end

#index_exists?(table_name, column_name = nil, **options) ⇒ Boolean

Checks to see if an index exists on a table for a given index definition.

# Check an index exists
index_exists?(:suppliers, :company_id)

# Check an index on multiple columns exists
index_exists?(:suppliers, [:company_id, :company_type])

# Check a unique index exists
index_exists?(:suppliers, :company_id, unique: true)

# Check an index with a custom name exists
index_exists?(:suppliers, :company_id, name: "idx_company_id")

# Check a valid index exists (PostgreSQL only)
index_exists?(:suppliers, :company_id, valid: true)

Returns:

  • (Boolean) 


102
103
104
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 102

def index_exists?(table_name, column_name = nil, **options)
  indexes(table_name).any? { |i| i.defined_for?(column_name, **options) }
end

#index_name(table_name, options) ⇒ Object

:nodoc:



1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1020

def index_name(table_name, options) # :nodoc:
  if Hash === options
    if options[:column]
      if options[:_uses_legacy_index_name]
        "index_#{table_name}_on_#{Array(options[:column]) * '_and_'}"
      else
        generate_index_name(table_name, options[:column])
      end
    elsif options[:name]
      options[:name]
    else
      raise ArgumentError, "You must specify the index name"
    end
  else
    index_name(table_name, index_name_options(options))
  end
end

#index_name_exists?(table_name, index_name) ⇒ Boolean

Verifies the existence of an index with a given name.

Returns:

  • (Boolean) 


1039
1040
1041
1042
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1039

def index_name_exists?(table_name, index_name)
  index_name = index_name.to_s
  indexes(table_name).detect { |i| i.name == index_name }
end

#indexes(table_name) ⇒ Object

Returns an array of indexes for the given table.

Raises:

  • (NotImplementedError) 


81
82
83
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 81

def indexes(table_name)
  raise NotImplementedError, "#indexes is not implemented"
end

#internal_string_options_for_primary_key ⇒ Object

:nodoc:



1389
1390
1391
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1389

def internal_string_options_for_primary_key # :nodoc:
  { primary_key: true }
end

#max_index_name_size ⇒ Object

Returns the maximum length of an index name in bytes.



1636
1637
1638
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1636

def max_index_name_size
  62
end

#native_database_types ⇒ Object

Returns a hash of mappings from the abstract data types to the native database types. See TableDefinition#column for details on the recognized abstract data types.



14
15
16
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 14

def native_database_types
  {}
end

#options_include_default?(options) ⇒ Boolean

Returns:

  • (Boolean) 


1546
1547
1548
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1546

def options_include_default?(options)
  options.include?(:default) && !(options[:null] == false && options[:default].nil?)
end

#primary_key(table_name) ⇒ Object

Returns just a table’s primary key



145
146
147
148
149
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 145

def primary_key(table_name)
  pk = primary_keys(table_name)
  pk = pk.first unless pk.size > 1
  pk
end

#quoted_columns_for_index(column_names, options) ⇒ Object

:nodoc:



1539
1540
1541
1542
1543
1544
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1539

def quoted_columns_for_index(column_names, options) # :nodoc:
  quoted_columns = column_names.each_with_object({}) do |name, result|
    result[name.to_sym] = quote_column_name(name).dup
  end
  add_options_for_index_columns(quoted_columns, **options).values.join(", ")
end

#remove_check_constraint(table_name, expression = nil, if_exists: false, **options) ⇒ Object

Removes the given check constraint from the table. Removing a check constraint that does not exist will raise an error.

remove_check_constraint :products, name: "price_check"

To silently ignore a non-existent check constraint rather than raise an error, use the if_exists option.

remove_check_constraint :products, name: "price_check", if_exists: true

The expression parameter will be ignored if present. It can be helpful to provide this in a migration’s change method so it can be reverted. In that case, expression will be used by #add_check_constraint.



1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1353

def remove_check_constraint(table_name, expression = nil, if_exists: false, **options)
  return unless supports_check_constraints?

  return if if_exists && !check_constraint_exists?(table_name, **options)

  chk_name_to_delete = check_constraint_for!(table_name, expression: expression, **options).name

  at = create_alter_table(table_name)
  at.drop_check_constraint(chk_name_to_delete)

  execute schema_creation.accept(at)
end

#remove_column(table_name, column_name, type = nil, **options) ⇒ Object

Removes the column from the table definition.

remove_column(:suppliers, :qualification)

The type and options parameters will be ignored if present. It can be helpful to provide these in a migration’s change method so it can be reverted. In that case, type and options will be used by #add_column. Depending on the database you’re using, indexes using this column may be automatically removed or modified to remove this column from the index.

If the options provided include an if_exists key, it will be used to check if the column does not exist. This will silently ignore the migration rather than raising if the column was already removed.

remove_column(:suppliers, :qualification, if_exists: true)



714
715
716
717
718
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 714

def remove_column(table_name, column_name, type = nil, **options)
  return if options[:if_exists] == true && !column_exists?(table_name, column_name)

  execute "ALTER TABLE #{quote_table_name(table_name)} #{remove_column_for_alter(table_name, column_name, type, **options)}"
end

#remove_columns(table_name, *column_names, type: nil, **options) ⇒ Object

Removes the given columns from the table definition.

remove_columns(:suppliers, :qualification, :experience)

type and other column options can be passed to make migration reversible.

remove_columns(:suppliers, :qualification, :experience, type: :string, null: false)



690
691
692
693
694
695
696
697
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 690

def remove_columns(table_name, *column_names, type: nil, **options)
  if column_names.empty?
    raise ArgumentError.new("You must specify at least one column name. Example: remove_columns(:people, :first_name)")
  end

  remove_column_fragments = remove_columns_for_alter(table_name, *column_names, type: type, **options)
  execute "ALTER TABLE #{quote_table_name(table_name)} #{remove_column_fragments.join(', ')}"
end

#remove_constraint(table_name, constraint_name) ⇒ Object

:nodoc:



1377
1378
1379
1380
1381
1382
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1377

def remove_constraint(table_name, constraint_name) # :nodoc:
  at = create_alter_table(table_name)
  at.drop_constraint(constraint_name)

  execute schema_creation.accept(at)
end

#remove_foreign_key(from_table, to_table = nil, **options) ⇒ Object

Removes the given foreign key from the table. Any option parameters provided will be used to re-add the foreign key in case of a migration rollback. It is recommended that you provide any options used when creating the foreign key so that the migration can be reverted properly.

Removes the foreign key on accounts.branch_id.

remove_foreign_key :accounts, :branches

Removes the foreign key on accounts.owner_id.

remove_foreign_key :accounts, column: :owner_id

Removes the foreign key on accounts.owner_id.

remove_foreign_key :accounts, to_table: :owners

Removes the foreign key named special_fk_name on the accounts table.

remove_foreign_key :accounts, name: :special_fk_name

Checks if the foreign key exists before trying to remove it. Will silently ignore indexes that don’t exist.

remove_foreign_key :accounts, :branches, if_exists: true

The options hash accepts the same keys as SchemaStatements#add_foreign_key with an addition of

:to_table

The name of the table that contains the referenced primary key.



1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1243

def remove_foreign_key(from_table, to_table = nil, **options)
  return unless use_foreign_keys?
  return if options.delete(:if_exists) == true && !foreign_key_exists?(from_table, to_table, **options.slice(:column))

  fk_name_to_delete = foreign_key_for!(from_table, to_table: to_table, **options).name

  at = create_alter_table from_table
  at.drop_foreign_key fk_name_to_delete

  execute schema_creation.accept(at)
end

#remove_index(table_name, column_name = nil, **options) ⇒ Object

Removes the given index from the table.

Removes the index on branch_id in the accounts table if exactly one such index exists.

remove_index :accounts, :branch_id

Removes the index on branch_id in the accounts table if exactly one such index exists.

remove_index :accounts, column: :branch_id

Removes the index on branch_id and party_id in the accounts table if exactly one such index exists.

remove_index :accounts, column: [:branch_id, :party_id]

Removes the index named by_branch_party in the accounts table.

remove_index :accounts, name: :by_branch_party

Removes the index on branch_id named by_branch_party in the accounts table.

remove_index :accounts, :branch_id, name: :by_branch_party

Checks if the index exists before trying to remove it. Will silently ignore indexes that don’t exist.

remove_index :accounts, if_exists: true

Removes the index named by_branch_party in the accounts table concurrently.

remove_index :accounts, name: :by_branch_party, algorithm: :concurrently

Note: only supported by PostgreSQL.

Concurrently removing an index is not supported in a transaction.

For more information see the “Transactional Migrations” section.



994
995
996
997
998
999
1000
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 994

def remove_index(table_name, column_name = nil, **options)
  return if options[:if_exists] && !index_exists?(table_name, column_name, **options)

  index_name = index_name_for_remove(table_name, column_name, options)

  execute "DROP INDEX #{quote_column_name(index_name)} ON #{quote_table_name(table_name)}"
end

#remove_reference(table_name, ref_name, foreign_key: false, polymorphic: false, **options) ⇒ Object Also known as: remove_belongs_to

Removes the reference(s). Also removes a type column if one exists.

Remove the reference
remove_reference(:products, :user, index: false)
Remove polymorphic reference
remove_reference(:products, :supplier, polymorphic: true)
Remove the reference with a foreign key
remove_reference(:products, :user, foreign_key: true)



1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1110

def remove_reference(table_name, ref_name, foreign_key: false, polymorphic: false, **options)
  conditional_options = options.slice(:if_exists, :if_not_exists)

  if foreign_key
    reference_name = Base.pluralize_table_names ? ref_name.to_s.pluralize : ref_name
    if foreign_key.is_a?(Hash)
      foreign_key_options = foreign_key.merge(conditional_options)
    else
      foreign_key_options = { to_table: reference_name, **conditional_options }
    end
    foreign_key_options[:column] ||= "#{ref_name}_id"
    remove_foreign_key(table_name, **foreign_key_options)
  end

  remove_column(table_name, "#{ref_name}_id", **conditional_options)
  remove_column(table_name, "#{ref_name}_type", **conditional_options) if polymorphic
end

#remove_timestamps(table_name, **options) ⇒ Object

Removes the timestamp columns (created_at and updated_at) from the table definition.

remove_timestamps(:suppliers)



1497
1498
1499
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1497

def remove_timestamps(table_name, **options)
  remove_columns table_name, :updated_at, :created_at
end

#rename_column(table_name, column_name, new_column_name) ⇒ Object

Renames a column.

rename_column(:suppliers, :description, :name)

Raises:

  • (NotImplementedError) 


781
782
783
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 781

def rename_column(table_name, column_name, new_column_name)
  raise NotImplementedError, "rename_column is not implemented"
end

#rename_index(table_name, old_name, new_name) ⇒ Object

Renames an index.

Rename the index_people_on_last_name index to index_users_on_last_name:

rename_index :people, 'index_people_on_last_name', 'index_users_on_last_name'



1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1008

def rename_index(table_name, old_name, new_name)
  old_name = old_name.to_s
  new_name = new_name.to_s
  validate_index_length!(table_name, new_name)

  # this is a naive implementation; some DBs may support this more efficiently (PostgreSQL, for instance)
  old_index_def = indexes(table_name).detect { |i| i.name == old_name }
  return unless old_index_def
  add_index(table_name, old_index_def.columns, name: new_name, unique: old_index_def.unique)
  remove_index(table_name, name: old_name)
end

#rename_table(table_name, new_name) ⇒ Object

Renames a table.

rename_table('octopuses', 'octopi')

Raises:

  • (NotImplementedError) 


539
540
541
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 539

def rename_table(table_name, new_name, **)
  raise NotImplementedError, "rename_table is not implemented"
end

#schema_creation ⇒ Object

Returns an instance of SchemaCreation, which can be used to visit a schema definition object and return DDL.



1594
1595
1596
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1594

def schema_creation # :nodoc:
  SchemaCreation.new(self)
end

#table_alias_for(table_name) ⇒ Object

Truncates a table alias according to the limits of the current adapter.



28
29
30
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 28

def table_alias_for(table_name)
  table_name[0...table_alias_length].tr(".", "_")
end

#table_comment(table_name) ⇒ Object

Returns the table comment that’s stored in database metadata.



23
24
25
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 23

def table_comment(table_name)
  nil
end

#table_exists?(table_name) ⇒ Boolean

Checks to see if the table table_name exists on the database.

table_exists?(:developers)

Returns:

  • (Boolean) 


59
60
61
62
63
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 59

def table_exists?(table_name)
  query_values(data_source_sql(table_name, type: "BASE TABLE"), "SCHEMA").any? if table_name.present?
rescue NotImplementedError
  tables.include?(table_name.to_s)
end

#table_options(table_name) ⇒ Object 



18
19
20
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 18

def table_options(table_name)
  nil
end

#tables ⇒ Object

Returns an array of table names defined in the database.



51
52
53
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 51

def tables
  query_values(data_source_sql(type: "BASE TABLE"), "SCHEMA")
end

#type_to_sql(type, limit: nil, precision: nil, scale: nil) ⇒ Object

:nodoc:



1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1414

def type_to_sql(type, limit: nil, precision: nil, scale: nil, **) # :nodoc:
  type = type.to_sym if type
  if native = native_database_types[type]
    column_type_sql = (native.is_a?(Hash) ? native[:name] : native).dup

    if type == :decimal # ignore limit, use precision and scale
      scale ||= native[:scale]

      if precision ||= native[:precision]
        if scale
          column_type_sql << "(#{precision},#{scale})"
        else
          column_type_sql << "(#{precision})"
        end
      elsif scale
        raise ArgumentError, "Error adding decimal column: precision cannot be empty if scale is specified"
      end

    elsif [:datetime, :timestamp, :time, :interval].include?(type) && precision ||= native[:precision]
      if (0..6) === precision
        column_type_sql << "(#{precision})"
      else
        raise ArgumentError, "No #{native[:name]} type has precision of #{precision}. The allowed range of precision is from 0 to 6"
      end
    elsif (type != :primary_key) && (limit ||= native.is_a?(Hash) && native[:limit])
      column_type_sql << "(#{limit})"
    end

    column_type_sql
  else
    type.to_s
  end
end

#update_table_definition(table_name, base) ⇒ Object

:nodoc:



1501
1502
1503
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1501

def update_table_definition(table_name, base) # :nodoc:
  Table.new(table_name, base)
end

#use_foreign_keys? ⇒ Boolean

Returns:

  • (Boolean) 


1588
1589
1590
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1588

def use_foreign_keys?
  supports_foreign_keys? && foreign_keys_enabled?
end

#valid_column_definition_options ⇒ Object

:nodoc:



1627
1628
1629
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1627

def valid_column_definition_options # :nodoc:
  ColumnDefinition::OPTION_NAMES
end

#valid_primary_key_options ⇒ Object

:nodoc:



1631
1632
1633
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1631

def valid_primary_key_options # :nodoc:
  [:limit, :default, :precision]
end

#valid_table_definition_options ⇒ Object

:nodoc:



1623
1624
1625
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1623

def valid_table_definition_options # :nodoc:
  [:temporary, :if_not_exists, :options, :as, :comment, :charset, :collation]
end

#view_exists?(view_name) ⇒ Boolean

Checks to see if the view view_name exists on the database.

view_exists?(:ebooks)

Returns:

  • (Boolean) 


74
75
76
77
78
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 74

def view_exists?(view_name)
  query_values(data_source_sql(view_name, type: "VIEW"), "SCHEMA").any? if view_name.present?
rescue NotImplementedError
  views.include?(view_name.to_s)
end

#views ⇒ Object

Returns an array of view names defined in the database.



66
67
68
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 66

def views
  query_values(data_source_sql(type: "VIEW"), "SCHEMA")
end