Automatic Migration

ent的迁移支持功能，可使数据库 schema 与你项目根目录下的 ent/migrate/schema.go 中定义的 schema 对象保持一致。

自动迁移

在应用程序初始化过程中运行自动迁移逻辑：

  1. if err := client.Schema.Create(ctx); err != nil {
  2.     log.Fatalf("failed creating schema resources: %v", err)
  3. }

Create 创建你项目 ent 部分所需的的数据库资源 。 默认情况下，Create以“append-only”模式工作；这意味着，它只创建新表和索引，将列追加到表或扩展列类型。 例如，将int改为bigint。

想要删除列或索引怎么办？

删除资源

WithDropIndex 和 WithDropColumn 是用于删除表列和索引的两个选项。

  1. package main
  3. import (
  4.     "context"
  5.     "log"
  7.     "<project>/ent"
  8.     "<project>/ent/migrate"
  9. )
  11. func main() {
  12.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  13.     if err != nil {
  14.         log.Fatalf("failed connecting to mysql: %v", err)
  15.     }
  16.     defer client.Close()
  17.     ctx := context.Background()
  18.     // Run migration.
  19.     err = client.Schema.Create(
  20.         ctx, 
  21.         migrate.WithDropIndex(true),
  22.         migrate.WithDropColumn(true), 
  23.     )
  24.     if err != nil {
  25.         log.Fatalf("failed creating schema resources: %v", err)
  26.     }
  27. }

为了在调试模式下运行迁移 (打印所有SQL查询)，请运行：

  1. err := client.Debug().Schema.Create(
  2.     ctx, 
  3.     migrate.WithDropIndex(true),
  4.     migrate.WithDropColumn(true),
  5. )
  6. if err != nil {
  7.     log.Fatalf("failed creating schema resources: %v", err)
  8. }

全局唯一ID

默认情况下，每个表的SQL主键从1开始；这意味着不同类型的多个实体可以有相同的ID。 不像AWS Neptune，节点ID是UUID。

This does not work well if you work with GraphQL, which requires the object ID to be unique.

To enable the Universal-IDs support for your project, pass the WithGlobalUniqueID option to the migration.

Automatic Migration - 图1Versioned-migration users should follow the documentation when using WithGlobalUniqueID on MySQL 5.*. :::

  1. package main
  3. import (
  4.     "context"
  5.     "log"
  7.     "<project>/ent"
  8.     "<project>/ent/migrate"
  9. )
  11. func main() {
  12.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  13.     if err != nil {
  14.         log.Fatalf("failed connecting to mysql: %v", err)
  15.     }
  16.     defer client.Close()
  17.     ctx := context.Background()
  18.     // Run migration.
  19.     if err := client.Schema.Create(ctx, migrate.WithGlobalUniqueID(true)); err != nil {
  20.         log.Fatalf("failed creating schema resources: %v", err)
  21.     }
  22. }

How does it work? ent migration allocates a 1<<32 range for the IDs of each entity (table), and store this information in a table named ent_types. For example, type A will have the range of [1,4294967296) for its IDs, and type B will have the range of [4294967296,8589934592), etc.

Note that if this option is enabled, the maximum number of possible tables is 65535.

Offline Mode

With Atlas becoming the default migration engine soon, offline migration will be replaced by versioned migrations.

Offline mode allows you to write the schema changes to an io.Writer before executing them on the database. It’s useful for verifying the SQL commands before they’re executed on the database, or to get an SQL script to run manually.

Print changes

  1. package main
  3. import (
  4.     "context"
  5.     "log"
  6.     "os"
  8.     "<project>/ent"
  9.     "<project>/ent/migrate"
  10. )
  12. func main() {
  13.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  14.     if err != nil {
  15.         log.Fatalf("failed connecting to mysql: %v", err)
  16.     }
  17.     defer client.Close()
  18.     ctx := context.Background()
  19.     // Dump migration changes to stdout.
  20.     if err := client.Schema.WriteTo(ctx, os.Stdout); err != nil {
  21.         log.Fatalf("failed printing schema changes: %v", err)
  22.     }
  23. }

Write changes to a file

  1. package main
  3. import (
  4.     "context"
  5.     "log"
  6.     "os"
  8.     "<project>/ent"
  9.     "<project>/ent/migrate"
  10. )
  12. func main() {
  13.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  14.     if err != nil {
  15.         log.Fatalf("failed connecting to mysql: %v", err)
  16.     }
  17.     defer client.Close()
  18.     ctx := context.Background()
  19.     // Dump migration changes to an SQL script.
  20.     f, err := os.Create("migrate.sql")
  21.     if err != nil {
  22.         log.Fatalf("create migrate file: %v", err)
  23.     }
  24.     defer f.Close()
  25.     if err := client.Schema.WriteTo(ctx, f); err != nil {
  26.         log.Fatalf("failed printing schema changes: %v", err)
  27.     }
  28. }

Foreign Keys

By default, ent uses foreign-keys when defining relationships (edges) to enforce correctness and consistency on the database side.

However, ent also provide an option to disable this functionality using the WithForeignKeys option. You should note that setting this option to false, will tell the migration to not create foreign-keys in the schema DDL and the edges validation and clearing must be handled manually by the developer.

We expect to provide a set of hooks for implementing the foreign-key constraints in the application level in the near future.

  1. package main
  3. import (
  4.     "context"
  5.     "log"
  7.     "<project>/ent"
  8.     "<project>/ent/migrate"
  9. )
  11. func main() {
  12.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  13.     if err != nil {
  14.         log.Fatalf("failed connecting to mysql: %v", err)
  15.     }
  16.     defer client.Close()
  17.     ctx := context.Background()
  18.     // Run migration.
  19.     err = client.Schema.Create(
  20.         ctx,
  21.         migrate.WithForeignKeys(false), // Disable foreign keys.
  22.     )
  23.     if err != nil {
  24.         log.Fatalf("failed creating schema resources: %v", err)
  25.     }
  26. }

Migration Hooks

The framework provides an option to add hooks (middlewares) to the migration phase. This option is ideal for modifying or filtering the tables that the migration is working on, or for creating custom resources in the database.

  1. package main
  3. import (
  4.     "context"
  5.     "log"
  7.     "<project>/ent"
  8.     "<project>/ent/migrate"
  10.     "entgo.io/ent/dialect/sql/schema"
  11. )
  13. func main() {
  14.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  15.     if err != nil {
  16.         log.Fatalf("failed connecting to mysql: %v", err)
  17.     }
  18.     defer client.Close()
  19.     ctx := context.Background()
  20.     // Run migration.
  21.     err = client.Schema.Create(
  22.         ctx,
  23.         schema.WithHooks(func(next schema.Creator) schema.Creator {
  24.             return schema.CreateFunc(func(ctx context.Context, tables ...*schema.Table) error {
  25.                 // Run custom code here.
  26.                 return next.Create(ctx, tables...)
  27.             })
  28.         }),
  29.     )
  30.     if err != nil {
  31.         log.Fatalf("failed creating schema resources: %v", err)
  32.     }
  33. }

Atlas Integration

Starting with v0.10, Ent supports running migration with Atlas, which is a more robust migration framework that covers many features that are not supported by current Ent migrate package. In order to execute a migration with the Atlas engine, use the WithAtlas(true) option.

  1. package main
  3. import (
  4.     "context"
  5.     "log"
  7.     "<project>/ent"
  8.     "<project>/ent/migrate"
  10.     "entgo.io/ent/dialect/sql/schema"
  11. )
  13. func main() {
  14.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  15.     if err != nil {
  16.         log.Fatalf("failed connecting to mysql: %v", err)
  17.     }
  18.     defer client.Close()
  19.     ctx := context.Background()
  20.     // Run migration.
  21.     err = client.Schema.Create(ctx, schema.WithAtlas(true))
  22.     if err != nil {
  23.         log.Fatalf("failed creating schema resources: %v", err)
  24.     }
  25. }

In addition to the standard options (e.g. WithDropColumn, WithGlobalUniqueID), the Atlas integration provides additional options for hooking into schema migration steps.

atlas-migration-process

Atlas Diff and Apply Hooks

Here are two examples that show how to hook into the Atlas Diff and Apply steps.

  1. package main
  3. import (
  4.     "context"
  5.     "log"
  7.     "<project>/ent"
  8.     "<project>/ent/migrate"
  10.     "ariga.io/atlas/sql/migrate"
  11.     atlas "ariga.io/atlas/sql/schema"
  12.     "entgo.io/ent/dialect"
  13.     "entgo.io/ent/dialect/sql/schema"
  14. )
  16. func main() {
  17.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  18.     if err != nil {
  19.         log.Fatalf("failed connecting to mysql: %v", err)
  20.     }
  21.     defer client.Close()
  22.     ctx := context.Background()
  23.     // Run migration.
  24.     err :=  client.Schema.Create(
  25.         ctx,
  26.         // Hook into Atlas Diff process.
  27.         schema.WithDiffHook(func(next schema.Differ) schema.Differ {
  28.             return schema.DiffFunc(func(current, desired *atlas.Schema) ([]atlas.Change, error) {
  29.                 // Before calculating changes.
  30.                 changes, err := next.Diff(current, desired)
  31.                 if err != nil {
  32.                     return nil, err
  33.                 }
  34.                 // After diff, you can filter
  35.                 // changes or return new ones.
  36.                 return changes, nil
  37.             })
  38.         }),
  39.         // Hook into Atlas Apply process.
  40.         schema.WithApplyHook(func(next schema.Applier) schema.Applier {
  41.             return schema.ApplyFunc(func(ctx context.Context, conn dialect.ExecQuerier, plan *migrate.Plan) error {
  42.                 // Example to hook into the apply process, or implement
  43.                 // a custom applier. For example, write to a file.
  44.                 //
  45.                 //  for _, c := range plan.Changes {
  46.                 //      fmt.Printf("%s: %s", c.Comment, c.Cmd)
  47.                 //      if err := conn.Exec(ctx, c.Cmd, c.Args, nil); err != nil {
  48.                 //          return err
  49.                 //      }
  50.                 //  }
  51.                 //
  52.                 return next.Apply(ctx, conn, plan)
  53.             })
  54.         }),
  55.     )
  56.     if err != nil {
  57.         log.Fatalf("failed creating schema resources: %v", err)
  58.     }
  59. }

Diff Hook Example

In case a field was renamed in the ent/schema, Ent won’t detect this change as renaming and will propose DropColumn and AddColumn changes in the diff stage. One way to get over this is to use the StorageKey option on the field and keep the old column name in the database table. However, using Atlas Diff hooks allow replacing the DropColumn and AddColumn changes with a RenameColumn change.

  1. func main() {
  2.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  3.     if err != nil {
  4.         log.Fatalf("failed connecting to mysql: %v", err)
  5.     }
  6.     defer client.Close()
  7.     // ...
  8.     if err := client.Schema.Create(ctx, schema.WithDiffHook(renameColumnHook)); err != nil {
  9.         log.Fatalf("failed creating schema resources: %v", err)
  10.     }
  11. }
  13. func renameColumnHook(next schema.Differ) schema.Differ {
  14.     return schema.DiffFunc(func(current, desired *atlas.Schema) ([]atlas.Change, error) {
  15.         changes, err := next.Diff(current, desired)
  16.         if err != nil {
  17.             return nil, err
  18.         }
  19.         for _, c := range changes {
  20.             m, ok := c.(*atlas.ModifyTable)
  21.             // Skip if the change is not a ModifyTable,
  22.             // or if the table is not the "users" table.
  23.             if !ok || m.T.Name != user.Table {
  24.                 continue
  25.             }
  26.             changes := atlas.Changes(m.Changes)
  27.             switch i, j := changes.IndexDropColumn("old_name"), changes.IndexAddColumn("new_name"); {
  28.             case i != -1 && j != -1:
  29.                 // Append a new renaming change.
  30.                 changes = append(changes, &atlas.RenameColumn{
  31.                     From: changes[i].(*atlas.DropColumn).C,
  32.                     To: changes[j].(*atlas.AddColumn).C,
  33.                 })
  34.                 // Remove the drop and add changes.
  35.                 changes.RemoveIndex(i, j)
  36.                 m.Changes = changes
  37.             case i != -1 || j != -1:
  38.                 return nil, errors.New("old_name and new_name must be present or absent")
  39.             }
  40.         }
  41.         return changes, nil
  42.     })
  43. }

Apply Hook Example

The Apply hook allows accessing and mutating the migration plan and its raw changes (SQL statements), but in addition to that it is also useful for executing custom SQL statements before or after the plan is applied. For example, changing a nullable column to non-nullable without a default value is not allowed by default. However, we can work around this using an Apply hook that UPDATEs all rows that contain NULL value in this column:

  1. func main() {
  2.     client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")
  3.     if err != nil {
  4.         log.Fatalf("failed connecting to mysql: %v", err)
  5.     }
  6.     defer client.Close()
  7.     // ...
  8.     if err := client.Schema.Create(ctx, schema.WithApplyHook(fillNulls)); err != nil {
  9.         log.Fatalf("failed creating schema resources: %v", err)
  10.     }
  11. }
  13. func fillNulls(next schema.Applier) schema.Applier {
  14.     return schema.ApplyFunc(func(ctx context.Context, conn dialect.ExecQuerier, plan *migrate.Plan) error {
  15.         // There are three ways to UPDATE the NULL values to "Unknown" in this stage.
  16.         // Append a custom migrate.Change to the plan, execute an SQL statement directly
  17.         // on the dialect.ExecQuerier, or use the ent.Client used by the project.
  19.         // Execute a custom SQL statement.
  20.         query, args := sql.Dialect(dialect.MySQL).
  21.             Update(user.Table).
  22.             Set(user.FieldDropOptional, "Unknown").
  23.             Where(sql.IsNull(user.FieldDropOptional)).
  24.             Query()
  25.         if err := conn.Exec(ctx, query, args, nil); err != nil {
  26.             return err
  27.         }
  29.         // Append a custom statement to migrate.Plan.
  30.         //
  31.         //  plan.Changes = append([]*migrate.Change{
  32.         //      {
  33.         //          Cmd: fmt.Sprintf("UPDATE users SET %[1]s = '%[2]s' WHERE %[1]s IS NULL", user.FieldDropOptional, "Unknown"),
  34.         //      },
  35.         //  }, plan.Changes...)
  37.         // Use the ent.Client used by the project.
  38.         //
  39.         //  drv := sql.NewDriver(dialect.MySQL, sql.Conn{ExecQuerier: conn.(*sql.Tx)})
  40.         //  if err := ent.NewClient(ent.Driver(drv)).
  41.         //      User.
  42.         //      Update().
  43.         //      SetDropOptional("Unknown").
  44.         //      Where(/* Add predicate to filter only rows with NULL values */).
  45.         //      Exec(ctx); err != nil {
  46.         //      return fmt.Errorf("fix default values to uppercase: %w", err)
  47.         //  }
  49.         return next.Apply(ctx, conn, plan)
  50.     })
  51. }