{"record":{"id":"bc4f0f3a3d6c0515","repo":"vitessio/vitess","slug":"online-ddl-is-disabled","errorCode":null,"errorMessage":"online DDL is disabled","messagePattern":"online DDL is disabled","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/schema/online_ddl.go","lineNumber":53,"sourceCode":"\tonlineDdlUUIDRegexp               = regexp.MustCompile(`^[0-f]{8}_[0-f]{4}_[0-f]{4}_[0-f]{4}_[0-f]{12}$`)\n\tonlineDDLGeneratedTableNameRegexp = regexp.MustCompile(`^_[0-f]{8}_[0-f]{4}_[0-f]{4}_[0-f]{4}_[0-f]{12}_([0-9]{14})_(gho|ghc|del|new|vrepl)$`)\n\tptOSCGeneratedTableNameRegexp     = regexp.MustCompile(`^_.*_old$`)\n\tmigrationContextValidatorRegexp   = regexp.MustCompile(`^[\\w:-]*$`)\n)\n\nvar onlineDDLInternalTableHintsMap = map[string]bool{\n\t\"vrp\": true, // vreplication\n\t\"gho\": true, // gh-ost\n\t\"ghc\": true, // gh-ost\n\t\"del\": true, // gh-ost\n\t\"new\": true, // pt-osc\n}\n\nvar (\n\t// ErrDirectDDLDisabled is returned when direct DDL is disabled, and a user attempts to run a DDL statement\n\tErrDirectDDLDisabled = errors.New(\"direct DDL is disabled\")\n\t// ErrOnlineDDLDisabled is returned when online DDL is disabled, and a user attempts to run an online DDL operation (submit, review, control)\n\tErrOnlineDDLDisabled = errors.New(\"online DDL is disabled\")\n\t// ErrForeignKeyFound indicates any finding of FOREIGN KEY clause in a DDL statement\n\tErrForeignKeyFound = errors.New(\"Foreign key found\")\n\t// ErrRenameTableFound indicates finding of ALTER TABLE...RENAME in ddl statement\n\tErrRenameTableFound = errors.New(\"RENAME clause found\")\n)\n\nconst (\n\tSchemaMigrationsTableName = \"schema_migrations\"\n\tRevertActionStr           = \"revert\"\n)\n\n// ValidateMigrationContext validates that the given migration context only uses valid characters\nfunc ValidateMigrationContext(migrationContext string) error {\n\tif migrationContextValidatorRegexp.MatchString(migrationContext) {\n\t\treturn nil\n\t}\n\treturn vterrors.Errorf(vtrpcpb.Code_INVALID_ARGUMENT, \"invalid characters in migration_context %v. Use alphanumeric, dash, underscore and colon only\", migrationContext)\n}","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/schema/online_ddl.go#L35-L71","documentation":"ErrOnlineDDLDisabled is a sentinel error returned when an online-DDL operation is requested (submit/review/control via TryExecute, buildAlterMigrationPlan, buildRevertMigrationPlan, buildShowMigrationLogsPlan) while online DDL is disabled in the configuration. It prevents scheduling gh-ost/pt-osc migrations when the deployment doesn't support or allow them.","triggerScenarios":"Calling vtctldclient Migration... (submit/revert/show/logs) or issuing a /*vt+ ddl_strategy=online|gh-ost|pt-osc */ statement while the tablet's ddl_strategy/config disallows online DDL (e.g. set to 'direct' or online-DDL feature disabled).","commonSituations":"Clusters not provisioned for gh-ost/pt-osc (missing artifacts/binlog assumptions); operators restricting online DDL during maintenance windows; scripts reusing online-DDL syntax against a direct-only cluster.","solutions":["Enable online DDL by setting -ddl_strategy to an online strategy (gh-ost, pt-osc, or online) on the tablet","If the operation must run now, use a direct strategy if permitted: /*vt+ ddl_strategy=direct */","Verify the VReplication/online-DDL prerequisites are met on the target keyspace/tablets","Handle errors.Is(err, schema.ErrOnlineDDLDisabled) in automation to pick a permitted strategy"],"exampleFix":"-- before (online-DDL disabled cluster)\nALTER /*vt+ ddl_strategy=gh-ost */ TABLE t ADD COLUMN c INT;\n// after: enable it via tablet flag\n-ddl_strategy gh-ost\n-- or use direct if allowed\nALTER /*vt+ ddl_strategy=direct */ TABLE t ADD COLUMN c INT;","handlingStrategy":"validation","validationCode":"strategy := viper.GetString(\"ddl_strategy\")\nif isOnlineDDLRequest(stmt) && !onlineDDLEnabled(strategy) {\n    return fmt.Errorf(\"online DDL disabled; set ddl_strategy to gh-ost/pt-osc or use direct\")\n}","typeGuard":null,"tryCatchPattern":"_, err := tm.TryExecute(ctx, migrationStmt)\nif errors.Is(err, schema.ErrOnlineDDLDisabled) {\n    return fmt.Errorf(\"online DDL is not enabled on this cluster: %w\", err)\n}","preventionTips":["Align ddl_strategy flags across tablets before issuing migrations","Verify online-DDL prerequisites (artifacts, binlog format) at deploy time","Gate migration tooling on a capability check, not assumptions","Document permitted strategies per environment"],"tags":["ddl","online-ddl","configuration","mysql"],"backgroundTag":"ddl-strategy-disabled","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}