跳至内容 跳至搜索
方法
A
B
C
D
F
I
M
N
O
P
R
T
U
V

实例公共方法

add_belongs_to(table_name, ref_name, **options)

别名:add_reference

add_check_constraint(table_name, expression, if_not_exists: false, **options)

向表添加新的检查约束。expression 是可验证布尔条件的 String 表示形式。

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

生成

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

options 哈希可以包含以下键

:name

约束名称。默认为 chk_rails_<identifier>

:if_not_exists

如果约束已存在,则静默忽略,而不是引发错误。

:validate

(仅限 PostgreSQL)指定是否应验证约束。默认为 true

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1260
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)

table_name 添加一个名为 column_name 的新 type 列。

请参阅 ActiveRecord::ConnectionAdapters::TableDefinition.column

type 参数通常是迁移本机类型之一,即以下类型之一::primary_key:string:text:integer:bigint:float:decimal:numeric:datetime:time:date:binary:blob:boolean

只要数据库支持,您就可以使用此列表中没有的类型(例如,MySQL 中的“多边形”),但这不会与数据库无关,通常应避免使用。

可用的选项如下(默认情况下没有这些选项)

  • :comment - 指定列的注释。某些后端会忽略此选项。

  • :collation - 指定 :string:text 列的排序规则。如果未指定,则该列将与表具有相同的排序规则。

  • :default - 列的默认值。对于 NULL,请使用 nil

  • :limit - 请求最大列长度。这是 :string 列的字符数,以及 :text:binary:blob:integer 列的字节数。某些后端会忽略此选项。

  • :null - 允许或不允许列中的 NULL 值。

  • :precision - 指定 :decimal:numeric:datetime:time 列的精度。

  • :scale - 指定 :decimal:numeric 列的刻度。

  • :if_not_exists - 指定列是否已存在以避免重新添加。这将避免重复的列错误。

注意:精度是有效数字的总数,刻度是小数点后可以存储的数字数。例如,数字 123.45 的精度为 5,刻度为 2。精度为 5、刻度为 2 的小数范围为 -999.99 至 999.99。

请注意不同 RDBMS 实现对 :decimal 列的行为

  • SQL 标准规定默认刻度应为 0,:scale <= :precision,并且对 :precision 的要求不作任何评论。

  • MySQL::precision [1..65],:scale [0..30]。默认值为 (10,0)。

  • PostgreSQL::precision [1..infinity],:scale [0..infinity]。无默认值。

  • SQLite3:对 :precision:scale 没有限制,但支持的最大 :precision 为 16。无默认值。

  • Oracle::precision [1..38],:scale [-84..127]。默认值为 (38,0)。

  • SqlServer::precision [1..38],:scale [0..38]。默认值为 (38,0)。

示例

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 620
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_foreign_key(from_table, to_table, **options)

添加一个新的外键。from_table 是带有键列的表,to_table 包含引用的主键。

外键将以以下模式命名:fk_rails_<identifier>identifier 是一个 10 个字符长的字符串,它是由 from_tablecolumn 确定性生成的。可以使用 :name 选项指定自定义名称。

创建简单外键
add_foreign_key :articles, :authors

生成

ALTER TABLE "articles" ADD CONSTRAINT fk_rails_e74ce85cbc FOREIGN KEY ("author_id") REFERENCES "authors" ("id")
创建外键,如果外键存在则忽略方法调用
add_foreign_key(:articles, :authors, if_not_exists: true)
在特定列上创建外键
add_foreign_key :articles, :users, column: :author_id, primary_key: "lng_id"

生成

ALTER TABLE "articles" ADD CONSTRAINT fk_rails_58ca3d3a82 FOREIGN KEY ("author_id") REFERENCES "users" ("lng_id")
创建复合外键
Assuming "carts" table has "(shop_id, user_id)" as a primary key.

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

生成

ALTER TABLE "orders" ADD CONSTRAINT fk_rails_6f5e4cb3a4 FOREIGN KEY ("cart_shop_id", "cart_user_id") REFERENCES "carts" ("shop_id", "user_id")
创建级联外键
add_foreign_key :articles, :authors, on_delete: :cascade

生成

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

options 哈希可以包含以下键

:column

from_table 上的外键列名。默认为 to_table.singularize + "_id"。传递一个数组以创建复合外键。

:primary_key

to_table 上的主键列名。默认为 id。传递一个数组以创建复合外键。

:name

约束名称。默认为 fk_rails_<identifier>

:on_delete

ON DELETE 发生的操作。有效值为 :nullify:cascade:restrict

:on_update

ON UPDATE 发生的操作。有效值为 :nullify:cascade:restrict

:if_not_exists

指定外键是否已存在,以避免再次尝试添加它。这将避免重复列错误。

:validate

(仅限 PostgreSQL)指定是否应验证约束。默认为 true

:deferrable

(仅限 PostgreSQL)指定外键是否应可延迟。有效值为布尔值或 :deferred:immediate 以指定默认行为。默认为 false

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1140
def add_foreign_key(from_table, to_table, **options)
  return unless use_foreign_keys?
  return if options[:if_not_exists] == true && foreign_key_exists?(from_table, to_table, **options.slice(:column))

  options = foreign_key_options(from_table, to_table, options)
  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)

向表中添加一个新索引。column_name 可以是单个 Symbol,或 Array 的 Symbol。

索引将以表和列名命名,除非你将 :name 作为选项传递。

创建简单索引
add_index(:suppliers, :name)

生成

CREATE INDEX index_suppliers_on_name ON suppliers(name)
创建已存在的索引
add_index(:suppliers, :name, if_not_exists: true)

生成

CREATE INDEX IF NOT EXISTS index_suppliers_on_name ON suppliers(name)

注意:不受 MySQL 支持。

创建唯一索引
add_index(:accounts, [:branch_id, :party_id], unique: true)

生成

CREATE UNIQUE INDEX index_accounts_on_branch_id_and_party_id ON accounts(branch_id, party_id)
创建命名索引
add_index(:accounts, [:branch_id, :party_id], unique: true, name: 'by_branch_party')

生成

CREATE UNIQUE INDEX by_branch_party ON accounts(branch_id, party_id)
创建具有特定键长度的索引
add_index(:accounts, :name, name: 'by_name', length: 10)

生成

CREATE INDEX by_name ON accounts(name(10))
为多个键创建具有特定键长度的索引
add_index(:accounts, [:name, :surname], name: 'by_name_surname', length: {name: 10, surname: 15})

生成

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

注意:仅受 MySQL 支持。

创建具有排序顺序的索引(desc 或 asc,asc 为默认值)
add_index(:accounts, [:branch_id, :party_id, :surname], name: 'by_branch_desc_party', order: {branch_id: :desc, party_id: :asc})

生成

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

注意:MySQL 仅从 8.0.1 起支持索引顺序(早期版本接受语法但忽略它)。

创建部分索引
add_index(:accounts, [:branch_id, :party_id], unique: true, where: "active")

生成

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

注意:部分索引仅受 PostgreSQL 和 SQLite 支持。

创建包含其他列的索引
add_index(:accounts, :branch_id,  include: :party_id)

生成

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

注意:仅受 PostgreSQL 支持。

使用特定方法创建索引
add_index(:developers, :name, using: 'btree')

生成

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

注意:仅受 PostgreSQL 和 MySQL 支持

使用特定运算符类创建索引
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

注意:仅受 PostgreSQL 支持

使用特定类型创建索引
add_index(:developers, :name, type: :fulltext)

生成

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

注意:仅受 MySQL 支持。

使用特定算法创建索引
add_index(:developers, :name, algorithm: :concurrently)
# CREATE INDEX CONCURRENTLY developers_on_name on developers (name)

注意:仅受 PostgreSQL 支持。

在事务中并发添加索引不受支持。

有关更多信息,请参阅 “事务迁移”部分

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 886
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_reference(table_name, ref_name, **options)

添加引用。默认情况下,引用列为 bigint,可以使用 :type 选项指定不同的类型。如果提供了 :polymorphic 选项,则可以选择性地添加 _type 列。

options 哈希可以包含以下键

:type

引用列类型。默认为 :bigint

:index

添加适当的索引。默认为 true。有关此选项的用法,请参阅 add_index

:foreign_key

添加适当的外键约束。默认为 false,传递 true 以添加。如果无法从关联中推断出联接表,请使用 :to_table 传递适当的表名。

:polymorphic

是否应添加额外的 _type 列。默认为 false。

:null

该列是否允许空值。默认为 true。

创建一个没有索引的 user_id bigint 列
add_reference(:products, :user, index: false)
创建一个 user_id 字符串列
add_reference(:products, :user, type: :string)
创建 supplier_id、supplier_type 列
add_reference(:products, :supplier, polymorphic: true)
创建一个具有唯一索引的 supplier_id 列
add_reference(:products, :supplier, index: { unique: true })
创建一个具有命名索引的 supplier_id 列
add_reference(:products, :supplier, index: { name: "my_supplier_index" })
创建一个 supplier_id 列和适当的外键
add_reference(:products, :supplier, foreign_key: true)
创建一个 supplier_id 列和一个指向 firms 表的外键
add_reference(:products, :supplier, foreign_key: { to_table: :firms })
别名:add_belongs_to
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1030
def add_reference(table_name, ref_name, **options)
  ReferenceDefinition.new(ref_name, **options).add(table_name, self)
end

add_timestamps(table_name, **options)

table_name添加时间戳(created_atupdated_at)列。其他选项(如:null)将转发到add_column

add_timestamps(:suppliers, null: true)
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1419
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)

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1325
def assume_migrated_upto_version(version)
  version = version.to_i
  sm_table = quote_table_name(schema_migration.table_name)

  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_create_table_definition(table_name, id: :primary_key, primary_key: nil, force: nil, **options)

返回一个TableDefinition对象,其中包含有关将相同参数传递给create_table时将创建的表的的信息。有关传递table_name和其他可以传递的其他选项的信息,请参阅create_table

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 328
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

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

根据新选项更改列的定义。有关你可以使用的选项的详细信息,请参阅TableDefinition#column

change_column(:suppliers, :name, :string, limit: 80)
change_column(:accounts, :description, :text)
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 695
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)

更改列的注释,如果为nil,则删除注释。

传递包含:from:to的哈希将使此更改在迁移中可逆

change_column_comment(:posts, :state, from: "old_comment", to: "new_comment")
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1497
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)

为列设置新的默认值

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

将默认值设置为 nil 会有效地删除默认值

change_column_default(:users, :email, nil)

传递包含:from:to的哈希将使此更改在迁移中可逆

change_column_default(:posts, :state, from: nil, to: "draft")
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 713
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)

设置或删除列上的 NOT NULL 约束。null 标志指示值是否可以为 NULL。例如

change_column_null(:users, :nickname, false)

表示昵称不能为 NULL(添加约束),而

change_column_null(:users, :nickname, true)

允许它们为 NULL(删除约束)。

该方法接受一个可选的第四个参数,以用其他值替换现有的 NULL。如果需要,在启用约束时使用该参数,因为否则那些行将无效。

请注意,第四个参数不会设置列的默认值。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 742
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)

用于更改 table 中列的块。

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

options 哈希可以包含以下键

:bulk

将其设置为 true 以使其成为批量更改查询,例如

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

默认为 false。

仅在 MySQL 和 PostgreSQL 适配器上受支持,在其他地方被忽略。

添加列
change_table(:suppliers) do |t|
  t.column :name, :string, limit: 60
end
更改列的类型
change_table(:suppliers) do |t|
  t.change :metadata, :json
end
添加 2 个整数列
change_table(:suppliers) do |t|
  t.integer :width, :height, null: false, default: 0
end
添加 created_at/updated_at 列
change_table(:suppliers) do |t|
  t.timestamps
end
添加外键列
change_table(:suppliers) do |t|
  t.references :company
end

创建 company_id(bigint) 列。

添加多态外键列
change_table(:suppliers) do |t|
  t.belongs_to :company, polymorphic: true
end

创建 company_type(varchar)company_id(bigint) 列。

删除列
change_table(:suppliers) do |t|
  t.remove :company
end
删除多列
change_table(:suppliers) do |t|
  t.remove :company_id
  t.remove :width, :height
end
删除索引
change_table(:suppliers) do |t|
  t.remove_index :company_id
end

另请参见 Table,了解所有列转换的详细信息。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 496
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)

更改表的注释,如果为 nil,则移除注释。

传递包含:from:to的哈希将使此更改在迁移中可逆

change_table_comment(:posts, from: "old_comment", to: "new_comment")
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1487
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)

检查表中是否存在针对给定检查约束定义的检查约束。

check_constraint_exists?(:products, name: "price_check")
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1309
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_constraints(table_name)

返回给定表的检查约束数组。检查约束表示为 CheckConstraintDefinition 对象。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1240
def check_constraints(table_name)
  raise NotImplementedError
end

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

检查给定表中是否存在列。

# 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)
# 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)

返回 table_name 指定的表的 Column 对象数组。

# 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

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

使用前两个参数的词法顺序创建的新连接表。这些参数可以是 StringSymbol

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

您可以传递一个包含以下键的options哈希

:table_name

设置表名,覆盖默认值。

:column_options

要附加到列定义的任何额外选项。

:options

要附加到表定义的任何额外选项。

:temporary

创建一个临时表。

:force

设置为 true 以在创建表之前删除该表。默认为 false。

请注意,create_join_table 默认情况下不会创建任何索引;您可以使用其块形式自己执行此操作

create_join_table :products, :categories do |t|
  t.index :product_id
  t.index :category_id
end
将后端特定选项添加到生成的 SQL(MySQL
create_join_table(:assemblies, :parts, options: 'ENGINE=InnoDB DEFAULT CHARSET=utf8')

生成

CREATE TABLE assemblies_parts (
  assembly_id bigint NOT NULL,
  part_id bigint NOT NULL,
) ENGINE=InnoDB DEFAULT CHARSET=utf8
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 375
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_table(table_name, id: :primary_key, primary_key: nil, force: nil, **options, &block)

使用名称table_name创建一个新表。table_name可以是 StringSymbol

有两种使用 create_table 的方法。您可以使用块形式或常规形式,如下所示

块形式

# 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

块形式,带有缩写

# 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

常规形式

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

options 哈希可以包含以下键

:id

是否自动添加主键列。默认为 true。用于 ActiveRecord::Base.has_and_belongs_to_many 的联接表应将其设置为 false。

可以使用 Symbol 来指定生成的主键列的类型。

:primary_key

主键的名称(如果要自动添加主键)。默认为id。如果 :id 为 false,则忽略此选项。

如果传递了一个数组,则将创建一个复合主键。

请注意,Active Record 模型将自动检测其主键。可以通过在模型上使用 self.primary_key= 来明确定义键,从而避免这种情况。

:options

要附加到表定义的任何额外选项。

:temporary

创建一个临时表。

:force

设置为 true 以在创建表之前删除该表。设置为 :cascade 以同时删除依赖对象。默认为 false。

:if_not_exists

设置为 true 以避免在表已存在时引发错误。默认为 false。

:as

用于生成表的 SQL。使用此选项时,将忽略块以及 :id:primary_key 选项。

将后端特定选项添加到生成的 SQL(MySQL
create_table(:suppliers, options: 'ENGINE=InnoDB DEFAULT CHARSET=utf8mb4')

生成

CREATE TABLE suppliers (
  id bigint auto_increment PRIMARY KEY
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
重命名主键列
create_table(:objects, primary_key: 'guid') do |t|
  t.column :name, :string, limit: 80
end

生成

CREATE TABLE objects (
  guid bigint auto_increment PRIMARY KEY,
  name varchar(80)
)
更改主键列类型
create_table(:tags, id: :string) do |t|
  t.column :label, :string
end

生成

CREATE TABLE tags (
  id varchar PRIMARY KEY,
  label varchar
)
创建一个复合主键
create_table(:orders, primary_key: [:product_id, :client_id]) do |t|
  t.belongs_to :product
  t.belongs_to :client
end

生成

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);
不添加主键列
create_table(:categories_suppliers, id: false) do |t|
  t.column :category_id, :bigint
  t.column :supplier_id, :bigint
end

生成

CREATE TABLE categories_suppliers (
  category_id bigint,
  supplier_id bigint
)
基于查询创建一个临时表
create_table(:long_query, temporary: true,
  as: "SELECT * FROM orders INNER JOIN line_items ON order_id=orders.id")

生成

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

另请参阅 TableDefinition#column,了解有关如何创建列的详细信息。

# 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]
  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)

检查数据源name是否存在于数据库中。

data_source_exists?(:ebooks)
# 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()

返回可用于支持 ActiveRecord 模型的关系名称。对于大多数适配器,这意味着所有tablesviews

# 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

drop_join_table(table_1, table_2, **options)

删除由给定参数指定的连接表。有关详细信息,请参见create_join_tabledrop_table

虽然此命令忽略了给定的块(如果有),但在迁移的change方法中提供一个块可能会有所帮助,以便可以还原它。在这种情况下,该块将由create_join_table使用。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 413
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_name, **options)

从数据库中删除一张表。

:force

设置为:cascade以同时删除依赖对象。默认为 false。

:if_exists

设置为 true,仅当表存在时才删除该表。默认为 false。

虽然此命令忽略大多数 options 和给定的块(如果存在),但将其提供给迁移的 change 方法可能会有所帮助,以便可以还原它。在这种情况下,options 和块将由 create_table 使用。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 526
def drop_table(table_name, **options)
  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

foreign_key_exists?(from_table, to_table = nil, **options)

检查表上是否存在给定外键定义的外键。

# 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")
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1204
def foreign_key_exists?(from_table, to_table = nil, **options)
  foreign_key_for(from_table, to_table: to_table, **options).present?
end

foreign_keys(table_name)

返回给定表的数组外键。外键表示为 ForeignKeyDefinition 对象。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1070
def foreign_keys(table_name)
  raise NotImplementedError, "foreign_keys is not implemented"
end

index_exists?(table_name, column_name, **options)

检查表上是否存在给定索引定义的索引。

# 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)
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 102
def index_exists?(table_name, column_name, **options)
  indexes(table_name).any? { |i| i.defined_for?(column_name, **options) }
end

index_name_exists?(table_name, index_name)

验证具有给定名称的索引的存在。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 978
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)

返回给定表的索引数组。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 81
def indexes(table_name)
  raise NotImplementedError, "#indexes is not implemented"
end

max_index_name_size()

以字节为单位返回索引名称的最大长度。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1553
def max_index_name_size
  62
end

native_database_types()

返回从抽象数据类型到本机数据库类型的映射哈希。有关已识别的抽象数据类型的详细信息,请参阅 TableDefinition#column

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 14
def native_database_types
  {}
end

options_include_default?(options)

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1477
def options_include_default?(options)
  options.include?(:default) && !(options[:null] == false && options[:default].nil?)
end

primary_key(table_name)

仅返回表的唯一键

# 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

remove_belongs_to(table_name, ref_name, foreign_key: false, polymorphic: false, **options)

别名:remove_reference

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

从表中移除给定的检查约束。移除不存在的检查约束将引发错误。

remove_check_constraint :products, name: "price_check"

要静默忽略不存在的检查约束而不是引发错误,请使用 if_exists 选项。

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

如果存在,将忽略 expression 参数。在迁移的 change 方法中提供此参数可能会有所帮助,以便可以还原。在这种情况下,expression 将由 add_check_constraint 使用。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1291
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)

从表定义中删除列。

remove_column(:suppliers, :qualification)

如果存在,typeoptions 参数将被忽略。在迁移的 change 方法中提供这些参数可能会有所帮助,以便可以还原。在这种情况下,typeoptions 将被 add_column 使用。根据所使用的数据库,使用此列的索引可能会自动删除或修改以从索引中删除此列。

如果提供的选项包括 if_exists 键,则将使用它来检查该列是否存在。如果该列已被使用,这将静默忽略迁移,而不是引发异常。

remove_column(:suppliers, :qualification, if_exists: true)
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 683
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)

从表定义中删除给定的列。

remove_columns(:suppliers, :qualification, :experience)

可以传递 type 和其他列选项以使迁移可逆。

remove_columns(:suppliers, :qualification, :experience, type: :string, null: false)
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 659
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_foreign_key(from_table, to_table = nil, **options)

从表中删除给定的外键。如果迁移回滚,将使用任何提供的选项参数重新添加外键。建议您提供创建外键时使用的任何选项,以便可以正确地还原迁移。

删除 accounts.branch_id 上的外键。

remove_foreign_key :accounts, :branches

删除 accounts.owner_id 上的外键。

remove_foreign_key :accounts, column: :owner_id

删除 accounts.owner_id 上的外键。

remove_foreign_key :accounts, to_table: :owners

删除 accounts 表上名为 special_fk_name 的外键。

remove_foreign_key :accounts, name: :special_fk_name

在尝试删除外键之前检查外键是否存在。将静默忽略不存在的索引。

remove_foreign_key :accounts, :branches, if_exists: true

options 哈希接受与 SchemaStatements#add_foreign_key 相同的键,并添加

:to_table

包含引用的主键的表的名称。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1181
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)

  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)

从表中删除给定的索引。

如果 accounts 表中恰好存在一个这样的索引,则删除 branch_id 上的索引。

remove_index :accounts, :branch_id

如果 accounts 表中恰好存在一个这样的索引,则删除 branch_id 上的索引。

remove_index :accounts, column: :branch_id

如果 accounts 表中恰好存在一个这样的索引,则删除 branch_idparty_id 上的索引。

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

删除 accounts 表中名为 by_branch_party 的索引。

remove_index :accounts, name: :by_branch_party

删除 accounts 表中名为 by_branch_partybranch_id 上的索引。

remove_index :accounts, :branch_id, name: :by_branch_party

在尝试删除索引之前检查索引是否存在。将静默忽略不存在的索引。

remove_index :accounts, if_exists: true

accounts 表中 concurrently 删除名为 by_branch_party 的索引。

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

注意:仅受 PostgreSQL 支持。

在事务中不支持并发删除索引。

有关更多信息,请参阅 “事务迁移”部分

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 937
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)

移除引用。如果存在,还将移除一个 type 列。

移除引用
remove_reference(:products, :user, index: false)
移除多态引用
remove_reference(:products, :supplier, polymorphic: true)
移除带有外键的引用
remove_reference(:products, :user, foreign_key: true)
也别名为:remove_belongs_to
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1049
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)

从表定义中移除时间戳列(created_atupdated_at)。

remove_timestamps(:suppliers)
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1428
def remove_timestamps(table_name, **options)
  remove_columns table_name, :updated_at, :created_at
end

rename_column(table_name, column_name, new_column_name)

重命名一个列。

rename_column(:suppliers, :description, :name)
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 750
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)

重命名一个索引。

index_people_on_last_name 索引重命名为 index_users_on_last_name

rename_index :people, 'index_people_on_last_name', 'index_users_on_last_name'
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 951
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, **)

重命名一个表。

rename_table('octopuses', 'octopi')
# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 510
def rename_table(table_name, new_name, **)
  raise NotImplementedError, "rename_table is not implemented"
end

table_alias_for(table_name)

根据当前适配器的限制截断表别名。

# 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)

返回存储在数据库元数据中的表注释。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 23
def table_comment(table_name)
  nil
end

table_exists?(table_name)

检查数据库中是否存在表table_name

table_exists?(:developers)
# 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)

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 18
def table_options(table_name)
  nil
end

tables()

返回数据库中定义的表名数组。

# 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

use_foreign_keys?()

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1505
def use_foreign_keys?
  supports_foreign_keys? && foreign_keys_enabled?
end

view_exists?(view_name)

检查数据库中是否存在视图view_name

view_exists?(:ebooks)
# 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()

返回数据库中定义的视图名数组。

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 66
def views
  query_values(data_source_sql(type: "VIEW"), "SCHEMA")
end