diff --git a/openmetadata-service/src/main/java/org/openmetadata/service/migration/api/MigrationProcess.java b/openmetadata-service/src/main/java/org/openmetadata/service/migration/api/MigrationProcess.java index 1eb4ee0b5ad..9ecdfb79e38 100644 --- a/openmetadata-service/src/main/java/org/openmetadata/service/migration/api/MigrationProcess.java +++ b/openmetadata-service/src/main/java/org/openmetadata/service/migration/api/MigrationProcess.java @@ -7,6 +7,50 @@ import org.jdbi.v3.core.Jdbi; import org.openmetadata.service.migration.QueryStatus; import org.openmetadata.service.migration.context.MigrationOps; +/** + * Migration framework interface that supports three implementation approaches: + * 1. Flyway (deprecated, do not add new migrations here) + * 2. Native SQL migrations + * 3. Java-based migrations + * + *

Migration Execution Order: + * Migrations are executed in a specific sequence that must be maintained: + *

    + *
  1. Initialize - Set up migration context, database connections, and services
    2. + *
  2. Schema Changes - Execute DDL statements to modify database schema (tables, columns)
    3. + *
  3. Data Migration - Run Java code to transform or fix data in the updated schema
    4. + *
  4. Post-DDL Scripts - Run final SQL statements that depend on migrated data (indexes, constraints)
    5. + *
+ * + *

IMPORTANT: For ALL migration types including pure Java migrations, + * you MUST create the following directory structure in the bootstrap directory: + * + * 

+ * bootstrap/
+ * └── migrations/
+ *     └── [version]/        # e.g. "1.2.0"
+ *         ├── mysql/
+ *         │   ├── schemaChanges.sql             # Can be empty for Java-only migrations
+ *         │   └── postDataMigrationSQLScript.sql # Can be empty for Java-only migrations
+ *         └── postgres/
+ *             ├── schemaChanges.sql             # Can be empty for Java-only migrations
+ *             └── postDataMigrationSQLScript.sql # Can be empty for Java-only migrations
+ *
+ * + *

The migration discovery process searches for these directories to identify available migrations. + * Even for pure Java migrations, the directory structure MUST exist - SQL files can be empty but the + * directory structure is mandatory. + * + *

Java migrations must follow this naming convention: + * {@code org.openmetadata.service.migration.[dbPackageName].[versionPackage].Migration} + * Example: {@code org.openmetadata.service.migration.postgres.v120.Migration} + * + * In collate: + * {@code io.collate.service.migration.[dbPackageName].[versionPackage].Migration} + * + *

Java migrations should extend {@code MigrationProcessImpl} and override required methods, + * particularly {@code runDataMigration()} and {@code getMigrationOps()}. + */ public interface MigrationProcess { interface MigrationProcessCallback { void call();