Attempt instant DDL early and add --force-instant-ddl flag

Move the --attempt-instant-ddl check to run before ghost table and binlog
streaming setup. If instant DDL succeeds, the migration completes immediately
without creating ghost tables, changelog tables, or starting binlog streaming.

Add --force-instant-ddl flag that aborts the migration if ALGORITHM=INSTANT
is not supported, preventing accidental multi-hour row-copy migrations when
the intent was an instant metadata change.

Author: hasan-dot

go/base/context.go

@@ -104,6 +104,7 @@ type MigrationContext struct {
 	GoogleCloudPlatform      bool
 	AzureMySQL               bool
 	AttemptInstantDDL        bool
+	ForceInstantDDL          bool
 	Resume                   bool
 	Revert                   bool
 	OldTableName             string

go/cmd/gh-ost/main.go

@@ -70,6 +70,7 @@ func main() {
 	flag.StringVar(&migrationContext.OriginalTableName, "table", "", "table name (mandatory)")
 	flag.StringVar(&migrationContext.AlterStatement, "alter", "", "alter statement (mandatory)")
 	flag.BoolVar(&migrationContext.AttemptInstantDDL, "attempt-instant-ddl", false, "Attempt to use instant DDL for this migration first")
+	flag.BoolVar(&migrationContext.ForceInstantDDL, "force-instant-ddl", false, "Require instant DDL; abort if the operation cannot be completed instantly (do not fall back to regular migration)")
 	storageEngine := flag.String("storage-engine", "innodb", "Specify table storage engine (default: 'innodb'). When 'rocksdb': the session transaction isolation level is changed from REPEATABLE_READ to READ_COMMITTED.")
 
 	flag.BoolVar(&migrationContext.CountTableRows, "exact-rowcount", false, "actually count table rows as opposed to estimate them (results in more accurate progress estimation)")
@@ -230,6 +231,9 @@ func main() {
 		if migrationContext.AttemptInstantDDL {
 			log.Warning("--attempt-instant-ddl was provided with --revert, it will be ignored")
 		}
+		if migrationContext.ForceInstantDDL {
+			log.Warning("--force-instant-ddl was provided with --revert, it will be ignored")
+		}
 		if migrationContext.IncludeTriggers {
 			log.Warning("--include-triggers was provided with --revert, it will be ignored")
 		}
@@ -270,6 +274,9 @@ func main() {
 	if migrationContext.SwitchToRowBinlogFormat && migrationContext.AssumeRBR {
 		migrationContext.Log.Fatal("--switch-to-rbr and --assume-rbr are mutually exclusive")
 	}
+	if migrationContext.ForceInstantDDL {
+		migrationContext.AttemptInstantDDL = true
+	}
 	if migrationContext.TestOnReplicaSkipReplicaStop {
 		if !migrationContext.TestOnReplica {
 			migrationContext.Log.Fatal("--test-on-replica-skip-replica-stop requires --test-on-replica to be enabled")

go/logic/migrator.go

@@ -430,6 +430,25 @@ func (this *Migrator) Migrate() (err error) {
 	if err := this.checkAbort(); err != nil {
 		return err
 	}
+
+	// In MySQL 8.0 (and possibly earlier) some DDL statements can be applied instantly.
+	// Attempt this EARLY, before creating ghost tables or starting binlog streaming,
+	// to avoid unnecessary overhead for large tables when instant DDL is possible.
+	// Skip during resume (the DDL may have already been applied) and noop mode.
+	if this.migrationContext.AttemptInstantDDL && !this.migrationContext.Resume {
+		if this.migrationContext.Noop {
+			this.migrationContext.Log.Debugf("Noop operation; not really attempting instant DDL")
+		} else {
+			if err := this.attemptInstantDDLEarly(); err == nil {
+				return nil
+			} else if this.migrationContext.ForceInstantDDL {
+				return fmt.Errorf("--force-instant-ddl enabled but ALGORITHM=INSTANT is not supported for this operation: %s", err)
+			} else {
+				this.migrationContext.Log.Infof("ALGORITHM=INSTANT not supported for this operation, proceeding with original algorithm")
+			}
+		}
+	}
+
 	// If we are resuming, we will initiateStreaming later when we know
 	// the binlog coordinates to resume streaming from.
 	// If not resuming, the streamer must be initiated before the applier,
@@ -451,27 +470,6 @@ func (this *Migrator) Migrate() (err error) {
 	if err := this.createFlagFiles(); err != nil {
 		return err
 	}
-	// In MySQL 8.0 (and possibly earlier) some DDL statements can be applied instantly.
-	// Attempt to do this if AttemptInstantDDL is set.
-	if this.migrationContext.AttemptInstantDDL {
-		if this.migrationContext.Noop {
-			this.migrationContext.Log.Debugf("Noop operation; not really attempting instant DDL")
-		} else {
-			this.migrationContext.Log.Infof("Attempting to execute alter with ALGORITHM=INSTANT")
-			if err := this.applier.AttemptInstantDDL(); err == nil {
-				if err := this.finalCleanup(); err != nil {
-					return nil
-				}
-				if err := this.hooksExecutor.onSuccess(); err != nil {
-					return err
-				}
-				this.migrationContext.Log.Infof("Success! table %s.%s migrated instantly", sql.EscapeName(this.migrationContext.DatabaseName), sql.EscapeName(this.migrationContext.OriginalTableName))
-				return nil
-			} else {
-				this.migrationContext.Log.Infof("ALGORITHM=INSTANT not supported for this operation, proceeding with original algorithm: %s", err)
-			}
-		}
-	}
 
 	initialLag, _ := this.inspector.getReplicationLag()
 	if !this.migrationContext.Resume {
@@ -1030,6 +1028,55 @@ func (this *Migrator) initiateServer() (err error) {
 	return nil
 }
 
+// attemptInstantDDLEarly attempts to execute the ALTER with ALGORITHM=INSTANT
+// before any ghost table or binlog streaming setup. This avoids the overhead of
+// creating ghost tables, changelog tables, and streaming binlog events for
+// operations that MySQL 8.0+ can execute as instant metadata-only changes.
+// If instant DDL succeeds, the migration is complete. If it fails, the caller
+// should proceed with the normal migration flow.
+func (this *Migrator) attemptInstantDDLEarly() error {
+	this.migrationContext.Log.Infof("Attempting to execute alter with ALGORITHM=INSTANT before full migration setup")
+
+	// Open a temporary connection to the master for the instant DDL attempt.
+	// This avoids initializing the full Applier (ghost table, changelog, etc.).
+	connConfig := this.migrationContext.ApplierConnectionConfig
+	uri := connConfig.GetDBUri(this.migrationContext.DatabaseName)
+	db, _, err := mysql.GetDB(this.migrationContext.Uuid, uri)
+	if err != nil {
+		this.migrationContext.Log.Infof("Could not open connection for instant DDL attempt: %s", err)
+		return err
+	}
+
+	tableLockTimeoutSeconds := this.migrationContext.CutOverLockTimeoutSeconds * 2
+	this.migrationContext.Log.Infof("Setting LOCK timeout as %d seconds for instant DDL attempt", tableLockTimeoutSeconds)
+	lockTimeoutQuery := fmt.Sprintf(`set /* gh-ost */ session lock_wait_timeout:=%d`, tableLockTimeoutSeconds)
+	if _, err := db.Exec(lockTimeoutQuery); err != nil {
+		this.migrationContext.Log.Infof("Could not set lock timeout for instant DDL: %s", err)
+		return err
+	}
+
+	query := fmt.Sprintf(`ALTER /* gh-ost */ TABLE %s.%s %s, ALGORITHM=INSTANT`,
+		sql.EscapeName(this.migrationContext.DatabaseName),
+		sql.EscapeName(this.migrationContext.OriginalTableName),
+		this.migrationContext.AlterStatementOptions,
+	)
+	this.migrationContext.Log.Infof("INSTANT DDL query: %s", query)
+
+	if _, err := db.Exec(query); err != nil {
+		this.migrationContext.Log.Infof("ALGORITHM=INSTANT is not supported for this operation, proceeding with regular algorithm: %s", err)
+		return err
+	}
+
+	if err := this.hooksExecutor.onSuccess(); err != nil {
+		return err
+	}
+	this.migrationContext.Log.Infof("Successfully executed instant DDL on %s.%s (no ghost table was needed)",
+		sql.EscapeName(this.migrationContext.DatabaseName),
+		sql.EscapeName(this.migrationContext.OriginalTableName),
+	)
+	return nil
+}
+
 // initiateInspector connects, validates and inspects the "inspector" server.
 // The "inspector" server is typically a replica; it is where we issue some
 // queries such as:

go/logic/migrator_test.go

@@ -386,6 +386,76 @@ func (suite *MigratorTestSuite) TestMigrateEmpty() {
 	suite.Require().Equal("_testing_del", tableName)
 }
 
+func (suite *MigratorTestSuite) TestMigrateInstantDDLEarly() {
+	ctx := context.Background()
+
+	_, err := suite.db.ExecContext(ctx, fmt.Sprintf("CREATE TABLE %s (id INT PRIMARY KEY, name VARCHAR(64))", getTestTableName()))
+	suite.Require().NoError(err)
+
+	connectionConfig, err := getTestConnectionConfig(ctx, suite.mysqlContainer)
+	suite.Require().NoError(err)
+
+	migrationContext := newTestMigrationContext()
+	migrationContext.ApplierConnectionConfig = connectionConfig
+	migrationContext.InspectorConnectionConfig = connectionConfig
+	migrationContext.SetConnectionConfig("innodb")
+	migrationContext.AttemptInstantDDL = true
+
+	// Adding a column is an instant DDL operation in MySQL 8.0+
+	migrationContext.AlterStatementOptions = "ADD COLUMN instant_col VARCHAR(255)"
+
+	migrator := NewMigrator(migrationContext, "0.0.0")
+
+	err = migrator.Migrate()
+	suite.Require().NoError(err)
+
+	// Verify the new column was added via instant DDL
+	var tableName, createTableSQL string
+	//nolint:execinquery
+	err = suite.db.QueryRow("SHOW CREATE TABLE "+getTestTableName()).Scan(&tableName, &createTableSQL)
+	suite.Require().NoError(err)
+
+	suite.Require().Contains(createTableSQL, "instant_col")
+
+	// Verify that NO ghost table was created (instant DDL should skip ghost table creation)
+	//nolint:execinquery
+	err = suite.db.QueryRow("SHOW TABLES IN test LIKE '_testing_gho'").Scan(&tableName)
+	suite.Require().Error(err, "ghost table should not exist after instant DDL")
+	suite.Require().Equal(gosql.ErrNoRows, err)
+
+	// Verify that NO changelog table was created
+	//nolint:execinquery
+	err = suite.db.QueryRow("SHOW TABLES IN test LIKE '_testing_ghc'").Scan(&tableName)
+	suite.Require().Error(err, "changelog table should not exist after instant DDL")
+	suite.Require().Equal(gosql.ErrNoRows, err)
+}
+
+func (suite *MigratorTestSuite) TestForceInstantDDLFailsForNonInstantOp() {
+	ctx := context.Background()
+
+	_, err := suite.db.ExecContext(ctx, fmt.Sprintf("CREATE TABLE %s (id INT PRIMARY KEY, name VARCHAR(64))", getTestTableName()))
+	suite.Require().NoError(err)
+
+	connectionConfig, err := getTestConnectionConfig(ctx, suite.mysqlContainer)
+	suite.Require().NoError(err)
+
+	migrationContext := newTestMigrationContext()
+	migrationContext.ApplierConnectionConfig = connectionConfig
+	migrationContext.InspectorConnectionConfig = connectionConfig
+	migrationContext.SetConnectionConfig("innodb")
+	migrationContext.AttemptInstantDDL = true
+	migrationContext.ForceInstantDDL = true
+
+	// Changing a column type from VARCHAR to INT is NOT an instant DDL operation
+	migrationContext.AlterStatementOptions = "MODIFY COLUMN name INT"
+
+	migrator := NewMigrator(migrationContext, "0.0.0")
+
+	err = migrator.Migrate()
+	suite.Require().Error(err)
+	suite.Require().Contains(err.Error(), "--force-instant-ddl")
+}
+
 func (suite *MigratorTestSuite) TestRetryBatchCopyWithHooks() {
 	ctx := context.Background()