Add protocol for migration service

Sources/DataRaft/Classes/DatabaseService.swift

@@ -48,7 +48,69 @@ import DataLiteC
 ///
 /// This approach allows you to build reusable service layers on top of a safe, transactional,
 /// and serialized foundation.
-open class DatabaseService: DatabaseServiceProtocol {
+///
+/// ## Error Handling
+///
+/// All database access is serialized using an internal dispatch queue to ensure thread safety.
+/// If a database corruption or decryption failure is detected (e.g., `SQLITE_NOTADB`), the
+/// service attempts to re-establish the connection and, in case of transaction blocks,
+/// retries the entire transaction block exactly once. If the problem persists, the error
+/// is rethrown.
+///
+/// ## Encryption Key Management
+///
+/// If a `keyProvider` is set, the service will use it to retrieve and apply encryption keys
+/// when establishing or re-establishing a database connection. Any error that occurs while
+/// retrieving or applying the encryption key is reported to the provider via
+/// `databaseService(_:didReceive:)`. Non-encryption-related errors (e.g., file access
+/// issues) are not reported to the provider.
+///
+/// ## Reconnect Behavior
+///
+/// The service can automatically reconnect to the database, but this happens only in very specific
+/// circumstances. Reconnection is triggered only when you run a transactional operation using
+/// ``perform(in:closure:)``, and a decryption error (`SQLITE_NOTADB`) occurs during
+/// the transaction. Even then, reconnection is possible only if you have set a ``keyProvider``,
+/// and only if the provider allows it by returning `true` from its
+/// ``DatabaseServiceKeyProvider/databaseServiceShouldReconnect(_:)-84qfz``
+/// method.
+///
+/// When this happens, the service will ask the key provider for a new encryption key, create a new
+/// database connection, and then try to re-run your transaction block one more time. If the second
+/// attempt also fails with the same decryption error, or if reconnection is not allowed, the error is
+/// returned to your code as usual, and no further attempts are made.
+///
+/// It's important to note that reconnection and retrying of transactions never happens outside of
+/// transactional operations, and will never be triggered for other types of errors. All of this logic
+/// runs on the service’s internal queue, so you don’t have to worry about thread safety.
+///
+/// - Important: Because a transaction block can be executed more than once when this
+///   mechanism is triggered, make sure that your block is idempotent and doesn't cause any
+///   side effects outside the database itself.
+///
+/// ## Topics
+///
+/// ### Initializers
+///
+/// - ``init(provider:queue:)``
+/// - ``init(connection:queue:)``
+///
+/// ### Key Management
+///
+/// - ``DatabaseServiceKeyProvider``
+/// - ``keyProvider``
+///
+/// ### Connection Management
+///
+/// - ``ConnectionProvider``
+/// - ``reconnect()``
+///
+/// ### Database Operations
+///
+/// - ``DatabaseServiceProtocol/Perform``
+/// - ``perform(_:)``
+/// - ``perform(in:closure:)``
+open class DatabaseService: DatabaseServiceProtocol, @unchecked Sendable {
     /// A closure that provides a new database connection when invoked.
     ///
     /// `ConnectionProvider` is used to defer the creation of a `Connection` instance
@@ -62,58 +124,33 @@ open class DatabaseService: DatabaseServiceProtocol {
     // MARK: - Properties
     
     private let provider: ConnectionProvider
-    private var connection: Connection
     private let queue: DispatchQueue
     private let queueKey = DispatchSpecificKey<Void>()
+    private var connection: Connection
     
-    /// The object that provides the encryption key for the database connection.
+    /// Provides the encryption key for the database connection.
     ///
-    /// When this property is set, the service attempts to retrieve an encryption key from the
+    /// When this property is set, the service synchronously retrieves and applies an encryption
-    /// provider and apply it to the current database connection. This operation is performed
+    /// key from the provider to the current database connection on the service’s internal queue,
-    /// synchronously on the service’s internal queue to ensure thread safety.
+    /// ensuring thread safety.
     ///
-    /// If an error occurs during key retrieval or application, the service notifies the provider
+    /// If an error occurs during key retrieval or application (for example, if biometric
-    /// by calling `databaseService(_:didReceive:)`.
+    /// authentication is cancelled, the key is unavailable, or decryption fails due to an
+    /// incorrect key), the service notifies the provider by calling
+    /// ``DatabaseServiceKeyProvider/databaseService(_:didReceive:)-xbrk``.
     ///
-    /// This enables external management of encryption keys, including features such as key rotation,
+    /// This mechanism enables external management of encryption keys, supporting scenarios such
-    /// user-scoped encryption, or error handling delegation.
+    /// as key rotation, user-specific encryption, or custom error handling.
-    ///
-    /// - Important: The service does not retry failed key applications. Ensure the provider is
-    ///   correctly configured and able to supply a valid key when needed.
     public weak var keyProvider: DatabaseServiceKeyProvider? {
         didSet {
-            perform { connection in
+            withConnection { connection in
-                do {
+                try? applyKey(to: connection)
-                    if let key = try keyProvider?.databaseServiceKey(self) {
-                        try connection.apply(key)
-                    }
-                } catch {
-                    keyProvider?.databaseService(self, didReceive: error)
-                }
             }
         }
     }
     
     // MARK: - Inits
     
-    /// Creates a new `DatabaseService` using the given connection provider and optional queue.
-    ///
-    /// This convenience initializer wraps the provided autoclosure in a `ConnectionProvider`
-    /// and delegates to the designated initializer. It is useful when passing a simple
-    /// connection expression.
-    ///
-    /// - Parameters:
-    ///   - provider: A closure that returns a `Connection` instance and may throw.
-    ///   - queue: An optional dispatch queue used as a target for internal serialization. If `nil`,
-    ///     a default serial queue with `.utility` QoS is created internally.
-    /// - Throws: Rethrows any error thrown by the connection provider.
-    public convenience init(
-        connection provider: @escaping @autoclosure ConnectionProvider,
-        queue: DispatchQueue? = nil
-    ) rethrows {
-        try self.init(provider: provider, queue: queue)
-    }
-    
     /// Creates a new `DatabaseService` with the specified connection provider and dispatch queue.
     ///
     /// This initializer immediately invokes the `provider` closure to establish the initial database
@@ -139,85 +176,88 @@ open class DatabaseService: DatabaseServiceProtocol {
         }
     }
     
+    /// Creates a new `DatabaseService` using the given connection provider and optional queue.
+    ///
+    /// This convenience initializer wraps the provided autoclosure in a `ConnectionProvider`
+    /// and delegates to the designated initializer. It is useful when passing a simple
+    /// connection expression.
+    ///
+    /// - Parameters:
+    ///   - provider: A closure that returns a `Connection` instance and may throw.
+    ///   - queue: An optional dispatch queue used as a target for internal serialization. If `nil`,
+    ///     a default serial queue with `.utility` QoS is created internally.
+    /// - Throws: Rethrows any error thrown by the connection provider.
+    public convenience init(
+        connection provider: @escaping @autoclosure ConnectionProvider,
+        queue: DispatchQueue? = nil
+    ) rethrows {
+        try self.init(provider: provider, queue: queue)
+    }
+    
     // MARK: - Methods
     
     /// Re-establishes the database connection using the stored connection provider.
     ///
-    /// This method creates a new `Connection` instance by invoking the original provider. If a
+    /// This method synchronously creates a new ``Connection`` instance by invoking the original
-    /// `keyProvider` is set, the method attempts to retrieve and apply an encryption key to the new
+    /// provider on the service’s internal queue. If a ``keyProvider`` is set, the service attempts
-    /// connection. The new connection replaces the existing one.
+    /// to retrieve and apply an encryption key to the new connection.
+    /// If any error occurs during key retrieval or application, the provider is notified via
+    /// ``DatabaseServiceKeyProvider/databaseService(_:didReceive:)-xbrk``,
+    /// and the error is rethrown.
     ///
-    /// The operation is executed synchronously on the internal dispatch queue via `perform(_:)`
+    /// The new connection replaces the existing one only if all steps succeed without errors.
+    ///
+    /// This operation is always executed on the internal dispatch queue (see ``perform(_:)``)
     /// to ensure thread safety.
     ///
-    /// - Throws: Any error thrown during connection creation or while retrieving or applying the
+    /// - Throws: Any error thrown during connection creation or while retrieving or applying
-    ///   encryption key.
+    ///   the encryption key. Only encryption-related errors are reported to the ``keyProvider``.
     public func reconnect() throws {
-        try perform { _ in
+        try withConnection { _ in
             let connection = try provider()
-            if let key = try keyProvider?.databaseServiceKey(self) {
+            try applyKey(to: connection)
-                try connection.apply(key)
-            }
             self.connection = connection
         }
     }
     
     /// Executes the given closure using the active database connection.
     ///
-    /// This method ensures thread-safe access to the underlying `Connection` by synchronizing
+    /// Ensures thread-safe access to the underlying ``Connection`` by synchronizing execution on
-    /// execution on an internal serial dispatch queue. If the call is already on that queue, the
+    /// the service’s internal serial dispatch queue. If the call is already running on this queue,
-    /// closure is executed directly to avoid unnecessary dispatching.
+    /// the closure is executed directly to avoid unnecessary dispatching.
-    ///
-    /// If the closure throws a `SQLiteError` with code `SQLITE_NOTADB` (e.g., when the database file
-    /// is corrupted or invalid), the service attempts to re-establish the connection by calling
-    /// ``reconnect()``. The error is still rethrown after reconnection.
     ///
     /// - Parameter closure: A closure that takes the active connection and returns a result.
     /// - Returns: The value returned by the closure.
-    /// - Throws: Any error thrown by the closure or during reconnection logic.
+    /// - Throws: Any error thrown by the closure.
     public func perform<T>(_ closure: Perform<T>) rethrows -> T {
-        do {
+        try withConnection(closure)
-            switch DispatchQueue.getSpecific(key: queueKey) {
-            case .none: return try queue.asyncAndWait { try closure(connection) }
-            case .some: return try closure(connection)
-            }
-        } catch {
-            switch error {
-            case let error as Connection.Error:
-                if error.code == SQLITE_NOTADB {
-                    try reconnect()
-                }
-                fallthrough
-            default:
-                throw error
-            }
-        }
     }
     
     /// Executes a closure inside a transaction if the connection is in autocommit mode.
     ///
-    /// If the current connection is in autocommit mode, a new transaction of the specified type
+    /// If the connection is in autocommit mode, starts a new transaction of the specified type,
-    /// is started, and the closure is executed within it. If the closure completes successfully,
+    /// executes the closure within it, and commits the transaction on success. If the closure
-    /// the transaction is committed. If an error is thrown, the transaction is rolled back.
+    /// throws, the transaction is rolled back.
     ///
-    /// If the thrown error is a `SQLiteError` with code `SQLITE_NOTADB`, the service attempts to
+    /// If the closure throws a `Connection.Error` with code `SQLITE_NOTADB` and reconnecting is
-    /// reconnect and retries the entire transaction block exactly once.
+    /// allowed, the service attempts to reconnect and retries the entire transaction block once.
     ///
-    /// If the connection is already within a transaction (i.e., not in autocommit mode),
+    /// If already inside a transaction (not in autocommit mode), executes the closure directly
-    /// the closure is executed directly without starting a new transaction.
+    /// without starting a new transaction.
     ///
     /// - Parameters:
-    ///   - transaction: The type of transaction to begin (e.g., `deferred`, `immediate`, `exclusive`).
+    ///   - transaction: The type of transaction to begin.
     ///   - closure: A closure that takes the active connection and returns a result.
     /// - Returns: The value returned by the closure.
-    /// - Throws: Any error thrown by the closure, transaction control statements,
+    /// - Throws: Any error thrown by the closure, transaction control statements, or reconnect logic.
-    ///   or reconnect logic.
+    ///
+    /// - Important: The closure may be executed more than once. Ensure it is idempotent.
     public func perform<T>(
         in transaction: TransactionType,
         closure: Perform<T>
     ) rethrows -> T {
+        try withConnection { connection in
             if connection.isAutocommit {
-            try perform { connection in
                 do {
                     try connection.beginTransaction(transaction)
                     let result = try closure(connection)
@@ -226,12 +266,13 @@ open class DatabaseService: DatabaseServiceProtocol {
                 } catch {
                     try connection.rollbackTransaction()
                     guard let error = error as? Connection.Error,
-                          error.code == SQLITE_NOTADB
+                          error.code == SQLITE_NOTADB,
+                          shouldReconnect
                     else { throw error }
                     
                     try reconnect()
                     
-                    return try perform { connection in
+                    return try withConnection { connection in
                         do {
                             try connection.beginTransaction(transaction)
                             let result = try closure(connection)
@@ -243,9 +284,35 @@ open class DatabaseService: DatabaseServiceProtocol {
                         }
                     }
                 }
-            }
             } else {
-            try perform(closure)
+                return try closure(connection)
+            }
+        }
+    }
+}
+
+private extension DatabaseService {
+    var shouldReconnect: Bool {
+        keyProvider?.databaseServiceShouldReconnect(self) ?? false
+    }
+    
+    func withConnection<T>(_ closure: Perform<T>) rethrows -> T {
+        switch DispatchQueue.getSpecific(key: queueKey) {
+        case .none: try queue.asyncAndWait { try closure(connection) }
+        case .some: try closure(connection)
+        }
+    }
+    
+    func applyKey(to connection: Connection) throws {
+        do {
+            if let key = try keyProvider?.databaseServiceKey(self) {
+                let sql = "SELECT count(*) FROM sqlite_master"
+                try connection.apply(key)
+                try connection.execute(raw: sql)
+            }
+        } catch {
+            keyProvider?.databaseService(self, didReceive: error)
+            throw error
         }
     }
 }

Sources/DataRaft/Classes/MigrationService.swift

@@ -1,110 +1,113 @@
 import Foundation
 import DataLiteCore
 
-/// A service responsible for managing and applying database migrations in a versioned manner.
+/// Thread-safe service for executing ordered database schema migrations.
 ///
-/// `MigrationService` manages a collection of migrations identified by versions and script URLs,
+/// `MigrationService` stores registered migrations and applies them sequentially
-/// and applies them sequentially to update the database schema. It ensures that each migration
+/// to update the database schema. Each migration runs only once, in version order,
-/// is applied only once, and in the correct version order based on the current database version.
+/// based on the current schema version stored in the database.
 ///
-/// This service is generic over a `VersionStorage` implementation that handles storing and
+/// The service is generic over:
-/// retrieving the current database version. Migrations must have unique versions and script URLs
+/// - `Service`: a database service conforming to ``DatabaseServiceProtocol``
-/// to prevent duplication.
+/// - `Storage`: a version storage conforming to ``VersionStorage``
+///
+/// Migrations are identified by version and script URL. Both must be unique
+/// across all registered migrations.
+///
+/// Execution is performed inside a single `.exclusive` transaction, ensuring
+/// that either all pending migrations are applied successfully or none are.
+/// On error, the database state is rolled back to the original version.
+///
+/// This type is safe to use from multiple threads.
 ///
 /// ```swift
 /// let connection = try Connection(location: .inMemory, options: .readwrite)
 /// let storage = UserVersionStorage<BitPackVersion>()
-/// let service = MigrationService(storage: storage, connection: connection)
+/// let service = MigrationService(service: connectionService, storage: storage)
 ///
 /// try service.add(Migration(version: "1.0.0", byResource: "v_1_0_0.sql")!)
 /// try service.add(Migration(version: "1.0.1", byResource: "v_1_0_1.sql")!)
-/// try service.add(Migration(version: "1.1.0", byResource: "v_1_1_0.sql")!)
-/// try service.add(Migration(version: "1.2.0", byResource: "v_1_2_0.sql")!)
-///
 /// try service.migrate()
 /// ```
 ///
 /// ### Custom Versions and Storage
 ///
-/// You can customize versioning by providing your own `Version` type conforming to
+/// You can supply a custom `Version` type conforming to ``VersionRepresentable``
-/// ``VersionRepresentable``, which supports comparison, hashing, and identity checks.
+/// and a `VersionStorage` implementation that determines how and where the
-///
+/// version is persisted (e.g., `PRAGMA user_version`, metadata table, etc.).
-/// The storage backend (`VersionStorage`) defines how the version is persisted, such as
+public final class MigrationService<
-/// in a pragma, table, or metadata.
+    Service: DatabaseServiceProtocol,
-///
+    Storage: VersionStorage
-/// This allows using semantic versions, integers, or other schemes, and storing them
+>:
-/// in custom places.
+    MigrationServiceProtocol,
-public final class MigrationService<Service: DatabaseServiceProtocol, Storage: VersionStorage> {
+    @unchecked Sendable
-    /// The version type used by this migration service, derived from the storage type.
+{
+    /// Schema version type used for migration ordering.
     public typealias Version = Storage.Version
     
-    /// Errors that may occur during migration registration or execution.
-    public enum Error: Swift.Error {
-        /// A migration with the same version or script URL was already registered.
-        case duplicateMigration(Migration<Version>)
-        
-        /// Migration execution failed, with optional reference to the failed migration.
-        case migrationFailed(Migration<Version>?, Swift.Error)
-        
-        /// The migration script is empty.
-        case emptyMigrationScript(Migration<Version>)
-    }
-    
-    // MARK: - Properties
-    
     private let service: Service
     private let storage: Storage
+    private var mutex = pthread_mutex_t()
     private var migrations = Set<Migration<Version>>()
     
-    /// The encryption key provider delegated to the underlying database service.
+    /// Encryption key provider delegated to the underlying database service.
     public weak var keyProvider: DatabaseServiceKeyProvider? {
         get { service.keyProvider }
         set { service.keyProvider = newValue }
     }
     
-    // MARK: - Inits
+    /// Creates a migration service with the given database service and storage.
-    
-    /// Creates a new migration service with the given database service and version storage.
     ///
     /// - Parameters:
-    ///   - service: The database service used to perform migrations.
+    ///   - service: Database service used to execute migrations.
-    ///   - storage: The version storage implementation used to track the current schema version.
+    ///   - storage: Version storage for reading and writing schema version.
     public init(
         service: Service,
         storage: Storage
     ) {
         self.service = service
         self.storage = storage
+        pthread_mutex_init(&mutex, nil)
     }
     
-    // MARK: - Migration Management
+    deinit {
+        pthread_mutex_destroy(&mutex)
+    }
     
-    /// Registers a new migration.
+    /// Registers a new migration, ensuring version and script URL uniqueness.
-    ///
-    /// Ensures that no other migration with the same version or script URL has been registered.
     ///
     /// - Parameter migration: The migration to register.
-    /// - Throws: ``Error/duplicateMigration(_:)`` if the migration version or script URL duplicates an existing one.
+    /// - Throws: ``MigrationError/duplicateMigration(_:)`` if the migration's
-    public func add(_ migration: Migration<Version>) throws {
+    ///   version or script URL is already registered.
+    public func add(_ migration: Migration<Version>) throws(MigrationError<Version>) {
+        pthread_mutex_lock(&mutex)
+        defer { pthread_mutex_unlock(&mutex) }
         guard !migrations.contains(where: {
             $0.version == migration.version
             || $0.scriptURL == migration.scriptURL
         }) else {
-            throw Error.duplicateMigration(migration)
+            throw .duplicateMigration(migration)
         }
         migrations.insert(migration)
     }
     
-    /// Executes all pending migrations in ascending version order.
+    /// Executes all pending migrations inside a single exclusive transaction.
     ///
-    /// This method retrieves the current schema version from the storage, filters and sorts
+    /// This method retrieves the current schema version from storage, then determines
-    /// pending migrations, executes each migration script within a single exclusive transaction,
+    /// which migrations have a higher version. The selected migrations are sorted in
-    /// and updates the schema version on success.
+    /// ascending order and each one's SQL script is executed in sequence. When all
+    /// scripts complete successfully, the stored version is updated to the highest
+    /// applied migration.
     ///
-    /// If a migration script is empty or a migration fails, the process aborts and rolls back changes.
+    /// If a script is empty or execution fails, the process aborts and the transaction
+    /// is rolled back, leaving the database unchanged.
     ///
-    /// - Throws: ``Error/migrationFailed(_:_:)`` if a migration script fails or if updating the version fails.
+    /// - Throws: ``MigrationError/emptyMigrationScript(_:)`` if a script is empty.
-    public func migrate() throws {
+    /// - Throws: ``MigrationError/migrationFailed(_:_:)`` if execution or version
+    ///   update fails.
+    public func migrate() throws(MigrationError<Version>) {
+        pthread_mutex_lock(&mutex)
+        defer { pthread_mutex_unlock(&mutex) }
         do {
             try service.perform(in: .exclusive) { connection in
                 try storage.prepare(connection)
@@ -116,12 +119,12 @@ public final class MigrationService<Service: DatabaseServiceProtocol, Storage: V
                 for migration in migrations {
                     let script = try migration.script
                     guard !script.isEmpty else {
-                        throw Error.emptyMigrationScript(migration)
+                        throw MigrationError.emptyMigrationScript(migration)
                     }
                     do {
                         try connection.execute(sql: script)
                     } catch {
-                        throw Error.migrationFailed(migration, error)
+                        throw MigrationError.migrationFailed(migration, error)
                     }
                 }
                 
@@ -129,10 +132,10 @@ public final class MigrationService<Service: DatabaseServiceProtocol, Storage: V
                     try storage.setVersion(connection, version)
                 }
             }
-        } catch let error as Error {
+        } catch let error as MigrationError<Version> {
             throw error
         } catch {
-            throw Error.migrationFailed(nil, error)
+            throw .migrationFailed(nil, error)
         }
     }
 }

Sources/DataRaft/Classes/RowDatabaseService.swift

@@ -44,7 +44,11 @@ import DataLiteCoder
 /// `RowDatabaseService` encourages a reusable, type-safe pattern for
 /// model-based interaction with SQLite while preserving thread safety
 /// and transactional integrity.
-open class RowDatabaseService: DatabaseService, RowDatabaseServiceProtocol {
+open class RowDatabaseService:
+    DatabaseService,
+    RowDatabaseServiceProtocol,
+    @unchecked Sendable
+{
     // MARK: - Properties
     
     /// The encoder used to serialize values into row representations.

Sources/DataRaft/Classes/UserVersionStorage.swift

@@ -13,7 +13,7 @@ import DataLiteCore
 /// defined by the application.
 public final class UserVersionStorage<
     Version: VersionRepresentable & RawRepresentable
->: VersionStorage where Version.RawValue == UInt32 {
+>: Sendable, VersionStorage where Version.RawValue == UInt32 {
     /// Errors related to reading or decoding the version.
     public enum Error: Swift.Error {
         /// The stored `user_version` could not be decoded into a valid `Version` case.

Sources/DataRaft/Enums/MigrationError.swift

@@ -0,0 +1,14 @@
+import Foundation
+import DataLiteCore
+
+/// Errors that may occur during migration registration or execution.
+public enum MigrationError<Version: VersionRepresentable>: Error {
+    /// A migration with the same version or script URL was already registered.
+    case duplicateMigration(Migration<Version>)
+    
+    /// Migration execution failed, with optional reference to the failed migration.
+    case migrationFailed(Migration<Version>?, Error)
+    
+    /// The migration script is empty.
+    case emptyMigrationScript(Migration<Version>)
+}

Sources/DataRaft/Protocols/DatabaseServiceKeyProvider.swift

@@ -3,51 +3,122 @@ import DataLiteCore
 
 /// A protocol for supplying encryption keys to `DatabaseService` instances.
 ///
-/// `DatabaseServiceKeyProvider` allows database services to delegate the responsibility of
+/// `DatabaseServiceKeyProvider` encapsulates all responsibilities for managing encryption keys
-/// retrieving, managing, and applying encryption keys. This enables separation of concerns
+/// for one or more `DatabaseService` instances. It allows a database service to delegate key
-/// and allows for advanced strategies such as per-user key derivation, secure hardware-backed
+/// retrieval, secure storage, rotation, and access control, enabling advanced security strategies
-/// storage, or biometric access control.
+/// such as per-user key derivation, hardware-backed keys, biometric authentication, or ephemeral
+/// in-memory secrets.
 ///
-/// When assigned to a `DatabaseService`, the provider is queried automatically whenever a
+/// The provider is queried automatically by the database service whenever a new connection
-/// connection is created or re-established (e.g., during service initialization or reconnect).
+/// is created or re-established (for example, during service initialization, after a reconnect,
+/// or when the service requests a key rotation).
 ///
-/// You can also implement error handling or diagnostics via the optional
+/// Error handling and diagnostics related specifically to encryption or key operations
-/// ``databaseService(_:didReceive:)`` method.
+/// (such as when a key is unavailable, authentication is denied, or decryption fails)
+/// are reported to the provider via the optional ``databaseService(_:didReceive:)`` callback.
+/// The provider is **not** notified of generic database or connection errors unrelated to
+/// encryption.
 ///
-/// - Tip: You may throw from ``databaseServiceKey(_:)`` to indicate that the key is temporarily
+/// - Important: This protocol is **exclusively** for cryptographic key management.
-///   unavailable or access is denied.
+///   It must not be used for generic database error handling or for concerns unrelated to
+///   encryption, authorization, or key lifecycle.
+///
+/// ## Key Availability
+///
+/// There are two distinct scenarios for returning a key:
+///
+/// - **No Encryption Needed:**
+///   Return `nil` if the target database does not require encryption (i.e., should be opened
+///   in plaintext mode). This is not an error; the database service will attempt to open the
+///   database without a key. If the database is in fact encrypted, this will result in a
+///   decryption error at the SQLite level (e.g., `SQLITE_NOTADB`), which is handled by the
+///   database service as a normal failure.
+///
+/// - **Key Temporarily Unavailable:**
+///   Also return `nil` if the key is *temporarily* unavailable for any reason (for example,
+///   the user has not yet authenticated, the device is locked, a remote key is still loading,
+///   or UI authorization has not been granted).
+///   Returning `nil` in this case means the database service will not attempt to open
+///   the database with a key. This will not trigger an error callback.
+///   When the key later becomes available (for example, after user authentication or
+///   successful network retrieval), **the provider is responsible for calling**
+///   ``DatabaseService/reconnect()`` on the service to re-attempt the operation with the key.
+///
+/// - **Error Situations:**
+///   Only throw an error if a *permanent* or *unexpected* failure occurs (for example,
+///   a hardware security error, a fatal storage problem, or a cryptographic failure
+///   that cannot be resolved by waiting or user action).
+///   Thrown errors will be reported to the provider via the error callback, and may be
+///   surfaced to the UI or logs.
+///
+/// - Tip: Never throw for temporary unavailability (such as "user has not unlocked" or
+///   "still waiting for user action")—just return `nil` in these cases.
+///   Use thrown errors only for non-recoverable or unexpected failures.
+///
+/// ## Error Callback
+///
+/// The method ``databaseService(_:didReceive:)`` will be called only for errors thrown by
+/// ``databaseServiceKey(_:)`` or by the key application process (such as if the key fails
+/// to decrypt the database).
+/// It will *not* be called for generic database or connection errors.
+///
+/// Implement this method if you wish to log, recover from, or respond to permanent key-related
+/// failures (such as prompting the user, resetting state, or displaying errors).
 public protocol DatabaseServiceKeyProvider: AnyObject {
     /// Returns the encryption key to be applied to the given database service.
     ///
-    /// This method is invoked by the `DatabaseService` during initialization or reconnection
+    /// This method is invoked by the `DatabaseService` during connection initialization,
-    /// to retrieve the encryption key that should be applied to the new connection.
+    /// reconnection, or explicit key rotation. Implementations may return a static key,
-    ///
+    /// derive it from external data, fetch it from secure hardware, or perform required
-    /// Implementations may return a static key, derive it from metadata, or load it from
+    /// user authentication.
-    /// secure storage. If the key is unavailable (e.g., user not authenticated, system locked),
-    /// this method may throw to indicate failure.
     ///
     /// - Parameter service: The requesting database service.
-    /// - Returns: A `Connection.Key` representing the encryption key.
+    /// - Returns: A `Connection.Key` representing the encryption key, or `nil` if encryption is
-    /// - Throws: Any error indicating that the key cannot be retrieved.
+    ///   not required for this database or the key is temporarily unavailable. Returning `nil`
-    func databaseServiceKey(_ service: DatabaseService) throws -> Connection.Key
+    ///   will cause the database service to attempt opening the database in plaintext mode.
+    ///   If the database is actually encrypted, access will fail with a decryption error.
+    /// - Throws: Only throw for unrecoverable or unexpected errors (such as hardware failure,
+    ///   fatal storage issues, or irrecoverable cryptographic errors). Do **not** throw for
+    ///   temporary unavailability; instead, return `nil` and call ``DatabaseService/reconnect()``
+    ///   later when the key becomes available.
+    ///
+    /// - Note: This method may be called multiple times during the lifecycle of a service,
+    ///   including after a failed decryption attempt or key rotation event.
+    func databaseServiceKey(_ service: DatabaseService) throws -> Connection.Key?
     
-    /// Notifies the provider that the database service encountered an error while applying a key.
+    /// Notifies the provider that the database service encountered an error
+    /// related to key retrieval or application.
     ///
-    /// This method is called when the service fails to retrieve or apply the encryption key.
+    /// This method is called **only** when the service fails to retrieve or apply an
-    /// You can use it to report diagnostics, attempt recovery, or update internal state.
+    /// encryption key (e.g., if ``databaseServiceKey(_:)`` throws, or if the key fails
+    /// to decrypt the database due to a password/key mismatch).
     ///
-    /// The default implementation is a no-op.
+    /// Use this callback to report diagnostics, trigger recovery logic, prompt the user
+    /// for authentication, or update internal state.
+    /// By default, this method does nothing; implement it only if you need to respond
+    /// to key-related failures.
     ///
     /// - Parameters:
     ///   - service: The database service reporting the error.
     ///   - error: The error encountered during key retrieval or application.
     func databaseService(_ service: DatabaseService, didReceive error: Error)
+    
+    /// Informs the service whether it should attempt to reconnect automatically.
+    ///
+    /// Return `true` if the service should retry connecting (for example, if the key may
+    /// become available shortly). By default, returns `false`.
+    ///
+    /// - Parameter service: The database service.
+    /// - Returns: `true` to retry, `false` to abort.
+    func databaseServiceShouldReconnect(_ service: DatabaseService) -> Bool
 }
 
 public extension DatabaseServiceKeyProvider {
-    /// Default no-op implementation of error handling callback.
+    /// Default no-op implementation for key-related error reporting.
-    ///
-    /// This allows conforming types to ignore the error reporting mechanism
-    /// if they do not need to respond to key failures.
     func databaseService(_ service: DatabaseService, didReceive error: Error) {}
+    
+    /// Default implementation disables automatic reconnect attempts.
+    func databaseServiceShouldReconnect(_ service: DatabaseService) -> Bool {
+        false
+    }
 }

Sources/DataRaft/Protocols/DatabaseServiceProtocol.swift

@@ -3,51 +3,84 @@ import DataLiteCore
 
 /// A protocol that defines a common interface for working with a database connection.
 ///
-/// Conforming types provide methods for executing closures with a live `Connection`, optionally
+/// `DatabaseServiceProtocol` abstracts the core operations required to safely interact with a
-/// wrapped in transactions. These closures are guaranteed to execute in a thread-safe and
+/// SQLite-compatible database. Conforming types provide thread-safe execution of closures with a live
-/// serialized manner. Implementations may also support reconnecting and managing encryption keys.
+/// `Connection`, optional transaction support, reconnection logic, and pluggable encryption key
+/// management via a ``DatabaseServiceKeyProvider``.
+///
+/// This protocol forms the foundation for safe, modular service layers on top of a database.
+///
+/// ## Topics
+///
+/// ### Key Management
+///
+/// - ``DatabaseServiceKeyProvider``
+/// - ``keyProvider``
+///
+/// ### Connection Management
+///
+/// - ``reconnect()``
+///
+/// ### Database Operations
+///
+/// - ``Perform``
+/// - ``perform(_:)``
+/// - ``perform(in:closure:)``
 public protocol DatabaseServiceProtocol: AnyObject {
     /// A closure that performs a database operation using an active connection.
     ///
-    /// The `Perform<T>` alias defines the signature for a database operation block
+    /// The `Perform<T>` type alias defines a closure signature for a database operation that
-    /// that receives a live `Connection` and either returns a result or throws an error.
+    /// receives a live `Connection` and returns a value or throws an error. This enables
-    /// It is commonly used to express atomic units of work in ``perform(_:)`` or
+    /// callers to express discrete, atomic database operations for execution via
-    /// ``perform(in:closure:)`` calls.
+    /// ``perform(_:)`` or ``perform(in:closure:)``.
     ///
-    /// - Parameter T: The result type returned by the closure.
+    /// - Parameter connection: The active database connection.
-    /// - Returns: A value of type `T` produced by the closure.
+    /// - Returns: The result of the operation.
-    /// - Throws: Any error that occurs during execution of the database operation.
+    /// - Throws: Any error thrown during execution of the operation.
     typealias Perform<T> = (Connection) throws -> T
     
     /// The object responsible for providing encryption keys for the database connection.
     ///
-    /// When assigned, the key provider will be queried for a new key and applied to the current
+    /// When assigned, the key provider will be queried for a key and applied to the current
-    /// connection, if available.
+    /// connection, if available. If key retrieval or application fails, the error is reported
+    /// via `databaseService(_:didReceive:)` and not thrown from the setter.
+    ///
+    /// - Important: Setting this property does not guarantee that the connection becomes available;
+    ///   error handling is asynchronous via callback.
     var keyProvider: DatabaseServiceKeyProvider? { get set }
     
     /// Re-establishes the database connection using the stored provider.
     ///
-    /// If a `keyProvider` is set, the returned connection will attempt to apply a new key.
+    /// If a `keyProvider` is set, the method attempts to retrieve and apply a key
+    /// to the new connection. All errors encountered during connection creation or
+    /// key application are thrown. If an error occurs that is related to encryption key
+    /// retrieval or application, it is also reported to the `DatabaseServiceKeyProvider`
+    /// via its `databaseService(_:didReceive:)` callback.
     ///
     /// - Throws: Any error that occurs during connection creation or key application.
     func reconnect() throws
     
-    /// Executes the given closure with a live connection.
+    /// Executes the given closure with a live connection in a thread-safe manner.
     ///
-    /// - Parameter closure: The operation to execute.
+    /// All invocations are serialized to prevent concurrent database access.
+    ///
+    /// - Parameter closure: The database operation to perform.
     /// - Returns: The result produced by the closure.
-    /// - Throws: Any error thrown during execution.
+    /// - Throws: Any error thrown by the closure.
     func perform<T>(_ closure: Perform<T>) rethrows -> T
     
     /// Executes the given closure within a transaction.
     ///
-    /// If no transaction is active, a new one is started and committed or rolled back as needed.
+    /// If no transaction is active, a new transaction of the specified type is started. The closure
+    /// is executed atomically: if it succeeds, the transaction is committed; if it throws, the
+    /// transaction is rolled back. If a transaction is already active, the closure is executed
+    /// without starting a new one.
     ///
     /// - Parameters:
-    ///   - transaction: The transaction type to begin.
+    ///   - transaction: The type of transaction to begin (e.g., `deferred`, `immediate`, `exclusive`).
-    ///   - closure: The operation to execute within the transaction.
+    ///   - closure: The database operation to perform within the transaction.
     /// - Returns: The result produced by the closure.
-    /// - Throws: Any error thrown by the closure or transaction.
+    /// - Throws: Any error thrown by the closure or transaction control statements.
     func perform<T>(
         in transaction: TransactionType,
         closure: Perform<T>

Sources/DataRaft/Protocols/MigrationServiceProtocol.swift

@@ -0,0 +1,43 @@
+import Foundation
+
+/// Protocol for managing and running database schema migrations.
+public protocol MigrationServiceProtocol: AnyObject {
+    /// Type representing the schema version for migrations.
+    associatedtype Version: VersionRepresentable
+    
+    /// Provider of encryption keys for the database service.
+    var keyProvider: DatabaseServiceKeyProvider? { get set }
+    
+    /// Adds a migration to be executed by the service.
+    ///
+    /// - Parameter migration: The migration to register.
+    /// - Throws: ``MigrationError/duplicateMigration(_:)`` if a migration with
+    ///   the same version or script URL is already registered.
+    func add(_ migration: Migration<Version>) throws(MigrationError<Version>)
+    
+    /// Runs all pending migrations in ascending version order.
+    ///
+    /// - Throws: ``MigrationError/emptyMigrationScript(_:)`` if a migration
+    ///   script is empty.
+    /// - Throws: ``MigrationError/migrationFailed(_:_:)`` if a script execution
+    ///   or version update fails.
+    func migrate() throws(MigrationError<Version>)
+}
+
+@available(iOS 13.0, *)
+@available(macOS 10.15, *)
+public extension MigrationServiceProtocol where Self: Sendable {
+    /// Asynchronously runs all pending migrations in ascending order.
+    ///
+    /// Performs the same logic as ``migrate()``, but runs asynchronously.
+    ///
+    /// - Throws: ``MigrationError/emptyMigrationScript(_:)`` if a migration
+    ///   script is empty.
+    /// - Throws: ``MigrationError/migrationFailed(_:_:)`` if a script execution
+    ///   or version update fails.
+    func migrate() async throws {
+        try await Task(priority: .utility) {
+            try self.migrate()
+        }.value
+    }
+}

Tests/DataRaftTests/Classes/DatabaseServiceTests.swift

@@ -54,9 +54,13 @@ class DatabaseServiceTests: DatabaseServiceKeyProvider {
         try? FileManager.default.removeItem(at: fileURL)
     }
     
-    func databaseServiceKey(_ service: DatabaseService) throws -> Connection.Key {
+    func databaseServiceKey(_ service: DatabaseService) throws -> Connection.Key? {
         currentKey
     }
+    
+    func databaseServiceShouldReconnect(_ service: DatabaseService) -> Bool {
+        true
+    }
 }
 
 extension DatabaseServiceTests {

Tests/DataRaftTests/Classes/MigrationServiceTests.swift

@@ -4,6 +4,7 @@ import DataLiteCore
 
 @Suite struct MigrationServiceTests {
     private typealias MigrationService = DataRaft.MigrationService<DatabaseService, VersionStorage>
+    private typealias MigrationError = DataRaft.MigrationError<MigrationService.Version>
     
     private var connection: Connection!
     private var migrationService: MigrationService!
@@ -25,25 +26,25 @@ import DataLiteCore
         do {
             try migrationService.add(migration3)
             Issue.record("Expected duplicateMigration error for version \(migration3.version)")
-        } catch MigrationService.Error.duplicateMigration(let migration) {
+        } catch MigrationError.duplicateMigration(let migration) {
             #expect(migration == migration3)
         } catch {
             Issue.record("Unexpected error: \(error)")
         }
     }
     
-    @Test func migrate() throws {
+    @Test func migrate() async throws {
         let migration1 = Migration<Int32>(version: 1, byResource: "migration_1", extension: "sql", in: .module)!
         let migration2 = Migration<Int32>(version: 2, byResource: "migration_2", extension: "sql", in: .module)!
         
         try migrationService.add(migration1)
         try migrationService.add(migration2)
-        try migrationService.migrate()
+        try await migrationService.migrate()
         
         #expect(connection.userVersion == 2)
     }
     
-    @Test func migrateWithError() throws {
+    @Test func migrateError() async throws {
         let migration1 = Migration<Int32>(version: 1, byResource: "migration_1", extension: "sql", in: .module)!
         let migration2 = Migration<Int32>(version: 2, byResource: "migration_2", extension: "sql", in: .module)!
         let migration3 = Migration<Int32>(version: 3, byResource: "migration_3", extension: "sql", in: .module)!
@@ -53,9 +54,9 @@ import DataLiteCore
         try migrationService.add(migration3)
         
         do {
-            try migrationService.migrate()
+            try await migrationService.migrate()
             Issue.record("Expected migrationFailed error for version \(migration3.version)")
-        } catch MigrationService.Error.migrationFailed(let migration, _) {
+        } catch MigrationError.migrationFailed(let migration, _) {
             #expect(migration == migration3)
         } catch {
             Issue.record("Unexpected error: \(error)")
@@ -64,7 +65,7 @@ import DataLiteCore
         #expect(connection.userVersion == 0)
     }
     
-    @Test func migrateWithEmptyMigration() throws {
+    @Test func migrateEmpty() async throws {
         let migration1 = Migration<Int32>(version: 1, byResource: "migration_1", extension: "sql", in: .module)!
         let migration2 = Migration<Int32>(version: 2, byResource: "migration_2", extension: "sql", in: .module)!
         let migration4 = Migration<Int32>(version: 4, byResource: "migration_4", extension: "sql", in: .module)!
@@ -74,9 +75,9 @@ import DataLiteCore
         try migrationService.add(migration4)
         
         do {
-            try migrationService.migrate()
+            try await migrationService.migrate()
             Issue.record("Expected migrationFailed error for version \(migration4.version)")
-        } catch MigrationService.Error.emptyMigrationScript(let migration) {
+        } catch MigrationError.emptyMigrationScript(let migration) {
             #expect(migration == migration4)
         } catch {
             Issue.record("Unexpected error: \(error)")