dialect/sql/schema: add method to create a named versioned migration … (

#2385)

* dialect/sql/schema: add method to create a named versioned migration file

* doc/md: documentation for named versioned migrations

* entc/gen/template/dialect/sql/feature: add NamedDiff method to create named versioned migration files

* all: go generate

* doc/md: apply CR

dialect/sql/schema/atlas.go

@@ -308,7 +308,7 @@ func (m *Migrate) atCreate(ctx context.Context, tables ...*Table) error {
 				return err
 			}
 		}
-		plan, err := m.atDiff(ctx, tx, tables...)
+		plan, err := m.atDiff(ctx, tx, "", tables...)
 		if err != nil {
 			return err
 		}
@@ -334,7 +334,7 @@ func (m *Migrate) atCreate(ctx context.Context, tables ...*Table) error {
 	return tx.Commit()
 }
 
-func (m *Migrate) atDiff(ctx context.Context, conn dialect.ExecQuerier, tables ...*Table) (*migrate.Plan, error) {
+func (m *Migrate) atDiff(ctx context.Context, conn dialect.ExecQuerier, name string, tables ...*Table) (*migrate.Plan, error) {
 	drv, err := m.atOpen(conn)
 	if err != nil {
 		return nil, err
@@ -364,7 +364,7 @@ func (m *Migrate) atDiff(ctx context.Context, conn dialect.ExecQuerier, tables .
 		return nil, err
 	}
 	// Plan changes.
-	return drv.PlanChanges(ctx, "changes", changes)
+	return drv.PlanChanges(ctx, name, changes)
 }
 
 type db struct{ dialect.ExecQuerier }

dialect/sql/schema/migrate.go

@@ -164,10 +164,16 @@ func (m *Migrate) Create(ctx context.Context, tables ...*Table) error {
 // Diff compares the state read from the StateReader with the state defined by Ent.
 // Changes will be written to migration files by the configures Planner.
 func (m *Migrate) Diff(ctx context.Context, tables ...*Table) error {
+	return m.NamedDiff(ctx, "changes", tables...)
+}
+
+// NamedDiff compares the state read from the StateReader with the state defined by Ent.
+// Changes will be written to migration files by the configures Planner.
+func (m *Migrate) NamedDiff(ctx context.Context, name string, tables ...*Table) error {
 	if m.atlas.dir == nil {
 		return errors.New("no migration directory given")
 	}
-	plan, err := m.atDiff(ctx, m, tables...)
+	plan, err := m.atDiff(ctx, m, name, tables...)
 	if err != nil {
 		return err
 	}

doc/md/versioned-migrations.md

@@ -82,6 +82,8 @@ func main() {
 	}
 	// Write migration diff.
 	err = client.Schema.Diff(ctx, schema.WithDir(dir))
+	// You can use the following method to give the migration files a name.
+	// err = client.Schema.NamedDiff(ctx, "migration_name", schema.WithDir(dir))
 	if err != nil {
 		log.Fatalf("failed creating schema resources: %v", err)
 	}
@@ -137,6 +139,10 @@ func main() {
     if err := m.Diff(context.Background(), tbls...); err != nil {
         log.Fatalln(err)
     }
+    // You can use the following method to give the migration files a name.
+    // if err := m.NamedDiff(context.Background(), "migration_name", tbls...); err != nil {
+    //     log.Fatalln(err)
+    // }
 }
 ```
 

entc/gen/template/dialect/sql/feature/migrate_diff.tmpl

@@ -16,4 +16,14 @@ func (s *Schema) Diff(ctx context.Context, opts ...schema.MigrateOption) error {
     }
     return migrate.Diff(ctx, Tables...)
 }
+
+// NamedDiff creates a named migration file containing the statements to resolve the diff
+// between the Ent schema and the connected database.
+func (s *Schema) NamedDiff(ctx context.Context, name string, opts ...schema.MigrateOption) error {
+    migrate, err := schema.NewMigrate(s.drv, opts...)
+    if err != nil {
+        return fmt.Errorf("ent/migrate: %w", err)
+    }
+    return migrate.NamedDiff(ctx, name, Tables...)
+}
 {{ end }}