feat: Add repair migration cli command.

packages/serverpod/lib/src/database/migrations/migration_manager.dart

@@ -6,6 +6,7 @@ import 'package:serverpod/protocol.dart';
 import 'package:serverpod/serverpod.dart';
 import 'package:serverpod/src/database/analyze.dart';
 import 'package:serverpod/src/database/migrations/migrations.dart';
+import 'package:serverpod/src/database/migrations/repair_migrations.dart';
 import 'package:serverpod_shared/serverpod_shared.dart';
 
 import '../../generated/protocol.dart' as internal;
@@ -144,6 +145,26 @@ class MigrationManager {
     return versions.sublist(index + 1);
   }
 
+  /// Applies the repair migration to the database.
+  Future<void> applyRepairMigration(Session session) async {
+    var repairMigration = RepairMigration.load(Directory.current);
+    if (repairMigration == null) {
+      return;
+    }
+
+    var appliedRepairMigration = await DatabaseMigrationVersion.db.findFirstRow(
+        session,
+        where: (t) =>
+            t.module.equals(MigrationConstants.repairMigrationModuleName));
+
+    if (appliedRepairMigration != null &&
+        appliedRepairMigration.version == repairMigration.versionName) {
+      return;
+    }
+
+    await session.dbNext.unsafeExecute(repairMigration.sqlMigration);
+  }
+
   /// Migrates all modules to the latest version.
   Future<void> migrateToLatest(Session session) async {
     var migrations = <Migration>[];

packages/serverpod/lib/src/database/migrations/repair_migrations.dart

@@ -0,0 +1,48 @@
+import 'dart:io';
+import 'package:path/path.dart' as path;
+import 'package:serverpod_shared/serverpod_shared.dart';
+
+/// [RepairMigration] is used to repair a database back to a migration version.
+class RepairMigration {
+  /// The version of the repair migration.
+  final String versionName;
+
+  /// The SQL to run to repair the database.
+  final String sqlMigration;
+
+  RepairMigration._({
+    required this.versionName,
+    required this.sqlMigration,
+  });
+
+  /// Loads the repair migration from the repair migration directory.
+  /// Returns null if no repair migration is found.
+  static RepairMigration? load(Directory projectRootDirectory) {
+    var repairMigrationFiles =
+        MigrationConstants.repairMigrationDirectory(projectRootDirectory)
+            .listSync()
+            .whereType<File>();
+    if (repairMigrationFiles.isEmpty) {
+      return null;
+    }
+
+    var migrationSqlFile = repairMigrationFiles.cast<File?>().firstWhere(
+          (element) => element != null
+              ? path.basename(element.path).endsWith('.sql')
+              : false,
+          orElse: () => null,
+        );
+
+    if (migrationSqlFile == null) {
+      return null;
+    }
+
+    var version = path.basename(migrationSqlFile.path).split('.').first;
+    var sqlMigration = migrationSqlFile.readAsStringSync();
+
+    return RepairMigration._(
+      versionName: version,
+      sqlMigration: sqlMigration,
+    );
+  }
+}

packages/serverpod/lib/src/server/command_line_args.dart

@@ -56,6 +56,9 @@ class CommandLineArgs {
   /// If true, the server will apply database migrations on startup.
   late final bool applyMigrations;
 
+  /// If true, the server will apply database repair migration on startup.
+  late final bool applyRepairMigration;
+
   /// Parses the command line arguments passed to Serverpod and creates a
   /// [CommandLineArgs] object.
   CommandLineArgs(List<String> args) {
@@ -92,6 +95,11 @@ class CommandLineArgs {
           'apply-migrations',
           abbr: 'a',
           defaultsTo: false,
+        )
+        ..addFlag(
+          'apply-repair-migration',
+          abbr: 'A',
+          defaultsTo: false,
         );
       var results = argParser.parse(args);
 
@@ -120,6 +128,7 @@ class CommandLineArgs {
       }
 
       applyMigrations = results['apply-migrations'] ?? false;
+      applyRepairMigration = results['apply-repair-migration'] ?? false;
     } catch (e) {
       stdout.writeln(
         'Failed to parse command line arguments. Using default values. $e',
@@ -129,6 +138,7 @@ class CommandLineArgs {
       loggingMode = ServerpodLoggingMode.normal;
       role = ServerpodRole.monolith;
       applyMigrations = false;
+      applyRepairMigration = false;
     }
   }
 

packages/serverpod/lib/src/server/serverpod.dart

@@ -350,9 +350,16 @@ class Serverpod {
         migrationManager = MigrationManager();
         await migrationManager.initialize(session);
 
+        if (commandLineArgs.applyRepairMigration) {
+          logVerbose('Applying database repair migration');
+          await migrationManager.applyRepairMigration(session);
+          await migrationManager.initialize(session);
+        }
+
         if (commandLineArgs.applyMigrations) {
           logVerbose('Applying database migrations.');
           await migrationManager.migrateToLatest(session);
+          await migrationManager.initialize(session);
         }
 
         logVerbose('Verifying database integrity.');
@@ -425,7 +432,8 @@ class Serverpod {
       // no other maintenance tasks will be run.
       if (commandLineArgs.role == ServerpodRole.monolith ||
           (commandLineArgs.role == ServerpodRole.maintenance &&
-              !commandLineArgs.applyMigrations)) {
+              !(commandLineArgs.applyMigrations |
+                  commandLineArgs.applyRepairMigration))) {
         logVerbose('Starting maintenance tasks.');
 
         // Start future calls
@@ -438,7 +446,8 @@ class Serverpod {
       logVerbose('Serverpod start complete.');
 
       if (commandLineArgs.role == ServerpodRole.maintenance &&
-          commandLineArgs.applyMigrations) {
+          (commandLineArgs.applyMigrations |
+              commandLineArgs.applyRepairMigration)) {
         logVerbose('Finished applying database migrations.');
         exit(0);
       }

packages/serverpod_shared/lib/src/constants.dart

@@ -12,8 +12,19 @@ abstract class MigrationConstants {
   /// Filename of the migration registry.
   static const migrationRegistryFileName = 'migration_registry.json';
 
+  /// Module name in database under which repair migrations are stored.
+  static const repairMigrationModuleName = '_repair';
+
   /// Directory where migrations are stored.
   static Directory migrationsBaseDirectory(Directory serverRootDirectory) =>
       Directory(path.join(
-          serverRootDirectory.path, 'generated', 'migration', 'migrations'));
+          _migrationDirectory(serverRootDirectory).path, 'migrations'));
+
+  /// Directory where repair migrations are stored.
+  static Directory repairMigrationDirectory(Directory serverRootDirectory) =>
+      Directory(
+          path.join(_migrationDirectory(serverRootDirectory).path, 'repair'));
+
+  static Directory _migrationDirectory(Directory serverRootDirectory) =>
+      Directory(path.join(serverRootDirectory.path, 'generated', 'migration'));
 }

packages/serverpod_shared/lib/src/migration_exceptions.dart

@@ -31,3 +31,40 @@ class MigrationVersionLoadException implements Exception {
     required this.exception,
   });
 }
+
+/// Exception thrown when trying to load the live database definition.
+class MigrationLiveDatabaseDefinitionException implements Exception {
+  /// The exception that was thrown.
+  final String exception;
+
+  /// Creates a new [MigrationLiveDatabaseDefinitionException].
+  MigrationLiveDatabaseDefinitionException({
+    required this.exception,
+  });
+}
+
+/// Exception thrown when writing a migration fails.
+class MigrationRepairWriteException implements Exception {
+  /// The exception that was thrown.
+  final String exception;
+
+  /// Creates a new [MigrationRepairWriteException].
+  MigrationRepairWriteException({
+    required this.exception,
+  });
+}
+
+/// Exception thrown when a migration target is not found.
+class MigrationRepairTargetNotFoundException implements Exception {
+  /// The versions that were found.
+  final List<String> versionsFound;
+
+  /// The name of the target that was not found.
+  final String targetName;
+
+  /// Creates a new [MigrationRepairTargetNotFoundException].
+  MigrationRepairTargetNotFoundException({
+    required this.versionsFound,
+    required this.targetName,
+  });
+}