feat: Add migrate function

exposed-core/api/exposed-core.api

@@ -2014,10 +2014,9 @@ public final class org/jetbrains/exposed/sql/SchemaUtils {
  public static synthetic fun dropSchema$default (Lorg/jetbrains/exposed/sql/SchemaUtils;[Lorg/jetbrains/exposed/sql/Schema;ZZILjava/lang/Object;)V
  public final fun dropSequence ([Lorg/jetbrains/exposed/sql/Sequence;Z)V
  public static synthetic fun dropSequence$default (Lorg/jetbrains/exposed/sql/SchemaUtils;[Lorg/jetbrains/exposed/sql/Sequence;ZILjava/lang/Object;)V
- public final fun generateMigrationScript ([Lorg/jetbrains/exposed/sql/Table;Ljava/lang/String;Ljava/lang/String;Z)Ljava/io/File;
- public static synthetic fun generateMigrationScript$default (Lorg/jetbrains/exposed/sql/SchemaUtils;[Lorg/jetbrains/exposed/sql/Table;Ljava/lang/String;Ljava/lang/String;ZILjava/lang/Object;)Ljava/io/File;
  public final fun listDatabases ()Ljava/util/List;
  public final fun listTables ()Ljava/util/List;
+ public final fun logTimeSpent (Ljava/lang/String;ZLkotlin/jvm/functions/Function0;)Ljava/lang/Object;
  public final fun setSchema (Lorg/jetbrains/exposed/sql/Schema;Z)V
  public static synthetic fun setSchema$default (Lorg/jetbrains/exposed/sql/SchemaUtils;Lorg/jetbrains/exposed/sql/Schema;ZILjava/lang/Object;)V
  public final fun sortTablesByReferences (Ljava/lang/Iterable;)Ljava/util/List;

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/SchemaUtils.kt

@@ -4,13 +4,12 @@ import org.jetbrains.exposed.exceptions.ExposedSQLException
 import org.jetbrains.exposed.sql.SqlExpressionBuilder.asLiteral
 import org.jetbrains.exposed.sql.transactions.TransactionManager
 import org.jetbrains.exposed.sql.vendors.*
-import java.io.File
 import java.math.BigDecimal
 
 /** Utility functions that assist with creating, altering, and dropping database schema objects. */
 @Suppress("TooManyFunctions", "LargeClass")
 object SchemaUtils {
- private inline fun <R> logTimeSpent(message: String, withLogs: Boolean, block: () -> R): R {
+ inline fun <R> logTimeSpent(message: String, withLogs: Boolean, block: () -> R): R {
  return if (withLogs) {
  val start = System.currentTimeMillis()
  val answer = block()
@@ -510,11 +509,11 @@ object SchemaUtils {
  * Returns the SQL statements that need to be executed to make the existing database schema compatible with
  * the table objects defined using Exposed.
  *
- * **Note:** Some dialects, like SQLite, do not support `ALTER TABLE ADD COLUMN` syntax completely,
- * which restricts the behavior when adding some missing columns. Please check the documentation.
- *
  * By default, a description for each intermediate step, as well as its execution time, is logged at the INFO level.
  * This can be disabled by setting [withLogs] to `false`.
+ *
+ * **Note:** Some dialects, like SQLite, do not support `ALTER TABLE ADD COLUMN` syntax completely,
+ * which restricts the behavior when adding some missing columns. Please check the documentation.
  */
  fun statementsRequiredToActualizeScheme(vararg tables: Table, withLogs: Boolean = true): List<String> {
  val (tablesToCreate, tablesToAlter) = tables.partition { !it.exists() }
@@ -832,44 +831,6 @@ object SchemaUtils {
  return toDrop.toList()
  }
 
- /**
- * @param tables The tables whose changes will be used to generate the migration script.
- * @param scriptName The name to be used for the generated migration script.
- * @param scriptDirectory The directory (path from repository root) in which to create the migration script.
- * @param withLogs By default, a description for each intermediate step, as well as its execution time, is logged at
- * the INFO level. This can be disabled by setting [withLogs] to `false`.
- *
- * @return The generated migration script.
- *
- * @throws IllegalArgumentException if no argument is passed for the [tables] parameter.
- *
- * This function simply generates the migration script without applying the migration. Its purpose is to show what
- * the migration script will look like before applying the migration.
- * If a migration script with the same name already exists, its content will be overwritten.
- */
- @ExperimentalDatabaseMigrationApi
- fun generateMigrationScript(vararg tables: Table, scriptDirectory: String, scriptName: String, withLogs: Boolean = true): File {
- require(tables.isNotEmpty()) { "Tables argument must not be empty" }
-
- val allStatements = statementsRequiredForDatabaseMigration(*tables, withLogs = withLogs)
-
- val migrationScript = File("$scriptDirectory/$scriptName.sql")
- migrationScript.createNewFile()
-
- // Clear existing content
- migrationScript.writeText("")
-
- // Append statements
- allStatements.forEach { statement ->
- // Add semicolon only if it's not already there
- val conditionalSemicolon = if (statement.last() == ';') "" else ";"
-
- migrationScript.appendText("$statement$conditionalSemicolon\n")
- }
-
- return migrationScript
- }
-
  /**
  * Returns the SQL statements that need to be executed to make the existing database schema compatible with
  * the table objects defined using Exposed. Unlike [statementsRequiredToActualizeScheme], DROP/DELETE statements are
@@ -881,6 +842,7 @@ object SchemaUtils {
  * By default, a description for each intermediate step, as well as its execution time, is logged at the INFO level.
  * This can be disabled by setting [withLogs] to `false`.
  */
+ @ExperimentalDatabaseMigrationApi
  fun statementsRequiredForDatabaseMigration(vararg tables: Table, withLogs: Boolean = true): List<String> {
  val (tablesToCreate, tablesToAlter) = tables.partition { !it.exists() }
  val createStatements = logTimeSpent("Preparing create tables statements", withLogs) {

exposed-migration/api/exposed-migration.api

@@ -0,0 +1,16 @@
+public final class ExposedMigrationException : java/lang/RuntimeException {
+ public fun <init> (Ljava/lang/Exception;Ljava/lang/String;)V
+}
+
+public final class MigrationUtils {
+ public static final field INSTANCE LMigrationUtils;
+ public final fun generateMigrationScript ([Lorg/jetbrains/exposed/sql/Table;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Z)Ljava/io/File;
+ public final fun generateMigrationScript ([Lorg/jetbrains/exposed/sql/Table;Ljava/lang/String;Ljava/lang/String;Z)Ljava/io/File;
+ public static synthetic fun generateMigrationScript$default (LMigrationUtils;[Lorg/jetbrains/exposed/sql/Table;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ZILjava/lang/Object;)Ljava/io/File;
+ public static synthetic fun generateMigrationScript$default (LMigrationUtils;[Lorg/jetbrains/exposed/sql/Table;Ljava/lang/String;Ljava/lang/String;ZILjava/lang/Object;)Ljava/io/File;
+ public final fun migrate (Lorg/jetbrains/exposed/sql/Database;[Lorg/jetbrains/exposed/sql/Table;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Z)V
+ public final fun migrate (Lorg/jetbrains/exposed/sql/Database;[Lorg/jetbrains/exposed/sql/Table;Ljavax/sql/DataSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Z)V
+ public static synthetic fun migrate$default (LMigrationUtils;Lorg/jetbrains/exposed/sql/Database;[Lorg/jetbrains/exposed/sql/Table;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ZILjava/lang/Object;)V
+ public static synthetic fun migrate$default (LMigrationUtils;Lorg/jetbrains/exposed/sql/Database;[Lorg/jetbrains/exposed/sql/Table;Ljavax/sql/DataSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ZILjava/lang/Object;)V
+}
+

exposed-migration/build.gradle.kts

@@ -0,0 +1,31 @@
+plugins {
+ kotlin("jvm")
+}
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ api(project(":exposed-core"))
+
+ api(libs.flyway)
+ api(libs.flyway.mysql)
+ api(libs.flyway.oracle)
+ api(libs.flyway.sqlserver)
+
+ testImplementation(project(":exposed-tests"))
+
+ testImplementation(libs.junit)
+ testImplementation(kotlin("test-junit"))
+
+ testCompileOnly(libs.pgjdbc.ng)
+}
+
+tasks.test {
+ useJUnitPlatform()
+}
+
+kotlin {
+ jvmToolchain(8)
+}

exposed-migration/src/main/kotlin/ExposedMigrationException.kt

@@ -0,0 +1,2 @@
+/** An exception thrown when a database migration fails. */
+class ExposedMigrationException(exception: Exception, message: String) : RuntimeException(message, exception)

exposed-migration/src/main/kotlin/MigrationUtils.kt

@@ -0,0 +1,222 @@
+import org.flywaydb.core.Flyway
+import org.flywaydb.core.api.FlywayException
+import org.flywaydb.core.api.output.MigrateResult
+import org.jetbrains.exposed.sql.Database
+import org.jetbrains.exposed.sql.ExperimentalDatabaseMigrationApi
+import org.jetbrains.exposed.sql.SchemaUtils
+import org.jetbrains.exposed.sql.SchemaUtils.statementsRequiredForDatabaseMigration
+import org.jetbrains.exposed.sql.Table
+import org.jetbrains.exposed.sql.exposedLogger
+import org.jetbrains.exposed.sql.transactions.TransactionManager
+import java.io.File
+import javax.sql.DataSource
+
+object MigrationUtils {
+ /**
+ * Applies a database migration from [oldVersion] to [newVersion]. If a migration script with the same name already
+ * exists, the existing one will be used as is and a new one will not be generated. This allows you to generate a
+ * migration script before the migration and modify it manually if needed.
+ *
+ * To generate a migration script without applying a migration, @see [generateMigrationScript].
+ *
+ * @param tables The tables to which the migration will be applied.
+ * @param user The user of the database.
+ * @param password The password of the database.
+ * @param oldVersion The version to migrate from. Pending migrations up to [oldVersion] are applied before applying the migration to [newVersion].
+ * @param newVersion The version to migrate to.
+ * @param migrationTitle The title of the migration.
+ * @param migrationScriptDirectory The directory in which to create the migration script.
+ * @param withLogs By default, a description for each intermediate step, as well as its execution time, is logged at
+ * the INFO level. This can be disabled by setting [withLogs] to `false`.
+ *
+ * @throws ExposedMigrationException if the migration fails.
+ */
+ @ExperimentalDatabaseMigrationApi
+ @Suppress("LongParameterList", "TooGenericExceptionCaught")
+ fun Database.migrate(
+ vararg tables: Table,
+ user: String,
+ password: String,
+ oldVersion: String,
+ newVersion: String,
+ migrationTitle: String,
+ migrationScriptDirectory: String,
+ withLogs: Boolean = true
+ ) {
+ val flyway = Flyway
+ .configure()
+ .baselineOnMigrate(true)
+ .baselineVersion(oldVersion)
+ .dataSource(url, user, password)
+ .locations("filesystem:$migrationScriptDirectory")
+ .load()
+
+ attemptMigration(
+ *tables,
+ flyway = flyway,
+ oldVersion = oldVersion,
+ newVersion = newVersion,
+ migrationTitle = migrationTitle,
+ migrationScriptDirectory = migrationScriptDirectory,
+ withLogs = withLogs
+ )
+ }
+
+ /**
+ * Applies a database migration from [oldVersion] to [newVersion]. If a migration script with the same name already
+ * exists, the existing one will be used as is and a new one will not be generated. This allows you to generate a
+ * migration script before the migration and modify it manually if needed.
+ *
+ * To generate a migration script without applying a migration, @see [generateMigrationScript].
+ *
+ * @param tables The tables to which the migration will be applied.
+ * @param dataSource The [DataSource] object to be used as a means of getting a connection.
+ * @param oldVersion The version to migrate from. Pending migrations up to [oldVersion] are applied before applying the migration to [newVersion].
+ * @param newVersion The version to migrate to.
+ * @param migrationTitle The title of the migration.
+ * @param migrationScriptDirectory The directory in which to create the migration script.
+ * @param withLogs By default, a description for each intermediate step, as well as its execution time, is logged at
+ * the INFO level. This can be disabled by setting [withLogs] to `false`.
+ *
+ * @throws ExposedMigrationException if the migration fails.
+ */
+ @ExperimentalDatabaseMigrationApi
+ @Suppress("LongParameterList", "TooGenericExceptionCaught")
+ fun Database.migrate(
+ vararg tables: Table,
+ dataSource: DataSource,
+ oldVersion: String,
+ newVersion: String,
+ migrationTitle: String,
+ migrationScriptDirectory: String,
+ withLogs: Boolean = true
+ ) {
+ val flyway = Flyway
+ .configure()
+ .baselineOnMigrate(true)
+ .baselineVersion(oldVersion)
+ .dataSource(dataSource)
+ .locations("filesystem:$migrationScriptDirectory")
+ .load()
+
+ attemptMigration(
+ *tables,
+ flyway = flyway,
+ oldVersion = oldVersion,
+ newVersion = newVersion,
+ migrationTitle = migrationTitle,
+ migrationScriptDirectory = migrationScriptDirectory,
+ withLogs = withLogs
+ )
+ }
+
+ @ExperimentalDatabaseMigrationApi
+ @Suppress("TooGenericExceptionCaught")
+ private fun attemptMigration(
+ vararg tables: Table,
+ flyway: Flyway,
+ oldVersion: String,
+ newVersion: String,
+ migrationTitle: String,
+ migrationScriptDirectory: String,
+ withLogs: Boolean
+ ) {
+ with(TransactionManager.current()) {
+ db.dialect.resetCaches()
+
+ try {
+ val migrationScript = File("$migrationScriptDirectory/$migrationTitle.sql")
+ if (!migrationScript.exists()) {
+ generateMigrationScript(
+ tables = *tables,
+ newVersion = newVersion,
+ title = migrationTitle,
+ scriptDirectory = migrationScriptDirectory,
+ withLogs = withLogs
+ )
+ }
+ } catch (exception: Exception) {
+ throw ExposedMigrationException(
+ exception = exception,
+ message = "Failed to generate migration script for migration from $oldVersion to $newVersion: ${exception.message.orEmpty()}"
+ )
+ }
+
+ try {
+ SchemaUtils.logTimeSpent("Migrating database from $oldVersion to $newVersion", withLogs = true) {
+ val migrateResult: MigrateResult = flyway.migrate()
+ if (withLogs) {
+ exposedLogger.info("Migration of database ${if (migrateResult.success) "succeeded" else "failed"}.")
+ }
+ }
+ } catch (exception: FlywayException) {
+ flyway.repair()
+ throw ExposedMigrationException(
+ exception = exception,
+ message = "Migration failed from version $oldVersion to $newVersion: ${exception.message.orEmpty()}"
+ )
+ }
+
+ db.dialect.resetCaches()
+ }
+ }
+
+ /**
+ * This function simply generates the migration script, using the Flyway naming convention, without applying the
+ * migration. Its purpose is to show the user what the migration script will look like before applying the
+ * migration. If a migration script with the same name already exists, its content will be overwritten.
+ *
+ * @param tables The tables whose changes will be used to generate the migration script.
+ * @param newVersion The version to migrate to.
+ * @param title The title of the migration.
+ * @param scriptDirectory The directory in which to create the migration script.
+ * @param withLogs By default, a description for each intermediate step, as well as its execution time, is logged at
+ * the INFO level. This can be disabled by setting [withLogs] to `false`.
+ *
+ * @return The generated migration script.
+ *
+ * @throws IllegalArgumentException if no argument is passed for the [tables] parameter.
+ */
+ @ExperimentalDatabaseMigrationApi
+ fun generateMigrationScript(vararg tables: Table, newVersion: String, title: String, scriptDirectory: String, withLogs: Boolean = true): File {
+ return generateMigrationScript(*tables, scriptName = "V${newVersion}__$title", scriptDirectory = scriptDirectory, withLogs = withLogs)
+ }
+
+ /**
+ * This function simply generates the migration script without applying the migration. Its purpose is to show what
+ * the migration script will look like before applying the migration. If a migration script with the same name
+ * already exists, its content will be overwritten.
+ *
+ * @param tables The tables whose changes will be used to generate the migration script.
+ * @param scriptName The name to be used for the generated migration script.
+ * @param scriptDirectory The directory (path from repository root) in which to create the migration script.
+ * @param withLogs By default, a description for each intermediate step, as well as its execution time, is logged at
+ * the INFO level. This can be disabled by setting [withLogs] to `false`.
+ *
+ * @return The generated migration script.
+ *
+ * @throws IllegalArgumentException if no argument is passed for the [tables] parameter.
+ */
+ @ExperimentalDatabaseMigrationApi
+ fun generateMigrationScript(vararg tables: Table, scriptDirectory: String, scriptName: String, withLogs: Boolean = true): File {
+ require(tables.isNotEmpty()) { "Tables argument must not be empty" }
+
+ val allStatements = statementsRequiredForDatabaseMigration(*tables, withLogs = withLogs)
+
+ val migrationScript = File("$scriptDirectory/$scriptName.sql")
+ migrationScript.createNewFile()
+
+ // Clear existing content
+ migrationScript.writeText("")
+
+ // Append statements
+ allStatements.forEach { statement ->
+ // Add semicolon only if it's not already there
+ val conditionalSemicolon = if (statement.last() == ';') "" else ";"
+
+ migrationScript.appendText("$statement$conditionalSemicolon\n")
+ }
+
+ return migrationScript
+ }
+}

exposed-tests/build.gradle.kts

@@ -23,6 +23,7 @@ dependencies {
  implementation(project(":exposed-jdbc"))
  implementation(project(":exposed-dao"))
  implementation(project(":exposed-kotlin-datetime"))
+ implementation(project(":exposed-migration"))
 
  implementation(libs.slf4j)
  implementation(libs.log4j.slf4j.impl)