bytebase/bytebase · error

failed to compute SDL migration

Error message

failed to compute SDL migration

What it means

This error wraps a failure from schema.SDLMigration, which generates the SQL needed to move a database from its current schema to the desired schema defined in a sheet (declarative/SDL migration). It is thrown during the diff step of a declarative release when the schema engine cannot compute the diff, e.g. because the dumped metadata or desired SDL is invalid for the target engine. The wrapped inner error from the schema package identifies the actual cause.

Source

Thrown at backend/runner/taskrun/database_migrate_executor.go:1029

	dbMetadata, err := s.GetDBSchema(ctx, &store.FindDBSchemaMessage{
		Workspace:    instance.Workspace,
		InstanceID:   database.InstanceID,
		DatabaseName: database.DatabaseName,
	})
	if err != nil {
		return "", errors.Wrapf(err, "failed to get database schema for database %q", database.DatabaseName)
	}
	if dbMetadata == nil {
		return "", errors.Errorf("database schema %q not found", database.DatabaseName)
	}

	// instance.Metadata.GetVersion() is the synced server version (e.g. "5.7.25"); thread
	// it so MySQL canonicalizes a 5.7 database's schema as 5.7 rather than the default 8.0
	// stored form. model.DatabaseMetadata drops the version, so it is sourced here where the
	// instance message still carries it. Other engines ignore the version.
	migrationSQL, err := schema.SDLMigration(instance.Metadata.GetEngine(), sheetContent, dbMetadata, instance.Metadata.GetVersion())
	if err != nil {
		return "", errors.Wrapf(err, "failed to compute SDL migration")
	}

	return migrationSQL, nil
}

// computeNeedDump determines if schema dump is needed based on task type and statements.
func computeNeedDump(taskType storepb.Task_Type, engine storepb.Engine, statement string) bool {
	//exhaustive:enforce
	switch taskType {
	case storepb.Task_DATABASE_MIGRATE:
		// For DATABASE_MIGRATE, skip dump if all statements are DML since they
		// don't change schema. IsAllDML owns the type list.
		return !parserbase.IsAllDML(engine, statement)
	case storepb.Task_DATABASE_CREATE:
		return true
	case storepb.Task_TASK_TYPE_UNSPECIFIED:
		return false
	default:

View on GitHub (pinned to 1870550677)

Solutions

1. Inspect the wrapped inner error to find which part of the SDL/diff failed
2. Validate the sheet SDL content locally with the same engine/version parser
3. Re-dump the database metadata so dbMetadata matches the live schema
4. Verify instance.Metadata.GetVersion() is correct for MySQL version canonicalization
5. Check the engine type matches the actual database engine

Example fix

// before
migrationSQL, err := schema.SDLMigration(instance.Metadata.GetEngine(), sheetContent, dbMetadata, instance.Metadata.GetVersion())
if err != nil {
	return "", errors.Wrapf(err, "failed to compute SDL migration")
}
// after
migrationSQL, err := schema.SDLMigration(instance.Metadata.GetEngine(), sheetContent, dbMetadata, instance.Metadata.GetVersion())
if err != nil {
	return "", errors.Wrapf(err, "failed to compute SDL migration for engine %s, version %s", instance.Metadata.GetEngine(), instance.Metadata.GetVersion())
}

// Pre-validate the sheet SDL parses for the engine before submitting the release
if _, err := schema.ParseSDL(instance.Engine, sheetContent); err != nil {
	return fmt.Errorf("invalid sheet SDL: %w", err)
}

func dbMetadataValid(m *model.DatabaseMetadata) bool { return m != nil && len(m.Schemas) > 0 }

migrationSQL, err := schema.SDLMigration(engine, sheetContent, dbMetadata, version)
if err != nil {
	return "", fmt.Errorf("failed to compute SDL migration: %w", err)
}

When it happens

Trigger: Running a declarative release via runDeclarativeRelease: schema.SDLMigration(instance.Engine, sheetContent, dbMetadata, instanceVersion) returns an error because the sheet SDL fails to parse, the dumped database metadata is inconsistent, or the engine cannot canonicalize the schema (e.g. MySQL version-specific parsing).

Common situations: Desired-schema sheet contains SQL the engine's parser rejects; database metadata was dumped from a MySQL 5.7 instance but version threading failed; unsupported engine features appear in the SDL; schema drift produced a diff the engine cannot express.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• failed to load source schema
• failed to load target schema
• schema is nil for %s
• unknown partition type: %v
• invalid subpartition type: %v

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/b8c060556a2b95ff. Report an issue: GitHub.