feat: add schema version-mismatch guard to prevent older app from opening newer database

Reads PRAGMA user_version via raw sqlite3 in read-only mode before Drift
opens the database. If the stored version exceeds the app's schema version,
throws DatabaseVersionMismatchException and shows an "Update Required"
screen instead of crashing on missing columns.

Author: ericgriffin

lib/core/database/database.dart

@@ -1178,8 +1178,12 @@ class ScheduledNotifications extends Table {
 class AppDatabase extends _$AppDatabase {
   AppDatabase(super.e);
 
+  /// The current schema version as a static constant so that pre-open checks
+  /// (e.g. version-mismatch guard) can reference it without an instance.
+  static const int currentSchemaVersion = 49;
+
   @override
-  int get schemaVersion => 49;
+  int get schemaVersion => currentSchemaVersion;
 
   @override
   MigrationStrategy get migration {

lib/core/database/database_version_exception.dart

@@ -0,0 +1,20 @@
+/// Thrown when the database file was created by a newer version of
+/// Submersion than the currently running app.
+///
+/// This prevents an older app from silently corrupting a newer schema
+/// by running stale migrations or downgrading the version stamp.
+class DatabaseVersionMismatchException implements Exception {
+  final int databaseVersion;
+  final int appVersion;
+
+  const DatabaseVersionMismatchException({
+    required this.databaseVersion,
+    required this.appVersion,
+  });
+
+  @override
+  String toString() =>
+      'DatabaseVersionMismatchException: database is schema v$databaseVersion '
+      'but this app only supports up to v$appVersion. '
+      'Please update Submersion to the latest version.';
+}

lib/core/services/database_service.dart

@@ -4,8 +4,10 @@ import 'package:drift/native.dart';
 import 'package:flutter/foundation.dart' show visibleForTesting;
 import 'package:path_provider/path_provider.dart';
 import 'package:path/path.dart' as p;
+import 'package:sqlite3/sqlite3.dart' as sqlite3;
 
 import 'package:submersion/core/database/database.dart';
+import 'package:submersion/core/database/database_version_exception.dart';
 import 'package:submersion/core/services/database_location_service.dart';
 
 class DatabaseService {
@@ -86,6 +88,9 @@ class DatabaseService {
       await dbDir.create(recursive: true);
     }
 
+    // Guard: reject databases created by a newer version of the app
+    _assertSchemaVersionCompatible(dbPath);
+
     final file = File(dbPath);
     // Use synchronous NativeDatabase instead of createInBackground
     // Background isolates can cause close() to hang indefinitely during migration
@@ -105,6 +110,9 @@ class DatabaseService {
       await dbDir.create(recursive: true);
     }
 
+    // Guard: reject databases created by a newer version of the app
+    _assertSchemaVersionCompatible(newPath);
+
     // Small delay to ensure any previous database connections are fully released
     // This helps prevent SQLite file locking issues, especially with WAL mode
     await Future.delayed(const Duration(milliseconds: 100));
@@ -147,6 +155,33 @@ class DatabaseService {
     }
   }
 
+  /// Throws [DatabaseVersionMismatchException] if the database file's schema
+  /// version is newer than what this build of the app supports.
+  ///
+  /// Uses raw sqlite3 to read PRAGMA user_version before Drift opens the
+  /// database, ensuring the file is never modified by a stale migration.
+  void _assertSchemaVersionCompatible(String dbPath) {
+    final file = File(dbPath);
+    if (!file.existsSync()) return;
+
+    final db = sqlite3.sqlite3.open(dbPath, mode: sqlite3.OpenMode.readOnly);
+    try {
+      final result = db.select('PRAGMA user_version');
+      if (result.isEmpty) return;
+
+      final storedVersion = result.first.values.first;
+      if (storedVersion is int &&
+          storedVersion > AppDatabase.currentSchemaVersion) {
+        throw DatabaseVersionMismatchException(
+          databaseVersion: storedVersion,
+          appVersion: AppDatabase.currentSchemaVersion,
+        );
+      }
+    } finally {
+      db.dispose();
+    }
+  }
+
   /// Resolve the database path using location service or default
   Future<String> _resolveDatabasePath() async {
     if (_locationService != null) {

lib/main.dart

@@ -5,6 +5,7 @@ import 'package:submersion/core/providers/provider.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
 import 'package:submersion/app.dart';
+import 'package:submersion/core/database/database_version_exception.dart';
 import 'package:submersion/core/domain/entities/storage_config.dart';
 import 'package:submersion/core/services/database_location_service.dart';
 import 'package:submersion/core/services/database_service.dart';
@@ -105,6 +106,46 @@ Future<void> main() async {
     await speciesRepository.seedBuiltInSpecies();
 
     runApp(SubmersionRestart(prefs: prefs));
+  } on DatabaseVersionMismatchException catch (e) {
+    debugPrint('FATAL: $e');
+    runApp(
+      MaterialApp(
+        home: Scaffold(
+          body: SafeArea(
+            child: Padding(
+              padding: const EdgeInsets.all(24),
+              child: Column(
+                mainAxisAlignment: MainAxisAlignment.center,
+                children: [
+                  const Icon(Icons.update, size: 64, color: Colors.orange),
+                  const SizedBox(height: 24),
+                  const Text(
+                    'Update Required',
+                    style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold),
+                    textAlign: TextAlign.center,
+                  ),
+                  const SizedBox(height: 16),
+                  Text(
+                    'Your dive data was saved by a newer version of '
+                    'Submersion (schema v${e.databaseVersion}). This version '
+                    'only supports up to schema v${e.appVersion}.',
+                    style: const TextStyle(fontSize: 14),
+                    textAlign: TextAlign.center,
+                  ),
+                  const SizedBox(height: 16),
+                  const Text(
+                    'Please update Submersion to the latest version. '
+                    'Your data is safe and has not been modified.',
+                    style: TextStyle(fontSize: 14),
+                    textAlign: TextAlign.center,
+                  ),
+                ],
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
   } catch (e, stack) {
     debugPrint('FATAL: App initialization failed: $e');
     debugPrint('$stack');