Automatic Migration

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

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

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

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

    Versioned-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

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

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

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

    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.

    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.                 //
    52.             })
    53.         }),
    54.     )
    55.     if err != nil {
    56.         log.Fatalf("failed creating schema resources: %v", err)
    57.     }
    58. }

    Diff Hook Example

    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)