ff

src/ffx/database.py

@@ -1,4 +1,4 @@
-import os, click
+import os, shutil, click
 
 from sqlalchemy import create_engine, inspect
 from sqlalchemy.orm import sessionmaker
@@ -9,7 +9,11 @@ import ffx.model
 from ffx.model.show import Base
 
 from ffx.model.property import Property
-from ffx.model.migration import DatabaseVersionException, migrateDatabase
+from ffx.model.migration import (
+    DatabaseVersionException,
+    getMigrationPlan,
+    migrateDatabase,
+)
 
 from ffx.constants import DATABASE_VERSION
 
@@ -30,7 +34,13 @@ def databaseContext(databasePath: str = ''):
         if not os.path.exists(ffxVarDir):
             os.makedirs(ffxVarDir)
         databasePath = os.path.join(ffxVarDir, 'ffx.db')
+    else:
+        databasePath = os.path.expanduser(databasePath)
 
+    if databasePath != ':memory:':
+        databasePath = os.path.abspath(databasePath)
+
+    databaseContext['path'] = databasePath
     databaseContext['url'] = f"sqlite:///{databasePath}"
     databaseContext['engine'] = create_engine(databaseContext['url'])
     databaseContext['session'] = sessionmaker(bind=databaseContext['engine'])
@@ -79,6 +89,7 @@ def ensureDatabaseVersion(databaseContext):
         )
 
     if currentDatabaseVersion < DATABASE_VERSION:
+        promptForDatabaseMigration(databaseContext, currentDatabaseVersion, DATABASE_VERSION)
         migrateDatabase(databaseContext, currentDatabaseVersion, DATABASE_VERSION, setDatabaseVersion)
         currentDatabaseVersion = getDatabaseVersion(databaseContext)
 
@@ -88,6 +99,67 @@ def ensureDatabaseVersion(databaseContext):
         )
 
 
+def promptForDatabaseMigration(databaseContext, currentDatabaseVersion: int, targetDatabaseVersion: int):
+    migrationPlan = getMigrationPlan(currentDatabaseVersion, targetDatabaseVersion)
+
+    click.echo("Database migration required.")
+    click.echo(f"Current version: {currentDatabaseVersion}")
+    click.echo(f"Target version: {targetDatabaseVersion}")
+    click.echo("Steps required:")
+
+    missingSteps = []
+    for migrationStep in migrationPlan:
+        moduleStatus = "present" if migrationStep.modulePresent else "missing"
+        click.echo(
+            f"  {migrationStep.versionFrom} -> {migrationStep.versionTo}: "
+            + f"{migrationStep.moduleName} [{moduleStatus}]"
+        )
+        if not migrationStep.modulePresent:
+            missingSteps.append(migrationStep)
+
+    if missingSteps:
+        firstMissingStep = missingSteps[0]
+        raise DatabaseVersionException(
+            f"No migration path from database version "
+            + f"{firstMissingStep.versionFrom} to {firstMissingStep.versionTo}"
+        )
+
+    if not click.confirm(
+        "Create a backup and continue with database migration?",
+        default=True,
+    ):
+        raise click.ClickException("Database migration aborted by user.")
+
+    backupPath = backupDatabaseBeforeMigration(
+        databaseContext,
+        currentDatabaseVersion,
+        targetDatabaseVersion,
+    )
+    click.echo(f"Database backup created: {backupPath}")
+
+
+def backupDatabaseBeforeMigration(databaseContext, currentDatabaseVersion: int, targetDatabaseVersion: int) -> str:
+    databasePath = databaseContext.get('path', '')
+    if not databasePath or databasePath == ':memory:':
+        raise click.ClickException("Database migration backup requires a file-backed SQLite database.")
+
+    if not os.path.isfile(databasePath):
+        raise click.ClickException(f"Database file not found for backup: {databasePath}")
+
+    backupPath = f"{databasePath}.v{currentDatabaseVersion}-to-v{targetDatabaseVersion}.bak"
+    backupIndex = 1
+    while os.path.exists(backupPath):
+        backupPath = (
+            f"{databasePath}.v{currentDatabaseVersion}-to-v{targetDatabaseVersion}.{backupIndex}.bak"
+        )
+        backupIndex += 1
+
+    databaseContext['engine'].dispose()
+    shutil.copy2(databasePath, backupPath)
+
+    return backupPath
+
+
 def getDatabaseVersion(databaseContext):
 
     try:

src/ffx/model/migration/__init__.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 import importlib
+import importlib.util
 
 
 class DatabaseVersionException(Exception):
@@ -8,10 +10,47 @@ class DatabaseVersionException(Exception):
         super().__init__(errorMessage)
 
 
+@dataclass(frozen=True)
+class MigrationStep:
+    versionFrom: int
+    versionTo: int
+    moduleName: str
+    modulePresent: bool
+
+
 def getMigrationStepModuleName(versionFrom: int, versionTo: int) -> str:
     return f"ffx.model.migration.step_{int(versionFrom)}_{int(versionTo)}"
 
 
+def migrationStepModuleExists(versionFrom: int, versionTo: int) -> bool:
+    moduleName = getMigrationStepModuleName(versionFrom, versionTo)
+
+    try:
+        return importlib.util.find_spec(moduleName) is not None
+    except ModuleNotFoundError:
+        return False
+
+
+def getMigrationPlan(currentVersion: int, targetVersion: int) -> list[MigrationStep]:
+    version = int(currentVersion)
+    target = int(targetVersion)
+    migrationPlan = []
+
+    while version < target:
+        nextVersion = version + 1
+        migrationPlan.append(
+            MigrationStep(
+                versionFrom=version,
+                versionTo=nextVersion,
+                moduleName=getMigrationStepModuleName(version, nextVersion),
+                modulePresent=migrationStepModuleExists(version, nextVersion),
+            )
+        )
+        version = nextVersion
+
+    return migrationPlan
+
+
 def loadMigrationStep(versionFrom: int, versionTo: int):
     moduleName = getMigrationStepModuleName(versionFrom, versionTo)
 
@@ -34,13 +73,10 @@ def loadMigrationStep(versionFrom: int, versionTo: int):
 
 
 def migrateDatabase(databaseContext, currentVersion: int, targetVersion: int, setDatabaseVersion):
-    version = int(currentVersion)
-    target = int(targetVersion)
-
-    while version < target:
-        nextVersion = version + 1
-        migrationStep = loadMigrationStep(version, nextVersion)
+    for migrationStepInfo in getMigrationPlan(currentVersion, targetVersion):
+        migrationStep = loadMigrationStep(
+            migrationStepInfo.versionFrom,
+            migrationStepInfo.versionTo,
+        )
         migrationStep(databaseContext)
-        version = nextVersion
-        setDatabaseVersion(databaseContext, version)
-
+        setDatabaseVersion(databaseContext, migrationStepInfo.versionTo)