Remove dead Applier.AttemptInstantDDL, update docs, add local test

Remove the now-unused AttemptInstantDDL() method from Applier since instant
DDL is handled by attemptInstantDDLEarly() in the Migrator.

Update command-line-flags.md to document the new early execution behavior of
--attempt-instant-ddl and add documentation for --force-instant-ddl.

Add localtests/force-instant-ddl with an instant-compatible ALTER to exercise
the --force-instant-ddl success path.

Author: hasan-dot

doc/command-line-flags.md

@@ -62,10 +62,18 @@ MySQL 8.0 supports "instant DDL" for some operations. If an alter statement can
 
 It is not reliable to parse the `ALTER` statement to determine if it is instant or not. This is because the table might be in an older row format, or have some other incompatibility that is difficult to identify.
 
+When `--attempt-instant-ddl` is enabled, `gh-ost` will attempt `ALGORITHM=INSTANT` **early**, right after connecting to the inspector and before creating ghost tables or starting binlog streaming. If instant DDL succeeds, the migration completes immediately without any of the normal setup overhead. This is especially beneficial for large tables where the ghost table creation and binlog streaming setup would otherwise add significant time.
+
 `--attempt-instant-ddl` is disabled by default, but the risks of enabling it are relatively minor: `gh-ost` may need to acquire a metadata lock at the start of the operation. This is not a problem for most scenarios, but it could be a problem for users that start the DDL during a period with long running transactions.
 
 `gh-ost` will automatically fallback to the normal DDL process if the attempt to use instant DDL is unsuccessful.
 
+### force-instant-ddl
+
+`--force-instant-ddl` requires instant DDL to succeed. If `ALGORITHM=INSTANT` is not supported for the given operation, `gh-ost` will abort the migration immediately instead of falling back to a regular row-copy migration. This is useful when you intend an instant metadata-only change and want to prevent accidental multi-hour migrations on large tables.
+
+Implies `--attempt-instant-ddl`. Ignored with `--revert`.
+
 ### binlogsyncer-max-reconnect-attempts
 `--binlogsyncer-max-reconnect-attempts=0`, the maximum number of attempts to re-establish a broken inspector connection for sync binlog. `0` or `negative number` means infinite retry, default `0`
 

go/logic/applier.go

@@ -279,36 +279,6 @@ func (this *Applier) ValidateOrDropExistingTables() error {
 	return nil
 }
 
-// AttemptInstantDDL attempts to use instant DDL (from MySQL 8.0, and earlier in Aurora and some others).
-// If successful, the operation is only a meta-data change so a lot of time is saved!
-// The risk of attempting to instant DDL when not supported is that a metadata lock may be acquired.
-// This is minor, since gh-ost will eventually require a metadata lock anyway, but at the cut-over stage.
-// Instant operations include:
-// - Adding a column
-// - Dropping a column
-// - Dropping an index
-// - Extending a VARCHAR column
-// - Adding a virtual generated column
-// It is not reliable to parse the `alter` statement to determine if it is instant or not.
-// This is because the table might be in an older row format, or have some other incompatibility
-// that is difficult to identify.
-func (this *Applier) AttemptInstantDDL() error {
-	query := this.generateInstantDDLQuery()
-	this.migrationContext.Log.Infof("INSTANT DDL query is: %s", query)
-
-	// Reuse cut-over-lock-timeout from regular migration process to reduce risk
-	// in situations where there may be long-running transactions.
-	tableLockTimeoutSeconds := this.migrationContext.CutOverLockTimeoutSeconds * 2
-	this.migrationContext.Log.Infof("Setting LOCK timeout as %d seconds", tableLockTimeoutSeconds)
-	lockTimeoutQuery := fmt.Sprintf(`set /* gh-ost */ session lock_wait_timeout:=%d`, tableLockTimeoutSeconds)
-	if _, err := this.db.Exec(lockTimeoutQuery); err != nil {
-		return err
-	}
-	// We don't need a trx, because for instant DDL the SQL mode doesn't matter.
-	_, err := this.db.Exec(query)
-	return err
-}
-
 // CreateGhostTable creates the ghost table on the applier host
 func (this *Applier) CreateGhostTable() error {
 	query := fmt.Sprintf(`create /* gh-ost */ table %s.%s like %s.%s`,

go/logic/migrator.go

@@ -442,7 +442,7 @@ func (this *Migrator) Migrate() (err error) {
 			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)
+				return fmt.Errorf("--force-instant-ddl enabled but ALGORITHM=INSTANT is not supported for this operation: %w", err)
 			} else {
 				this.migrationContext.Log.Infof("ALGORITHM=INSTANT not supported for this operation, proceeding with original algorithm")
 			}

localtests/force-instant-ddl/create.sql

@@ -0,0 +1,25 @@
+drop table if exists gh_ost_test;
+
+create table gh_ost_test (
+    id int auto_increment,
+    i int not null,
+    color varchar(32),
+    primary key(id)
+) auto_increment = 1;
+
+insert into
+    gh_ost_test
+values
+    (null, 11, 'red');
+
+insert into
+    gh_ost_test
+values
+    (null, 13, 'green');
+
+insert into
+    gh_ost_test
+values
+    (null, 17, 'blue');
+
+drop event if exists gh_ost_test;

localtests/force-instant-ddl/extra_args

@@ -0,0 +1 @@
+--force-instant-ddl --alter='ADD COLUMN extra_col VARCHAR(255)'