What causes "RENAME clause found" in vitessio/vitess?

Execute the rename with a direct DDL strategy: ALTER /*vt+ ddl_strategy=direct */ TABLE ...

RENAME clause found

Error message

RENAME clause found

What it means

ErrRenameTableFound is a sentinel error indicating an ALTER TABLE ... RENAME (or RENAME TABLE) clause was found during online-DDL statement validation (validateWalk / onlineDDLStatementSanity). Renames cannot be expressed as an online migration on the same table, so the statement is rejected in the online path.

Source

Thrown at go/vt/schema/online_ddl.go:57

)

var onlineDDLInternalTableHintsMap = map[string]bool{
	"vrp": true, // vreplication
	"gho": true, // gh-ost
	"ghc": true, // gh-ost
	"del": true, // gh-ost
	"new": true, // pt-osc
}

var (
	// ErrDirectDDLDisabled is returned when direct DDL is disabled, and a user attempts to run a DDL statement
	ErrDirectDDLDisabled = errors.New("direct DDL is disabled")
	// ErrOnlineDDLDisabled is returned when online DDL is disabled, and a user attempts to run an online DDL operation (submit, review, control)
	ErrOnlineDDLDisabled = errors.New("online DDL is disabled")
	// ErrForeignKeyFound indicates any finding of FOREIGN KEY clause in a DDL statement
	ErrForeignKeyFound = errors.New("Foreign key found")
	// ErrRenameTableFound indicates finding of ALTER TABLE...RENAME in ddl statement
	ErrRenameTableFound = errors.New("RENAME clause found")
)

const (
	SchemaMigrationsTableName = "schema_migrations"
	RevertActionStr           = "revert"
)

// ValidateMigrationContext validates that the given migration context only uses valid characters
func ValidateMigrationContext(migrationContext string) error {
	if migrationContextValidatorRegexp.MatchString(migrationContext) {
		return nil
	}
	return vterrors.Errorf(vtrpcpb.Code_INVALID_ARGUMENT, "invalid characters in migration_context %v. Use alphanumeric, dash, underscore and colon only", migrationContext)
}

// when validateWalk returns true, then the child nodes are also visited
func validateWalk(node sqlparser.SQLNode, allowForeignKeys bool) (kontinue bool, err error) {
	switch node.(type) {

View on GitHub (pinned to 01a25a7d17)

Solutions

Execute the rename with a direct DDL strategy: ALTER /*vt+ ddl_strategy=direct */ TABLE ...
Avoid renaming; create the new table online, copy data (vreplication), then drop the old table
Run RENAME TABLE as a separate permitted statement outside the online-DDL path
Check errors.Is(err, schema.ErrRenameTableFound) in tooling to redirect renames to direct execution

Example fix

-- before
ALTER /*vt+ ddl_strategy=gh-ost */ TABLE t RENAME TO t2;
-- after
ALTER /*vt+ ddl_strategy=direct */ TABLE t RENAME TO t2;

Defensive patterns

Strategy: validation

Validate before calling

if strings.Contains(strings.ToUpper(stmt), " RENAME ") {
    return fmt.Errorf("renames require ddl_strategy=direct or a copy-based migration")
}

Try / catch

_, err := tm.TryExecute(ctx, stmt)
if errors.Is(err, schema.ErrRenameTableFound) {
    // reroute to direct strategy or a create+copy+drop plan
}

Prevention

Never use online ddl_strategy for RENAME statements
For large table renames, plan create-new + vreplication copy + atomic swap
Lint generated migrations for RENAME clauses
Keep rename operations in a separate, direct-DDL-approved change window

When it happens

Trigger: Submitting ALTER TABLE t RENAME TO t2 (or equivalent rename syntax) with an online ddl_strategy; the sanity walk detects the rename clause and returns ErrRenameTableFound.

Common situations: Refactoring table names in production via vtctld; automated migration tools generating rename statements; users expecting gh-ost/pt-osc to support renames like plain MySQL does.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/d404fbaf383bdb82. Report an issue: GitHub.