68 lines
2.6 KiB
Swift
68 lines
2.6 KiB
Swift
import Foundation
|
|
import DataLiteCore
|
|
|
|
/// A protocol for a database service.
|
|
///
|
|
/// `DatabaseServiceProtocol` defines the core capabilities required for
|
|
/// reliable interaction with a database. Conforming implementations provide
|
|
/// execution of client closures with a live connection, transaction wrapping,
|
|
/// reconnection logic, and flexible encryption key management.
|
|
///
|
|
/// This enables building safe and extensible service layers on top of
|
|
/// a database.
|
|
///
|
|
/// ## Topics
|
|
///
|
|
/// ### Key Management
|
|
///
|
|
/// - ``DatabaseServiceKeyProvider``
|
|
/// - ``keyProvider``
|
|
///
|
|
/// ### Database Operations
|
|
///
|
|
/// - ``Perform``
|
|
/// - ``perform(_:)``
|
|
/// - ``perform(in:closure:)``
|
|
public protocol DatabaseServiceProtocol: AnyObject, Sendable {
|
|
/// A closure executed with an active database connection.
|
|
///
|
|
/// Used by the service to safely provide access to `Connection`
|
|
/// within the appropriate execution context.
|
|
///
|
|
/// - Parameter connection: The active database connection.
|
|
/// - Returns: The value returned by the closure.
|
|
/// - Throws: An error if the closure execution fails.
|
|
typealias Perform<T> = (Connection) throws -> T
|
|
|
|
/// The encryption key provider for the database service.
|
|
///
|
|
/// Enables external management of encryption keys.
|
|
/// When set, the service can request a key when establishing or
|
|
/// restoring a connection, and can also notify about errors
|
|
/// encountered while applying a key.
|
|
var keyProvider: DatabaseServiceKeyProvider? { get set }
|
|
|
|
/// Executes the given closure with an active connection.
|
|
///
|
|
/// The closure receives the connection and may perform any
|
|
/// database operations within the current context.
|
|
///
|
|
/// - Parameter closure: The closure that accepts a connection.
|
|
/// - Returns: The value returned by the closure.
|
|
/// - Throws: An error if one occurs during closure execution.
|
|
func perform<T>(_ closure: Perform<T>) throws -> T
|
|
|
|
/// Executes the given closure within a transaction.
|
|
///
|
|
/// If the connection is in autocommit mode, the method automatically
|
|
/// begins a transaction, executes the closure, and commits the changes.
|
|
/// In case of failure, the transaction is rolled back.
|
|
///
|
|
/// - Parameters:
|
|
/// - transaction: The type of transaction to begin.
|
|
/// - closure: The closure that accepts a connection.
|
|
/// - Returns: The value returned by the closure.
|
|
/// - Throws: An error if one occurs during closure execution.
|
|
func perform<T>(in transaction: TransactionType, closure: Perform<T>) throws -> T
|
|
}
|