262 lines
10 KiB
Swift
262 lines
10 KiB
Swift
import Foundation
|
||
import DataLiteCore
|
||
import DataLiteC
|
||
|
||
/// A base database service that handles transactions and posts change notifications.
|
||
///
|
||
/// ## Overview
|
||
///
|
||
/// `DatabaseService` provides a lightweight transactional layer for performing database operations
|
||
/// within a thread-safe execution context. It automatically detects modifications to the database
|
||
/// and posts a ``databaseDidChange`` notification database updates, allowing observers to react to
|
||
/// updates.
|
||
///
|
||
/// This class is intended to be subclassed by higher-level data managers that encapsulate domain
|
||
/// logic while relying on consistent connection and transaction handling.
|
||
///
|
||
/// ## Usage
|
||
///
|
||
/// ```swift
|
||
/// final class NoteService: DatabaseService {
|
||
/// func insertNote(_ text: String) throws {
|
||
/// try perform(in: .deferred) { connection in
|
||
/// let sql = "INSERT INTO notes (text) VALUES (?)"
|
||
/// let stmt = try connection.prepare(sql: sql)
|
||
/// try stmt.bind(text, at: 0)
|
||
/// try stmt.step()
|
||
/// }
|
||
/// }
|
||
/// }
|
||
///
|
||
/// let connection = try Connection(location: .inMemory, options: [])
|
||
/// let service = NoteService(connection: connection)
|
||
/// try service.insertNote("Hello, world!")
|
||
/// ```
|
||
///
|
||
/// ## Topics
|
||
///
|
||
/// ### Initializers
|
||
///
|
||
/// - ``ConnectionService/ConnectionProvider``
|
||
/// - ``ConnectionService/ConnectionConfig``
|
||
/// - ``init(provider:config:queue:center:)``
|
||
/// - ``init(provider:config:queue:)``
|
||
///
|
||
/// ### Performing Operations
|
||
///
|
||
/// - ``ConnectionServiceProtocol/Perform``
|
||
/// - ``perform(_:)``
|
||
/// - ``perform(in:closure:)``
|
||
///
|
||
/// ### Connection Delegate
|
||
///
|
||
/// - ``connection(_:didUpdate:)``
|
||
/// - ``connectionWillCommit(_:)``
|
||
/// - ``connectionDidRollback(_:)``
|
||
///
|
||
/// ### Notifications
|
||
///
|
||
/// - ``databaseDidChange``
|
||
open class DatabaseService:
|
||
ConnectionService,
|
||
DatabaseServiceProtocol,
|
||
ConnectionDelegate,
|
||
@unchecked Sendable
|
||
{
|
||
// MARK: - Properties
|
||
|
||
private let center: NotificationCenter?
|
||
|
||
/// Notification posted after the database content changes with this service.
|
||
public static let databaseDidChange = Notification.Name("DatabaseService.databaseDidChange")
|
||
|
||
// MARK: - Inits
|
||
|
||
/// Creates a database service with a specified notification center.
|
||
///
|
||
/// Configures an internal serial queue for thread-safe access to the database. The connection
|
||
/// itself is not created during initialization — it is established lazily on first use (for
|
||
/// example, inside ``perform(_:)``).
|
||
///
|
||
/// The internal queue is created with QoS `.utility`. If `queue` is provided, it becomes the
|
||
/// target of the internal queue.
|
||
///
|
||
/// - Parameters:
|
||
/// - provider: A closure that returns a new database connection.
|
||
/// - config: An optional configuration closure called after the connection is established and
|
||
/// the encryption key is applied.
|
||
/// - queue: An optional target queue for the internal one.
|
||
/// - center: An optional notification center used to post database change notifications.
|
||
public init(
|
||
provider: @escaping ConnectionProvider,
|
||
config: ConnectionConfig? = nil,
|
||
queue: DispatchQueue? = nil,
|
||
center: NotificationCenter?
|
||
) {
|
||
self.center = center
|
||
super.init(provider: provider, config: config, queue: queue)
|
||
}
|
||
|
||
/// Creates a database service using the default database notification center.
|
||
///
|
||
/// Configures an internal serial queue for thread-safe access to the database. The connection
|
||
/// itself is not created during initialization — it is established lazily on first use (for
|
||
/// example, inside ``perform(_:)``).
|
||
///
|
||
/// The service posts change notifications through ``Foundation/NotificationCenter/databaseCenter``,
|
||
/// which provides a shared channel for observing database events across the application.
|
||
///
|
||
/// The internal queue is created with QoS `.utility`. If `queue` is provided, it becomes the
|
||
/// target of the internal queue.
|
||
///
|
||
/// - Parameters:
|
||
/// - provider: A closure that returns a new database connection.
|
||
/// - config: An optional configuration closure called after the connection is established and
|
||
/// the encryption key is applied.
|
||
/// - queue: An optional target queue for the internal one.
|
||
public required init(
|
||
provider: @escaping ConnectionProvider,
|
||
config: ConnectionConfig? = nil,
|
||
queue: DispatchQueue? = nil
|
||
) {
|
||
self.center = .databaseCenter
|
||
super.init(provider: provider, config: config, queue: queue)
|
||
}
|
||
|
||
// MARK: - Performing Operations
|
||
|
||
/// Executes a closure within the context of a managed database connection.
|
||
///
|
||
/// Runs the operation on the service’s internal queue and ensures that the connection is valid
|
||
/// before use. If the connection is unavailable or fails during execution, this method throws
|
||
/// an error.
|
||
///
|
||
/// After the closure completes, if the database content has changed, the service posts a
|
||
/// ``databaseDidChange`` notification through its configured notification center.
|
||
///
|
||
/// - Parameter closure: The operation to perform using the connection.
|
||
/// - Returns: The result produced by the closure.
|
||
/// - Throws: An error thrown by the closure or the connection.
|
||
public override func perform<T>(_ closure: Perform<T>) throws -> T {
|
||
try super.perform { connection in
|
||
let changes = connection.totalChanges
|
||
defer {
|
||
if changes != connection.totalChanges {
|
||
center?.post(name: Self.databaseDidChange, object: self)
|
||
}
|
||
}
|
||
return try closure(connection)
|
||
}
|
||
}
|
||
|
||
/// Executes a closure inside a transaction when the connection operates in autocommit mode.
|
||
///
|
||
/// The method begins the requested `TransactionType`, runs the closure, and commits the
|
||
/// transaction on success. Failures trigger a rollback. If the SQLite engine reports
|
||
/// `SQLITE_NOTADB` and the key provider allows reconnection, the service re-establishes the
|
||
/// connection and retries the closure once, mirroring the behavior described in
|
||
/// ``DatabaseServiceProtocol``.
|
||
///
|
||
/// - Parameters:
|
||
/// - transaction: The type of transaction to start (for example, `.deferred`).
|
||
/// - closure: The work to run while the transaction is active.
|
||
/// - Returns: The value returned by the closure.
|
||
/// - Throws: Errors from the closure, transaction handling, or connection management.
|
||
///
|
||
/// - Important: The closure may be executed more than once if a reconnection occurs. Ensure it
|
||
/// performs only database operations and does not produce external side effects (such as
|
||
/// sending network requests or posting notifications).
|
||
public func perform<T>(
|
||
in transaction: TransactionType,
|
||
closure: Perform<T>
|
||
) throws -> T {
|
||
try perform { connection in
|
||
guard connection.isAutocommit else {
|
||
return try closure(connection)
|
||
}
|
||
|
||
do {
|
||
try connection.beginTransaction(transaction)
|
||
let result = try closure(connection)
|
||
try connection.commitTransaction()
|
||
return result
|
||
} catch {
|
||
if !connection.isAutocommit {
|
||
try connection.rollbackTransaction()
|
||
}
|
||
|
||
guard
|
||
let error = error as? SQLiteError,
|
||
error.code == SQLITE_NOTADB,
|
||
setNeedsReconnect()
|
||
else {
|
||
throw error
|
||
}
|
||
|
||
return try perform { connection in
|
||
do {
|
||
try connection.beginTransaction(transaction)
|
||
let result = try closure(connection)
|
||
try connection.commitTransaction()
|
||
return result
|
||
} catch {
|
||
if !connection.isAutocommit {
|
||
try connection.rollbackTransaction()
|
||
}
|
||
throw error
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
// MARK: - ConnectionDelegate
|
||
|
||
/// Handles database updates reported by the active connection.
|
||
///
|
||
/// Called after an SQL statement modifies the database content. Subclasses can override this
|
||
/// method to observe specific actions (for example, inserts, updates, or deletes).
|
||
///
|
||
/// - Important: This method must not execute SQL statements or otherwise alter the connection
|
||
/// state.
|
||
///
|
||
/// - Parameters:
|
||
/// - connection: The connection that performed the update.
|
||
/// - action: The SQLite action describing the change.
|
||
open func connection(_ connection: any ConnectionProtocol, didUpdate action: SQLiteAction) {
|
||
}
|
||
|
||
/// Called immediately before the connection commits a transaction.
|
||
///
|
||
/// Subclasses can override this method to perform validation or consistency checks prior to
|
||
/// committing. Throwing an error cancels the commit and triggers a rollback.
|
||
///
|
||
/// - Important: This method must not execute SQL statements or otherwise alter the connection
|
||
/// state.
|
||
///
|
||
/// - Parameter connection: The connection preparing to commit.
|
||
/// - Throws: An error to cancel the commit and roll back the transaction.
|
||
open func connectionWillCommit(_ connection: any ConnectionProtocol) throws {
|
||
}
|
||
|
||
/// Called after the connection rolls back a transaction.
|
||
///
|
||
/// Subclasses can override this method to handle cleanup or recovery logic following a
|
||
/// rollback.
|
||
///
|
||
/// - Important: This method must not execute SQL statements or otherwise alter the connection
|
||
/// state.
|
||
///
|
||
/// - Parameter connection: The connection that rolled back the transaction.
|
||
open func connectionDidRollback(_ connection: any ConnectionProtocol) {
|
||
}
|
||
|
||
// MARK: - Internal Methods
|
||
|
||
override func connect() throws -> any ConnectionProtocol {
|
||
let connection = try super.connect()
|
||
connection.add(delegate: self)
|
||
return connection
|
||
}
|
||
}
|