数据库迁移

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.

  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

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. }