angd-dev/data-raft
1
0
Fork 0
Code Pull Requests Releases Activity

DataRaft swift package

Browse Source
This commit is contained in:
Oleksii Zghurskyi
2025-05-18 17:47:22 +03:00
parent d64c6b2ef2
commit 1b2cdaf23e
23 changed files with 1862 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
Sources/DataRaft/Classes/DatabaseService.swift Normal file
View File

@@ -0,0 +1,251 @@
import Foundation
import DataLiteCore
import DataLiteC
/// A base class for services that operate on a database connection.
///
/// `DatabaseService` provides a shared interface for executing operations on a `Connection`,
/// with support for transaction handling and optional request serialization.
///
/// Subclasses can use this base to coordinate safe, synchronous access to the database
/// without duplicating concurrency or transaction logic.
///
/// For example, you can define a custom service for managing notes:
///
/// ```swift
/// final class NoteService: DatabaseService {
/// func insertNote(_ text: String) throws {
/// try perform { connection in
/// let stmt = try connection.prepare(
/// sql: "INSERT INTO notes (text) VALUES (?)"
/// )
/// try stmt.bind(text, at: 0)
/// try stmt.step()
/// }
/// }
///
/// func fetchNotes() throws -> [String] {
/// try perform { connection in
/// let stmt = try connection.prepare(sql: "SELECT text FROM notes")
/// var result: [String] = []
/// while try stmt.step() {
/// if let text: String = stmt.columnValue(at: 0) {
/// result.append(text)
/// }
/// }
/// return result
/// }
/// }
/// }
///
/// let connection = try Connection(location: .inMemory, options: .readwrite)
/// let service = NoteService(connection: connection)
///
/// try service.insertNote("Hello, world!")
/// let notes = try service.fetchNotes()
/// print(notes) // ["Hello, world!"]
/// ```
///
/// This approach allows you to build reusable service layers on top of a safe, transactional,
/// and serialized foundation.
open class DatabaseService: DatabaseServiceProtocol {
/// A closure that provides a new database connection when invoked.
///
/// `ConnectionProvider` is used to defer the creation of a `Connection` instance
/// until it is actually needed. It can throw errors if the connection cannot be
/// established or configured correctly.
///
/// - Returns: A valid `Connection` instance.
/// - Throws: Any error encountered while opening or configuring the connection.
public typealias ConnectionProvider = () throws -> Connection
// MARK: - Properties
private let provider: ConnectionProvider
private var connection: Connection
private let queue: DispatchQueue
private let queueKey = DispatchSpecificKey<Void>()
/// The object that provides the encryption key for the database connection.
///
/// When this property is set, the service attempts to retrieve an encryption key from the
/// provider and apply it to the current database connection. This operation is performed
/// synchronously on the service’s internal queue to ensure thread safety.
///
/// If an error occurs during key retrieval or application, the service notifies the provider
/// by calling `databaseService(_:didReceive:)`.
///
/// This enables external management of encryption keys, including features such as key rotation,
/// user-scoped encryption, or error handling delegation.
///
/// - 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
do {
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
/// connection. An internal serial queue is created for synchronizing database access. If a
/// `queue` is provided, it is set as the target of the internal queue, allowing you to control
/// scheduling and quality of service.
///
/// - Parameters:
/// - provider: A closure that returns a new `Connection` instance. May throw on failure.
/// - queue: An optional dispatch queue to target for internal serialization. If `nil`,
/// a dedicated serial queue with `.utility` QoS is created.
/// - Throws: Any error thrown by the `provider` during initial connection setup.
public init(
provider: @escaping ConnectionProvider,
queue: DispatchQueue? = nil
) rethrows {
self.provider = provider
self.connection = try provider()
self.queue = .init(for: Self.self, qos: .utility)
self.queue.setSpecific(key: queueKey, value: ())
if let queue = queue {
self.queue.setTarget(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
/// `keyProvider` is set, the method attempts to retrieve and apply an encryption key to the new
/// connection. The new connection replaces the existing one.
///
/// The operation is executed synchronously on the internal dispatch queue via `perform(_:)`
/// to ensure thread safety.
///
/// - Throws: Any error thrown during connection creation or while retrieving or applying the
/// encryption key.
public func reconnect() throws {
try perform { _ in
let connection = try provider()
if let key = try keyProvider?.databaseServiceKey(self) {
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
/// execution on an internal serial dispatch queue. If the call is already on that queue, 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.
public func perform<T>(_ closure: Perform<T>) rethrows -> T {
do {
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
/// is started, and the closure is executed within it. If the closure completes successfully,
/// the transaction is committed. If an error is thrown, the transaction is rolled back.
///
/// If the thrown error is a `SQLiteError` with code `SQLITE_NOTADB`, the service attempts to
/// reconnect and retries the entire transaction block exactly once.
///
/// If the connection is already within a transaction (i.e., not in autocommit mode),
/// the closure is executed directly without starting a new transaction.
///
/// - Parameters:
/// - transaction: The type of transaction to begin (e.g., `deferred`, `immediate`, `exclusive`).
/// - 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,
/// or reconnect logic.
public func perform<T>(
in transaction: TransactionType,
closure: Perform<T>
) rethrows -> T {
if connection.isAutocommit {
try perform { connection in
do {
try connection.beginTransaction(transaction)
let result = try closure(connection)
try connection.commitTransaction()
return result
} catch {
try connection.rollbackTransaction()
guard let error = error as? Connection.Error,
error.code == SQLITE_NOTADB
else { throw error }
try reconnect()
return try perform { connection in
do {
try connection.beginTransaction(transaction)
let result = try closure(connection)
try connection.commitTransaction()
return result
} catch {
try connection.rollbackTransaction()
throw error
}
}
}
}
} else {
try perform(closure)
}
}
}

138
Sources/DataRaft/Classes/MigrationService.swift Normal file
View File

@@ -0,0 +1,138 @@
import Foundation
import DataLiteCore
/// A service responsible for managing and applying database migrations in a versioned manner.
///
/// `MigrationService` manages a collection of migrations identified by versions and script URLs,
/// and applies them sequentially to update the database schema. It ensures that each migration
/// is applied only once, and in the correct version order based on the current database version.
///
/// This service is generic over a `VersionStorage` implementation that handles storing and
/// retrieving the current database version. Migrations must have unique versions and script URLs
/// to prevent duplication.
///
/// ```swift
/// let connection = try Connection(location: .inMemory, options: .readwrite)
/// let storage = UserVersionStorage<BitPackVersion>()
/// let service = MigrationService(storage: storage, connection: connection)
///
/// 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
/// ``VersionRepresentable``, which supports comparison, hashing, and identity checks.
///
/// The storage backend (`VersionStorage`) defines how the version is persisted, such as
/// in a pragma, table, or metadata.
///
/// This allows using semantic versions, integers, or other schemes, and storing them
/// in custom places.
public final class MigrationService<Service: DatabaseServiceProtocol, Storage: VersionStorage> {
/// The version type used by this migration service, derived from the storage type.
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 migrations = Set<Migration<Version>>()
/// The 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 new migration service with the given database service and version storage.
///
/// - Parameters:
/// - service: The database service used to perform migrations.
/// - storage: The version storage implementation used to track the current schema version.
public init(
service: Service,
storage: Storage
) {
self.service = service
self.storage = storage
}
// MARK: - Migration Management
/// Registers a new migration.
///
/// 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.
public func add(_ migration: Migration<Version>) throws {
guard !migrations.contains(where: {
$0.version == migration.version
|| $0.scriptURL == migration.scriptURL
}) else {
throw Error.duplicateMigration(migration)
}
migrations.insert(migration)
}
/// Executes all pending migrations in ascending version order.
///
/// This method retrieves the current schema version from the storage, filters and sorts
/// pending migrations, executes each migration script within a single exclusive transaction,
/// and updates the schema version on success.
///
/// If a migration script is empty or a migration fails, the process aborts and rolls back changes.
///
/// - Throws: ``Error/migrationFailed(_:_:)`` if a migration script fails or if updating the version fails.
public func migrate() throws {
do {
try service.perform(in: .exclusive) { connection in
try storage.prepare(connection)
let version = try storage.getVersion(connection)
let migrations = migrations
.filter { $0.version > version }
.sorted { $0.version < $1.version }
for migration in migrations {
let script = try migration.script
guard !script.isEmpty else {
throw Error.emptyMigrationScript(migration)
}
do {
try connection.execute(sql: script)
} catch {
throw Error.migrationFailed(migration, error)
}
}
if let version = migrations.last?.version {
try storage.setVersion(connection, version)
}
}
} catch let error as Error {
throw error
} catch {
throw Error.migrationFailed(nil, error)
}
}
}

111
Sources/DataRaft/Classes/RowDatabaseService.swift Normal file
View File

@@ -0,0 +1,111 @@
import Foundation
import DataLiteCore
import DataLiteCoder
/// A database service that provides built-in row encoding and decoding.
///
/// `RowDatabaseService` extends `DatabaseService` by adding support for
/// value serialization using `RowEncoder` and deserialization using `RowDecoder`.
///
/// This enables subclasses to perform type-safe operations on models
/// encoded from or decoded into SQLite row representations.
///
/// For example, a concrete service might define model-aware fetch or insert methods:
///
/// ```swift
/// struct User: Codable {
/// let id: Int
/// let name: String
/// }
///
/// final class UserService: RowDatabaseService {
/// func fetchUsers() throws -> [User] {
/// try perform(in: .deferred) { connection in
/// let stmt = try connection.prepare(sql: "SELECT * FROM users")
/// let rows = try stmt.execute()
/// return try decoder.decode([User].self, from: rows)
/// }
/// }
///
/// func insertUser(_ user: User) throws {
/// try perform(in: .deferred) { connection in
/// let row = try encoder.encode(user)
/// let columns = row.columns.joined(separator: ", ")
/// let parameters = row.namedParameters.joined(separator: ", ")
/// let stmt = try connection.prepare(
/// sql: "INSERT INTO users (\(columns)) VALUES (\(parameters))"
/// )
/// try stmt.execute(rows: [row])
/// }
/// }
/// }
/// ```
///
/// `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 {
// MARK: - Properties
/// The encoder used to serialize values into row representations.
public let encoder: RowEncoder
/// The decoder used to deserialize row values into strongly typed models.
public let decoder: RowDecoder
// MARK: - Inits
/// Creates a new `RowDatabaseService`.
///
/// This initializer accepts a closure that supplies the database connection. If no encoder
/// or decoder is provided, default instances are used.
///
/// - Parameters:
/// - provider: A closure that returns a `Connection` instance. May throw an error.
/// - encoder: The encoder used to serialize models into SQLite-compatible rows.
/// Defaults to a new encoder.
/// - decoder: The decoder used to deserialize SQLite rows into typed models.
/// Defaults to a new decoder.
/// - queue: An optional dispatch queue used for serialization. If `nil`, an internal
/// serial queue with `.utility` QoS is created.
/// - Throws: Any error thrown by the connection provider.
public convenience init(
connection provider: @escaping @autoclosure ConnectionProvider,
encoder: RowEncoder = RowEncoder(),
decoder: RowDecoder = RowDecoder(),
queue: DispatchQueue? = nil
) rethrows {
try self.init(
provider: provider,
encoder: encoder,
decoder: decoder,
queue: queue
)
}
/// Designated initializer for `RowDatabaseService`.
///
/// Initializes a new instance with the specified connection provider, encoder, decoder,
/// and an optional dispatch queue for synchronization.
///
/// - Parameters:
/// - provider: A closure that returns a `Connection` instance. May throw an error.
/// - encoder: A custom `RowEncoder` used for encoding model data. Defaults to a new encoder.
/// - decoder: A custom `RowDecoder` used for decoding database rows. Defaults to a new decoder.
/// - queue: An optional dispatch queue for serializing access to the database connection.
/// If `nil`, a default internal serial queue with `.utility` QoS is used.
/// - Throws: Any error thrown by the connection provider.
public init(
provider: @escaping ConnectionProvider,
encoder: RowEncoder = RowEncoder(),
decoder: RowDecoder = RowDecoder(),
queue: DispatchQueue? = nil
) rethrows {
self.encoder = encoder
self.decoder = decoder
try super.init(
provider: provider,
queue: queue
)
}
}

66
Sources/DataRaft/Classes/UserVersionStorage.swift Normal file
View File

@@ -0,0 +1,66 @@
import Foundation
import DataLiteCore
/// A database version storage that uses the `user_version` field.
///
/// This class implements ``VersionStorage`` by storing version information
/// in the SQLite `PRAGMA user_version` field. It provides a lightweight,
/// type-safe way to persist versioning data in a database.
///
/// The generic `Version` type must conform to both ``VersionRepresentable``
/// and `RawRepresentable`, where `RawValue == UInt32`. This allows
/// converting between stored integer values and semantic version types
/// defined by the application.
public final class UserVersionStorage<
Version: VersionRepresentable & RawRepresentable
>: 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.
case invalidStoredVersion(UInt32)
}
// MARK: - Inits
/// Creates a new user version storage instance.
public init() {}
// MARK: - Methods
/// Returns the current version stored in the `user_version` field.
///
/// This method reads the `PRAGMA user_version` value and attempts to
/// decode it into a valid `Version` value. If the stored value is not
/// recognized, it throws an error.
///
/// - Parameter connection: The database connection.
/// - Returns: A decoded version value of type `Version`.
/// - Throws: ``Error/invalidStoredVersion(_:)`` if the stored value
/// cannot be mapped to a valid `Version` instance.
public func getVersion(
_ connection: Connection
) throws -> Version {
let raw = UInt32(bitPattern: connection.userVersion)
guard let version = Version(rawValue: raw) else {
throw Error.invalidStoredVersion(raw)
}
return version
}
/// Stores the given version in the `user_version` field.
///
/// This method updates the `PRAGMA user_version` field
/// with the raw `UInt32` value of the provided `Version`.
///
/// - Parameters:
/// - connection: The database connection.
/// - version: The version to store.
public func setVersion(
_ connection: Connection,
_ version: Version
) throws {
connection.userVersion = .init(
bitPattern: version.rawValue
)
}
}

19
Sources/DataRaft/Extensions/DispatchQueue.swift Normal file
View File

@@ -0,0 +1,19 @@
import Foundation
extension DispatchQueue {
convenience init<T>(
for type: T.Type,
qos: DispatchQoS = .unspecified,
attributes: Attributes = [],
autoreleaseFrequency: AutoreleaseFrequency = .inherit,
target: DispatchQueue? = nil
) {
self.init(
label: String(describing: type),
qos: qos,
attributes: attributes,
autoreleaseFrequency: autoreleaseFrequency,
target: target
)
}
}

53
Sources/DataRaft/Protocols/DatabaseServiceKeyProvider.swift Normal file
View File

@@ -0,0 +1,53 @@
import Foundation
import DataLiteCore
/// A protocol for supplying encryption keys to `DatabaseService` instances.
///
/// `DatabaseServiceKeyProvider` allows database services to delegate the responsibility of
/// retrieving, managing, and applying encryption keys. This enables separation of concerns
/// and allows for advanced strategies such as per-user key derivation, secure hardware-backed
/// storage, or biometric access control.
///
/// When assigned to a `DatabaseService`, the provider is queried automatically whenever a
/// connection is created or re-established (e.g., during service initialization or reconnect).
///
/// You can also implement error handling or diagnostics via the optional
/// ``databaseService(_:didReceive:)`` method.
///
/// - Tip: You may throw from ``databaseServiceKey(_:)`` to indicate that the key is temporarily
/// unavailable or access is denied.
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
/// to retrieve the encryption key that should be applied to the new connection.
///
/// Implementations may return a static key, derive it from metadata, or load it from
/// 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.
/// - Throws: Any error indicating that the key cannot be retrieved.
func databaseServiceKey(_ service: DatabaseService) throws -> Connection.Key
/// Notifies the provider that the database service encountered an error while applying a key.
///
/// This method is called when the service fails to retrieve or apply the encryption key.
/// You can use it to report diagnostics, attempt recovery, or update internal state.
///
/// The default implementation is a no-op.
///
/// - Parameters:
/// - service: The database service reporting the error.
/// - error: The error encountered during key retrieval or application.
func databaseService(_ service: DatabaseService, didReceive error: Error)
}
public extension DatabaseServiceKeyProvider {
/// Default no-op implementation of error handling callback.
///
/// 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) {}
}

55
Sources/DataRaft/Protocols/DatabaseServiceProtocol.swift Normal file
View File

@@ -0,0 +1,55 @@
import Foundation
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
/// wrapped in transactions. These closures are guaranteed to execute in a thread-safe and
/// serialized manner. Implementations may also support reconnecting and managing encryption keys.
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
/// that receives a live `Connection` and either returns a result or throws an error.
/// It is commonly used to express atomic units of work in ``perform(_:)`` or
/// ``perform(in:closure:)`` calls.
///
/// - Parameter T: The result type returned by the closure.
/// - Returns: A value of type `T` produced by the closure.
/// - Throws: Any error that occurs during execution of the database 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
/// connection, if available.
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.
///
/// - Throws: Any error that occurs during connection creation or key application.
func reconnect() throws
/// Executes the given closure with a live connection.
///
/// - Parameter closure: The operation to execute.
/// - Returns: The result produced by the closure.
/// - Throws: Any error thrown during execution.
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.
///
/// - Parameters:
/// - transaction: The transaction type to begin.
/// - closure: The operation to execute within the transaction.
/// - Returns: The result produced by the closure.
/// - Throws: Any error thrown by the closure or transaction.
func perform<T>(
in transaction: TransactionType,
closure: Perform<T>
) rethrows -> T
}

17
Sources/DataRaft/Protocols/RowDatabaseServiceProtocol.swift Normal file
View File

@@ -0,0 +1,17 @@
import Foundation
import DataLiteCoder
/// A protocol for database services that support row encoding and decoding.
///
/// Conforming types provide `RowEncoder` and `RowDecoder` instances for serializing
/// and deserializing model types to and from SQLite row representations.
///
/// This enables strongly typed, reusable, and safe access to database records
/// using Swift's `Codable` system.
public protocol RowDatabaseServiceProtocol: DatabaseServiceProtocol {
/// The encoder used to serialize values into database rows.
var encoder: RowEncoder { get }
/// The decoder used to deserialize database rows into typed models.
var decoder: RowDecoder { get }
}

33
Sources/DataRaft/Protocols/VersionRepresentable.swift Normal file
View File

@@ -0,0 +1,33 @@
import Foundation
/// A constraint that defines the requirements for a type used as a database schema version.
///
/// This type alias specifies the minimal set of capabilities a version type must have
/// to participate in schema migrations. Conforming types must be:
///
/// - `Equatable`: to check whether two versions are equal
/// - `Comparable`: to compare versions and determine ordering
/// - `Hashable`: to use versions as dictionary keys or in sets
/// - `Sendable`: to ensure safe use in concurrent contexts
///
/// Use this alias as a base constraint when defining custom version types
/// for use with ``VersionStorage``.
///
/// ```swift
/// struct SemanticVersion: VersionRepresentable {
/// let major: Int
/// let minor: Int
/// let patch: Int
///
/// static func < (lhs: Self, rhs: Self) -> Bool {
/// if lhs.major != rhs.major {
/// return lhs.major < rhs.major
/// }
/// if lhs.minor != rhs.minor {
/// return lhs.minor < rhs.minor
/// }
/// return lhs.patch < rhs.patch
/// }
/// }
/// ```
public typealias VersionRepresentable = Equatable & Comparable & Hashable & Sendable

140
Sources/DataRaft/Protocols/VersionStorage.swift Normal file
View File

@@ -0,0 +1,140 @@
import Foundation
import DataLiteCore
/// A protocol that defines how the database version is stored and retrieved.
///
/// This protocol decouples the concept of version representation from
/// the way the version is stored. It enables flexible implementations
/// that can store version values in different forms and places.
///
/// The associated `Version` type determines how the version is represented
/// (e.g. as an integer, a semantic string, or a structured object), while the
/// conforming type defines how that version is persisted.
///
/// Use this protocol to implement custom strategies for version tracking:
/// - Store an integer version in SQLite's `user_version` field.
/// - Store a string in a dedicated metadata table.
/// - Store structured data in a JSON column.
///
/// To define your own versioning mechanism, implement `VersionStorage`
/// and choose a `Version` type that conforms to ``VersionRepresentable``.
///
/// You can implement this protocol to define a custom way of storing the version
/// of a database schema. For example, the version could be a string stored in a metadata table.
///
/// Below is an example of a simple implementation that stores the version string
/// in a table named `schema_version`.
///
/// ```swift
/// final class StringVersionStorage: VersionStorage {
/// typealias Version = String
///
/// func prepare(_ connection: Connection) throws {
/// let script: SQLScript = """
/// CREATE TABLE IF NOT EXISTS schema_version (
/// version TEXT NOT NULL
/// );
///
/// INSERT INTO schema_version (version)
/// SELECT '0.0.0'
/// WHERE NOT EXISTS (SELECT 1 FROM schema_version);
/// """
/// try connection.execute(sql: script)
/// }
///
/// func getVersion(_ connection: Connection) throws -> Version {
/// let query = "SELECT version FROM schema_version LIMIT 1"
/// let stmt = try connection.prepare(sql: query)
/// guard try stmt.step(), let value: Version = stmt.columnValue(at: 0) else {
/// throw DatabaseError.message("Missing version in schema_version table.")
/// }
/// return value
/// }
///
/// func setVersion(_ connection: Connection, _ version: Version) throws {
/// let query = "UPDATE schema_version SET version = ?"
/// let stmt = try connection.prepare(sql: query)
/// try stmt.bind(version, at: 0)
/// try stmt.step()
/// }
/// }
/// ```
///
/// This implementation works as follows:
///
/// - `prepare(_:)` creates the `schema_version` table if it does not exist, and ensures that it
/// contains exactly one row with an initial version value (`"0.0.0"`).
///
/// - `getVersion(_:)` reads the current version string from the single row in the table.
/// If the row is missing, it throws an error.
///
/// - `setVersion(_:_:)` updates the version string in that row. A `WHERE` clause is not necessary
/// because the table always contains exactly one row.
///
/// ## Topics
///
/// ### Associated Types
///
/// - ``Version``
///
/// ### Instance Methods
///
/// - ``prepare(_:)``
/// - ``getVersion(_:)``
/// - ``setVersion(_:_:)``
public protocol VersionStorage {
/// A type representing the database schema version.
associatedtype Version: VersionRepresentable
/// Prepares the storage mechanism for tracking the schema version.
///
/// This method is called before any version operations. Use it to create required tables
/// or metadata structures needed for version management.
///
/// - Important: This method is executed within an active migration transaction.
/// Do not issue `BEGIN` or `COMMIT` manually. If this method throws an error,
/// the entire migration process will be aborted and rolled back.
///
/// - Parameter connection: The database connection used for schema preparation.
/// - Throws: An error if preparation fails.
func prepare(_ connection: Connection) throws
/// Returns the current schema version stored in the database.
///
/// This method must return a valid version previously stored by the migration system.
///
/// - Important: This method is executed within an active migration transaction.
/// Do not issue `BEGIN` or `COMMIT` manually. If this method throws an error,
/// the entire migration process will be aborted and rolled back.
///
/// - Parameter connection: The database connection used to fetch the version.
/// - Returns: The version currently stored in the database.
/// - Throws: An error if reading fails or the version is missing.
func getVersion(_ connection: Connection) throws -> Version
/// Stores the given version as the current schema version.
///
/// This method is called at the end of the migration process to persist
/// the final schema version after all migration steps have completed successfully.
///
/// - Important: This method is executed within an active migration transaction.
/// Do not issue `BEGIN` or `COMMIT` manually. If this method throws an error,
/// the entire migration process will be aborted and rolled back.
///
/// - Parameters:
/// - connection: The database connection used to write the version.
/// - version: The version to store.
/// - Throws: An error if writing fails.
func setVersion(_ connection: Connection, _ version: Version) throws
}
public extension VersionStorage {
/// A default implementation that performs no preparation.
///
/// Override this method if your storage implementation requires any setup,
/// such as creating a version table or inserting an initial value.
///
/// If you override this method and it throws an error, the migration process
/// will be aborted and rolled back.
func prepare(_ connection: Connection) throws {}
}

158
Sources/DataRaft/Structures/BitPackVersion.swift Normal file
View File

@@ -0,0 +1,158 @@
import Foundation
/// A semantic version packed into a 32-bit unsigned integer.
///
/// This type stores a `major.minor.patch` version using bit fields inside a single `UInt32`:
///
/// - 12 bits for `major` in the 0...4095 range
/// - 12 bits for `minor`in the 0...4095 range
/// - 8 bits for `patch` in the 0...255 range
///
/// ## Topics
///
/// ### Errors
///
/// - ``Error``
/// - ``ParseError``
///
/// ### Creating a Version
///
/// - ``init(rawValue:)``
/// - ``init(major:minor:patch:)``
/// - ``init(version:)``
/// - ``init(stringLiteral:)``
///
/// ### Instance Properties
///
/// - ``rawValue``
/// - ``major``
/// - ``minor``
/// - ``patch``
/// - ``description``
public struct BitPackVersion: VersionRepresentable, RawRepresentable, CustomStringConvertible {
/// An error related to invalid version components.
public enum Error: Swift.Error {
/// An error for a major component that exceeds the allowed range.
case majorOverflow(UInt32)
/// An error for a minor component that exceeds the allowed range.
case minorOverflow(UInt32)
/// An error for a patch component that exceeds the allowed range.
case patchOverflow(UInt32)
/// A message describing the reason for the error.
public var localizedDescription: String {
switch self {
case .majorOverflow(let value):
"Major version overflow: \(value). Allowed range: 0...4095."
case .minorOverflow(let value):
"Minor version overflow: \(value). Allowed range: 0...4095."
case .patchOverflow(let value):
"Patch version overflow: \(value). Allowed range: 0...255."
}
}
}
// MARK: - Properties
/// The packed 32-bit value that encodes the version.
public let rawValue: UInt32
/// The major component of the version.
public var major: UInt32 { (rawValue >> 20) & 0xFFF }
/// The minor component of the version.
public var minor: UInt32 { (rawValue >> 8) & 0xFFF }
/// The patch component of the version.
public var patch: UInt32 { rawValue & 0xFF }
/// A string representation in the form `"major.minor.patch"`.
public var description: String {
"\(major).\(minor).\(patch)"
}
// MARK: - Inits
/// Creates a version from a packed 32-bit unsigned integer.
///
/// - Parameter rawValue: A bit-packed version value.
public init(rawValue: UInt32) {
self.rawValue = rawValue
}
/// Creates a version from individual components.
///
/// - Parameters:
/// - major: The major component in the 0...4095 range.
/// - minor: The minor component in the 0...4095 range.
/// - patch: The patch component in the 0...255 range. Defaults to `0`.
///
/// - Throws: ``Error/majorOverflow(_:)`` if `major` is out of range.
/// - Throws: ``Error/minorOverflow(_:)`` if `minor` is out of range.
/// - Throws: ``Error/patchOverflow(_:)`` if `patch` is out of range.
public init(major: UInt32, minor: UInt32, patch: UInt32 = 0) throws {
guard major < (1 << 12) else { throw Error.majorOverflow(major) }
guard minor < (1 << 12) else { throw Error.minorOverflow(minor) }
guard patch < (1 << 8) else { throw Error.patchOverflow(patch) }
self.init(rawValue: (major << 20) | (minor << 8) | patch)
}
// MARK: - Comparable
/// Compares two versions by their packed 32-bit values.
public static func < (lhs: Self, rhs: Self) -> Bool {
lhs.rawValue < rhs.rawValue
}
}
// MARK: - ExpressibleByStringLiteral
@available(iOS 16.0, *)
@available(macOS 13.0, *)
extension BitPackVersion: ExpressibleByStringLiteral {
/// An error related to parsing a version string.
public enum ParseError: Swift.Error {
/// A string that doesn't match the expected version format.
case invalidFormat(String)
/// A message describing the format issue.
public var localizedDescription: String {
switch self {
case .invalidFormat(let str):
"Invalid version format: \(str). Expected something like '1.2' or '1.2.3'."
}
}
}
/// Creates a version by parsing a string like `"1.2"` or `"1.2.3"`.
///
/// - Parameter version: A version string in the form `x.y` or `x.y.z`.
///
/// - Throws: ``ParseError/invalidFormat(_:)`` if the string format is invalid.
/// - Throws: `Error` if any component is out of range.
public init(version: String) throws {
let regex = /^(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\.(0|[1-9]\d*))?$/
guard version.wholeMatch(of: regex) != nil else {
throw ParseError.invalidFormat(version)
}
let parts = version.split(separator: ".")
.compactMap { UInt32($0) }
try self.init(
major: parts[0],
minor: parts[1],
patch: parts.count == 3 ? parts[2] : 0
)
}
/// Creates a version from a string literal like `"1.2"` or `"1.2.3"`.
///
/// - Warning: Crashes if the string format is invalid.
/// Use ``init(version:)`` for safe parsing.
public init(stringLiteral value: String) {
try! self.init(version: value)
}
}

75
Sources/DataRaft/Structures/Migration.swift Normal file
View File

@@ -0,0 +1,75 @@
import Foundation
import DataLiteCore
/// Represents a database migration step associated with a specific version.
///
/// Each `Migration` contains a reference to a migration script file (usually a `.sql` file) and the
/// version to which this script corresponds. The script is expected to be bundled with the application.
///
/// You can initialize a migration directly with a URL to the script, or load it from a resource
/// embedded in a bundle.
public struct Migration<Version: VersionRepresentable>: Hashable, Sendable {
// MARK: - Properties
/// The version associated with this migration step.
public let version: Version
/// The URL pointing to the migration script (e.g., an SQL file).
public let scriptURL: URL
/// The SQL script associated with this migration.
///
/// This computed property reads the contents of the file at `scriptURL` and returns it as a
/// `SQLScript` instance. Use this to access and execute the migration's SQL commands.
///
/// - Throws: An error if the script file cannot be read or is invalid.
public var script: SQLScript {
get throws {
try SQLScript(contentsOf: scriptURL)
}
}
// MARK: - Inits
/// Creates a migration with a specified version and script URL.
///
/// - Parameters:
/// - version: The version this migration corresponds to.
/// - scriptURL: The file URL to the migration script.
public init(version: Version, scriptURL: URL) {
self.version = version
self.scriptURL = scriptURL
}
/// Creates a migration by locating a script resource in the specified bundle.
///
/// This initializer attempts to locate a script file in the provided bundle using the specified
/// resource `name` and optional `extension`. The `name` parameter may include or omit the file extension.
///
/// - If `name` includes an extension (e.g., `"001_init.sql"`), pass `extension` as `nil` or an empty string.
/// - If `name` omits the extension (e.g., `"001_init"`), specify the extension separately
/// (e.g., `"sql"`), or leave it `nil` if the file has no extension.
///
/// - Important: Passing a name that already includes the extension while also specifying a non-`nil`
/// `extension` may result in failure to locate the file.
///
/// - Parameters:
/// - version: The version this migration corresponds to.
/// - name: The resource name of the script file. May include or omit the file extension.
/// - extension: The file extension, if separated from the name. Defaults to `nil`.
/// - bundle: The bundle in which to search for the resource. Defaults to `.main`.
///
/// - Returns: A `Migration` if the resource file is found; otherwise, `nil`.
public init?(
version: Version,
byResource name: String,
extension: String? = nil,
in bundle: Bundle = .main
) {
guard let url = bundle.url(
forResource: name,
withExtension: `extension`
) else { return nil }
self.init(version: version, scriptURL: url)
}
}