feat: simplify database migration system for local-first application

apps/scopes/src/main/kotlin/io/github/kamiazya/scopes/apps/cli/di/scopemanagement/ScopeManagementInfrastructureModule.kt

@@ -1,6 +1,8 @@
 package io.github.kamiazya.scopes.apps.cli.di.scopemanagement
 
 import io.github.kamiazya.scopes.platform.application.port.TransactionManager
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.MigrationAwareDatabaseProvider
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.MigrationConfig
 import io.github.kamiazya.scopes.platform.infrastructure.transaction.SqlDelightTransactionManager
 import io.github.kamiazya.scopes.scopemanagement.db.ScopeManagementDatabase
 import io.github.kamiazya.scopes.scopemanagement.domain.repository.ActiveContextRepository
@@ -17,13 +19,13 @@ import io.github.kamiazya.scopes.scopemanagement.infrastructure.adapters.ErrorMa
 import io.github.kamiazya.scopes.scopemanagement.infrastructure.alias.generation.DefaultAliasGenerationService
 import io.github.kamiazya.scopes.scopemanagement.infrastructure.alias.generation.providers.DefaultWordProvider
 import io.github.kamiazya.scopes.scopemanagement.infrastructure.alias.generation.strategies.HaikunatorStrategy
+import io.github.kamiazya.scopes.scopemanagement.infrastructure.migration.ScopeManagementMigrationProvider
 import io.github.kamiazya.scopes.scopemanagement.infrastructure.repository.SqlDelightActiveContextRepository
 import io.github.kamiazya.scopes.scopemanagement.infrastructure.repository.SqlDelightAspectDefinitionRepository
 import io.github.kamiazya.scopes.scopemanagement.infrastructure.repository.SqlDelightContextViewRepository
 import io.github.kamiazya.scopes.scopemanagement.infrastructure.repository.SqlDelightScopeAliasRepository
 import io.github.kamiazya.scopes.scopemanagement.infrastructure.repository.SqlDelightScopeRepository
 import io.github.kamiazya.scopes.scopemanagement.infrastructure.service.AspectQueryFilterValidator
-import io.github.kamiazya.scopes.scopemanagement.infrastructure.sqldelight.SqlDelightDatabaseProvider
 import org.koin.core.qualifier.named
 import org.koin.dsl.module
 
@@ -38,15 +40,59 @@ import org.koin.dsl.module
  * - Default services following Zero-Configuration principle
  */
 val scopeManagementInfrastructureModule = module {
-    // SQLDelight Database
+    // Migration configuration
+    single<MigrationConfig>(named("scopeManagementMigrationConfig")) {
+        MigrationConfig(
+            maxRetries = 3,
+        )
+    }
+
+    // Migration provider
+    single(named("scopeManagementMigrationProvider")) {
+        { ScopeManagementMigrationProvider(logger = get()).getMigrations() }
+    }
+
+    // Migration-aware database provider
+    single<MigrationAwareDatabaseProvider<ScopeManagementDatabase>>(named("scopeManagementDatabaseProvider")) {
+        val migrationProvider: () -> List<io.github.kamiazya.scopes.platform.infrastructure.database.migration.Migration> =
+            get(named("scopeManagementMigrationProvider"))
+        val config: MigrationConfig = get(named("scopeManagementMigrationConfig"))
+        val logger: io.github.kamiazya.scopes.platform.observability.logging.Logger = get()
+
+        MigrationAwareDatabaseProvider(
+            migrationProvider = migrationProvider,
+            config = config,
+            logger = logger,
+            databaseFactory = { driver ->
+                // Schema is created by migrations; avoid double-creation here
+                ScopeManagementDatabase(driver)
+            },
+        )
+    }
+
+    // SQLDelight Database using the migration-aware provider
     single<ScopeManagementDatabase>(named("scopeManagement")) {
         val databasePath: String = get<String>(named("databasePath"))
+        val provider: MigrationAwareDatabaseProvider<ScopeManagementDatabase> = get(named("scopeManagementDatabaseProvider"))
+
         val dbPath = if (databasePath == ":memory:") {
             ":memory:"
         } else {
             "$databasePath/scope-management.db"
         }
-        SqlDelightDatabaseProvider.createDatabase(dbPath)
+
+        // Create database with migrations applied
+        kotlinx.coroutines.runBlocking {
+            provider.createDatabase(dbPath).fold(
+                ifLeft = { err ->
+                    // Fail-fast using Kotlin's error() function
+                    error("Failed to create database: ${err.message}")
+                },
+                ifRight = { database ->
+                    database
+                },
+            )
+        }
     }
 
     // Repository implementations - mix of SQLDelight and legacy SQLite
@@ -128,4 +174,10 @@ val scopeManagementInfrastructureModule = module {
             logger = get(),
         )
     }
+
+    // Note: Schema version repository and migration executor are no longer needed here
+    // They are handled internally by MigrationAwareDatabaseProvider
+
+    // Note: Migrations are now automatically run when creating the ManagedSqlDriver
+    // No need for separate MigrationManager or DatabaseMigrationBootstrapper
 }

apps/scopes/src/main/resources/META-INF/native-image/resource-config.json

@@ -20,6 +20,10 @@
       "pattern" : "logback-.*\\.xml$"
     }, {
       "pattern" : "META-INF/services/.*"
+    }, {
+      "pattern" : "migrations/.*\\.sql$"
+    }, {
+      "pattern" : "migrations/.*/.*\\.sql$"
     } ]
   },
   "bundles" : [ ]

contexts/device-synchronization/infrastructure/src/main/kotlin/io/github/kamiazya/scopes/devicesync/infrastructure/migration/DeviceSyncMigrationProvider.kt

@@ -0,0 +1,18 @@
+package io.github.kamiazya.scopes.devicesync.infrastructure.migration
+
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.Migration
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.scanner.ResourceMigrationDiscovery
+import io.github.kamiazya.scopes.platform.observability.logging.Logger
+
+/**
+ * Provides migrations for the Device Synchronization bounded context.
+ */
+class DeviceSyncMigrationProvider(private val logger: Logger) {
+    private val discovery = ResourceMigrationDiscovery(
+        resourcePath = "migrations/device-sync",
+        classLoader = this::class.java.classLoader,
+        logger = logger,
+    )
+
+    fun getMigrations(): List<Migration> = discovery.discoverMigrations()
+}

contexts/device-synchronization/infrastructure/src/main/kotlin/io/github/kamiazya/scopes/devicesync/infrastructure/sqldelight/SqlDelightDatabaseProvider.kt

@@ -1,35 +1,50 @@
 package io.github.kamiazya.scopes.devicesync.infrastructure.sqldelight
 
-import app.cash.sqldelight.db.SqlDriver
-import app.cash.sqldelight.driver.jdbc.sqlite.JdbcSqliteDriver
 import io.github.kamiazya.scopes.devicesync.db.DeviceSyncDatabase
+import io.github.kamiazya.scopes.devicesync.infrastructure.migration.DeviceSyncMigrationProvider
+import io.github.kamiazya.scopes.platform.infrastructure.database.ManagedSqlDriver
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.applyMigrations
+import io.github.kamiazya.scopes.platform.observability.logging.ConsoleLogger
+import kotlinx.coroutines.runBlocking
 
 /**
- * Provides SQLDelight database instances for Device Synchronization.
+ * Provides SQLDelight database instances for Device Synchronization with automatic migrations.
  */
 object SqlDelightDatabaseProvider {
 
-    /**
-     * Creates a new DeviceSyncDatabase instance.
-     */
-    fun createDatabase(databasePath: String): DeviceSyncDatabase {
-        val driver: SqlDriver = JdbcSqliteDriver("jdbc:sqlite:$databasePath")
-
-        // Create the database schema
-        DeviceSyncDatabase.Schema.create(driver)
+    class ManagedDatabase(private val database: DeviceSyncDatabase, private val managedDriver: AutoCloseable) :
+        DeviceSyncDatabase by database,
+        AutoCloseable {
+        override fun close() = managedDriver.close()
+    }
 
-        // Enable foreign keys
-        driver.execute(null, "PRAGMA foreign_keys=ON", 0)
+    fun createDatabase(databasePath: String): DeviceSyncDatabase {
+        val managedDriver = ManagedSqlDriver.createWithDefaults(databasePath)
+        val driver = managedDriver.driver
 
-        return DeviceSyncDatabase(driver)
+        val logger = ConsoleLogger("DeviceSyncDB")
+        val migrations = DeviceSyncMigrationProvider(logger).getMigrations()
+        runBlocking {
+            driver.applyMigrations(migrations, logger).fold(
+                ifLeft = { err -> error("Migration failed: ${err.message}") },
+                ifRight = { },
+            )
+        }
+        return ManagedDatabase(DeviceSyncDatabase(driver), managedDriver)
     }
 
-    /**
-     * Creates an in-memory database for testing.
-     */
     fun createInMemoryDatabase(): DeviceSyncDatabase {
-        val driver: SqlDriver = JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)
-        DeviceSyncDatabase.Schema.create(driver)
-        return DeviceSyncDatabase(driver)
+        val managedDriver = ManagedSqlDriver(":memory:")
+        val driver = managedDriver.driver
+
+        val logger = ConsoleLogger("DeviceSyncDB-InMemory")
+        val migrations = DeviceSyncMigrationProvider(logger).getMigrations()
+        runBlocking {
+            driver.applyMigrations(migrations, logger).fold(
+                ifLeft = { err -> error("Migration failed: ${err.message}") },
+                ifRight = { },
+            )
+        }
+        return ManagedDatabase(DeviceSyncDatabase(driver), managedDriver)
     }
 }

contexts/device-synchronization/infrastructure/src/main/resources/migrations/device-sync/V1__Initial_device_sync_schema.sql

@@ -0,0 +1,25 @@
+-- Initial schema for Device Synchronization
+
+CREATE TABLE IF NOT EXISTS devices (
+    device_id TEXT PRIMARY KEY NOT NULL,
+    last_sync_at INTEGER,
+    last_successful_push INTEGER,
+    last_successful_pull INTEGER,
+    sync_status TEXT NOT NULL DEFAULT 'NEVER_SYNCED',
+    pending_changes INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_devices_sync_status ON devices(sync_status);
+CREATE INDEX IF NOT EXISTS idx_devices_updated_at ON devices(updated_at);
+
+CREATE TABLE IF NOT EXISTS vector_clocks (
+    device_id TEXT NOT NULL,
+    component_device TEXT NOT NULL,
+    timestamp INTEGER NOT NULL,
+    PRIMARY KEY (device_id, component_device)
+);
+
+CREATE INDEX IF NOT EXISTS idx_vector_clocks_device_id ON vector_clocks(device_id);
+

contexts/event-store/infrastructure/src/main/kotlin/io/github/kamiazya/scopes/eventstore/infrastructure/migration/EventStoreMigrationProvider.kt

@@ -0,0 +1,20 @@
+package io.github.kamiazya.scopes.eventstore.infrastructure.migration
+
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.Migration
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.scanner.ResourceMigrationDiscovery
+import io.github.kamiazya.scopes.platform.observability.logging.Logger
+
+/**
+ * Provides migrations for the Event Store bounded context.
+ *
+ * Migrations are discovered from classpath resources under migrations/event-store.
+ */
+class EventStoreMigrationProvider(private val logger: Logger) {
+    private val discovery = ResourceMigrationDiscovery(
+        resourcePath = "migrations/event-store",
+        classLoader = this::class.java.classLoader,
+        logger = logger,
+    )
+
+    fun getMigrations(): List<Migration> = discovery.discoverMigrations()
+}

contexts/event-store/infrastructure/src/main/kotlin/io/github/kamiazya/scopes/eventstore/infrastructure/sqldelight/SqlDelightDatabaseProvider.kt

@@ -1,35 +1,50 @@
 package io.github.kamiazya.scopes.eventstore.infrastructure.sqldelight
 
-import app.cash.sqldelight.db.SqlDriver
-import app.cash.sqldelight.driver.jdbc.sqlite.JdbcSqliteDriver
 import io.github.kamiazya.scopes.eventstore.db.EventStoreDatabase
+import io.github.kamiazya.scopes.eventstore.infrastructure.migration.EventStoreMigrationProvider
+import io.github.kamiazya.scopes.platform.infrastructure.database.ManagedSqlDriver
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.applyMigrations
+import io.github.kamiazya.scopes.platform.observability.logging.ConsoleLogger
+import kotlinx.coroutines.runBlocking
 
 /**
- * Provides SQLDelight database instances for Event Store.
+ * Provides SQLDelight database instances for Event Store with automatic migrations.
  */
 object SqlDelightDatabaseProvider {
 
-    /**
-     * Creates a new EventStoreDatabase instance.
-     */
-    fun createDatabase(databasePath: String): EventStoreDatabase {
-        val driver: SqlDriver = JdbcSqliteDriver("jdbc:sqlite:$databasePath")
-
-        // Create the database schema
-        EventStoreDatabase.Schema.create(driver)
+    class ManagedDatabase(private val database: EventStoreDatabase, private val managedDriver: AutoCloseable) :
+        EventStoreDatabase by database,
+        AutoCloseable {
+        override fun close() = managedDriver.close()
+    }
 
-        // Enable foreign keys
-        driver.execute(null, "PRAGMA foreign_keys=ON", 0)
+    fun createDatabase(databasePath: String): EventStoreDatabase {
+        val managedDriver = ManagedSqlDriver.createWithDefaults(databasePath)
+        val driver = managedDriver.driver
 
-        return EventStoreDatabase(driver)
+        val logger = ConsoleLogger("EventStoreDB")
+        val migrations = EventStoreMigrationProvider(logger).getMigrations()
+        runBlocking {
+            driver.applyMigrations(migrations, logger).fold(
+                ifLeft = { err -> error("Migration failed: ${err.message}") },
+                ifRight = { },
+            )
+        }
+        return ManagedDatabase(EventStoreDatabase(driver), managedDriver)
     }
 
-    /**
-     * Creates an in-memory database for testing.
-     */
     fun createInMemoryDatabase(): EventStoreDatabase {
-        val driver: SqlDriver = JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)
-        EventStoreDatabase.Schema.create(driver)
-        return EventStoreDatabase(driver)
+        val managedDriver = ManagedSqlDriver(":memory:")
+        val driver = managedDriver.driver
+
+        val logger = ConsoleLogger("EventStoreDB-InMemory")
+        val migrations = EventStoreMigrationProvider(logger).getMigrations()
+        runBlocking {
+            driver.applyMigrations(migrations, logger).fold(
+                ifLeft = { err -> error("Migration failed: ${err.message}") },
+                ifRight = { },
+            )
+        }
+        return ManagedDatabase(EventStoreDatabase(driver), managedDriver)
     }
 }

contexts/event-store/infrastructure/src/main/resources/migrations/event-store/V1__Initial_event_store_schema.sql

@@ -0,0 +1,19 @@
+-- Initial schema for Event Store
+
+CREATE TABLE IF NOT EXISTS events (
+    sequence_number INTEGER PRIMARY KEY AUTOINCREMENT,
+    event_id TEXT NOT NULL UNIQUE,
+    aggregate_id TEXT NOT NULL,
+    aggregate_version INTEGER NOT NULL,
+    event_type TEXT NOT NULL,
+    event_data TEXT NOT NULL,
+    occurred_at INTEGER NOT NULL,
+    stored_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_aggregate_id_version ON events(aggregate_id, aggregate_version);
+CREATE INDEX IF NOT EXISTS idx_events_stored_at ON events(stored_at);
+CREATE INDEX IF NOT EXISTS idx_events_occurred_at ON events(occurred_at);
+CREATE INDEX IF NOT EXISTS idx_events_event_type_sequence_number ON events(event_type, sequence_number);
+CREATE INDEX IF NOT EXISTS idx_events_event_type_occurred_at ON events(event_type, occurred_at);
+

contexts/scope-management/infrastructure/src/main/kotlin/io/github/kamiazya/scopes/scopemanagement/infrastructure/migration/ScopeManagementMigrationProvider.kt

@@ -0,0 +1,24 @@
+package io.github.kamiazya.scopes.scopemanagement.infrastructure.migration
+
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.Migration
+import io.github.kamiazya.scopes.platform.infrastructure.database.migration.scanner.ResourceMigrationDiscovery
+import io.github.kamiazya.scopes.platform.observability.logging.Logger
+
+/**
+ * Provides migrations for the Scope Management bounded context.
+ *
+ * Migrations are discovered from the classpath under the migrations directory.
+ * They follow the naming convention: V{version}__{description}.sql
+ */
+class ScopeManagementMigrationProvider(private val logger: Logger) {
+    private val discovery = ResourceMigrationDiscovery(
+        resourcePath = "migrations/scope-management",
+        classLoader = this::class.java.classLoader,
+        logger = logger,
+    )
+
+    /**
+     * Gets all migrations for the scope management context.
+     */
+    fun getMigrations(): List<Migration> = discovery.discoverMigrations()
+}