Ecto Migrator

生成迁移文件

基于自然语言生成

解析用户描述并生成迁移文件。常见模式如下：

文件命名规范

mix ecto.gen.migration 
# 生成路径：priv/repo/migrations/YYYYMMDDHHMMSS_.exs

命名惯例：create_

迁移模板

defmodule MyApp.Repo.Migrations.CreateUsers do
  use Ecto.Migration

  def change do
    create table(:users, primary_key: false) do
      add :id, :binary_id, primary_key: true
      add :email, :string, null: false
      add :name, :string, null: false
      add :role, :string, null: false, default: "member"
      add :metadata, :map, default: %{}
      add :tenant_id, :binary_id, null: false

      add :team_id, references(:teams, type: :binary_id, on_delete: :delete_all)

      timestamps(type: :utc_datetime_usec)
    end

    create unique_index(:users, [:tenant_id, :email])
    create index(:users, [:tenant_id])
    create index(:users, [:team_id])
  end
end

字段类型

完整类型映射与使用建议请参阅 references/column-types.md。

关键决策：

• ID 字段：使用 :binary_id（UUID）—— 表定义需设 primary_key: false，手动添加 :id 字段。
• 金额字段：使用 :integer（单位为分）或 :decimal —— 禁止使用 :float。
• 时间戳：始终使用 timestamps(type: :utc_datetime_usec)。
• 枚举类型：使用 :string 配合应用层的 Ecto.Enum —— 避免使用 PostgreSQL 原生 enum（难以迁移）。
• JSON 数据：使用 :map（对应 PostgreSQL 的 jsonb 类型）。
• 数组字段：使用 {:array, :string} 等形式。

索引策略

详细索引设计指南请参阅 references/index-patterns.md。

何时添加索引

以下情况必须添加索引：

• 外键字段（以 _id 结尾的列）
• tenant_id（复合索引中应作为首列）
• 用于 WHERE 子句的字段
• 用于 ORDER BY 的字段
• 唯一性约束所涉及的字段

索引类型

# 标准 B-tree 索引
create index(:users, [:tenant_id])

# 唯一索引
create unique_index(:users, [:tenant_id, :email])

# 部分索引（条件索引）
create index(:orders, [:status], where: "status != 'completed'", name: :orders_active_status_idx)

# GIN 索引（用于 jsonb 字段）
create index(:events, [:metadata], using: :gin)

# GIN 索引（用于数组字段）
create index(:posts, [:tags], using: :gin)

# 复合索引
create index(:orders, [:tenant_id, :status, :inserted_at])

# 并发索引（不锁表 —— 应单独放在一个迁移中）
@disable_ddl_transaction true
@disable_migration_lock true

def change do
  create index(:users, [:email], concurrently: true)
end

约束条件

# 检查约束
create constraint(:orders, :amount_must_be_positive, check: "amount > 0")

# 排他约束（需启用 btree_gist 扩展）
execute "CREATE EXTENSION IF NOT EXISTS btree_gist", ""
create constraint(:reservations, :no_overlapping_bookings,
  exclude: ~s|gist (room_id WITH =, tstzrange(starts_at, ends_at) WITH &&)|
)

# 唯一约束（多数场景下与 unique_index 功能一致）
create unique_index(:accounts, [:slug])

引用关系（外键）

add :user_id, references(:users, type: :binary_id, on_delete: :delete_all), null: false
add :team_id, references(:teams, type: :binary_id, on_delete: :nilify_all)
add :parent_id, references(:categories, type: :binary_id, on_delete: :nothing)

多租户模式

每张表均需包含 tenant_id

def change do
  create table(:items, primary_key: false) do
    add :id, :binary_id, primary_key: true
    add :name, :string, null: false
    add :tenant_id, :binary_id, null: false
    timestamps(type: :utc_datetime_usec)
  end

  # 复合索引中 tenant_id 必须置于首位
  create index(:items, [:tenant_id])
  create unique_index(:items, [:tenant_id, :name])
end

为已有表添加 tenant_id

def change do
  alter table(:items) do
    add :tenant_id, :binary_id
  end

  # 在独立的数据迁移中完成数据填充（backfill），之后再执行：
  # alter table(:items) do
  #   modify :tenant_id, :binary_id, null: false
  # end
end

数据迁移

规则：禁止在同一个迁移文件中混合模式变更（schema changes）与数据变更（data changes）。

安全的数据迁移模式

defmodule MyApp.Repo.Migrations.BackfillUserRoles do
  use Ecto.Migration

  # 不要使用 schema 模块 —— 它们可能在此迁移运行后发生变更
  def up do
    execute """
    UPDATE users SET role = 'member' WHERE role IS NULL
    """
  end

  def down do
    # 数据迁移通常不可逆
    :ok
  end
end

分批数据迁移（适用于大表）

def up do
  execute """
  UPDATE users SET role = 'member'
  WHERE id IN (
    SELECT id FROM users WHERE role IS NULL LIMIT 10000
  )
  """

  # 对于超大表，建议改用 Task 或 Oban job 执行
end

可逆 vs 不可逆迁移

可逆迁移（使用 change）

以下操作可由 Ecto 自动推导反向操作：

• create table ↔ drop table
• add column ↔ remove column
• create index ↔ drop index
• rename ↔ rename

不可逆迁移（使用 up/down）

必须显式定义正向与反向逻辑：

• modify 字段类型 —— Ecto 无法自动推断原始类型
• execute 原生 SQL
• 数据填充（backfills）
• 带数据的字段删除

def up do
  alter table(:users) do
    modify :email, :citext, from: :string  # 添加 from: 可提升可逆性
  end
end

def down do
  alter table(:users) do
    modify :email, :string, from: :citext
  end
end

使用 modify 时指定 from:

Phoenix 1.7+ 支持通过 from: 实现可逆的 modify 操作：

def change do
  alter table(:users) do
    modify :email, :citext, null: false, from: {:string, null: true}
  end
end

PostgreSQL 扩展

def change do
  execute "CREATE EXTENSION IF NOT EXISTS citext", "DROP EXTENSION IF EXISTS citext"
  execute "CREATE EXTENSION IF NOT EXISTS pgcrypto", "DROP EXTENSION IF EXISTS pgcrypto"
  execute "CREATE EXTENSION IF NOT EXISTS pg_trgm", "DROP EXTENSION IF EXISTS pg_trgm"
end

枚举类型（PostgreSQL 原生 —— 谨慎使用）

优先使用 :string 字段配合 Ecto.Enum。若必须使用 PostgreSQL 原生 enum：

def up do
  execute "CREATE TYPE order_status AS ENUM ('pending', 'confirmed', 'shipped', 'delivered')"

  alter table(:orders) do
    add :status, :order_status, null: false, default: "pending"
  end
end

def down do
  alter table(:orders) do
    remove :status
  end

  execute "DROP TYPE order_status"
end

警告：向 PostgreSQL enum 中新增值需使用 ALTER TYPE ... ADD VALUE，该语句无法在事务内执行。因此更推荐使用 :string + Ecto.Enum 方案。

检查清单

• 主键：设置 primary_key: false，并手动添加 add :id, :binary_id, primary_key: true
• 必填字段需声明 null: false
• 使用 timestamps(type: :utc_datetime_usec)
• 外键需配置合适的 on_delete 行为
• 每个外键字段都应建索引
• tenant_id 字段必须建索引（且在复合索引中作为首列）
• 在必要位置添加唯一性约束
• 并发索引应置于独立迁移中，并添加 @disable_ddl_transaction true
• 数据迁移必须与模式迁移分离，存于不同文件