Merge branch 'development'

This commit is contained in:
Gwendal Roué committed 2025-10-02 08:11:07 +02:00
commit 18497b68fd
7 files changed
+422 -35

No files matched your search

+7
View File
@@ -7,6 +7,7 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
#### 7.x Releases
- `7.8.x` Releases - [7.8.0](#780)
- `7.7.x` Releases - [7.7.0](#770) - [7.7.1](#771)
- `7.6.x` Releases - [7.6.0](#760) - [7.6.1](#761)
- `7.5.x` Releases - [7.5.0](#750)
@@ -139,6 +140,12 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
---
## 7.8.0
Released October 2, 2025
- **New**: Merged Migrations by [@groue](https://github.com/groue) in [#1818](https://github.com/groue/GRDB.swift/pull/1818)
## 7.7.1
Released September 29, 2025
+1 -1
View File
@@ -1,6 +1,6 @@
Pod::Spec.new do |s|
s.name = 'GRDB.swift'
s.version = '7.7.1'
s.version = '7.8.0'
s.license = { :type => 'MIT', :file => 'LICENSE' }
s.summary = 'A toolkit for SQLite databases, with a focus on application development.'
+149 -14
View File
@@ -18,6 +18,7 @@ import Foundation
/// ### Registering Migrations
///
/// - ``registerMigration(_:foreignKeyChecks:migrate:)``
/// - ``registerMigration(_:foreignKeyChecks:merging:migrate:)``
/// - ``ForeignKeyChecks``
///
/// ### Configuring a DatabaseMigrator
@@ -161,9 +162,8 @@ public struct DatabaseMigrator: Sendable {
/// Registers a migration.
///
/// The registered migration is appended to the list of migrations to run:
/// it will execute after previously registered migrations, and before
/// migrations that are registered later.
/// The registered migration is appended to the list of migrations. It
/// will execute after previously registered migrations.
///
/// For example:
///
@@ -214,6 +214,107 @@ public struct DatabaseMigrator: Sendable {
_ identifier: String,
foreignKeyChecks: ForeignKeyChecks = .deferred,
migrate: @escaping @Sendable (Database) throws -> Void)
{
registerMigration(identifier, foreignKeyChecks: foreignKeyChecks, merging: []) { db, ids in
precondition(ids.isEmpty)
try migrate(db)
}
}
/// Registers a merged migration.
///
/// Like migrations registered with ``registerMigration(_:foreignKeyChecks:migrate:)``,
/// the merged migration is appended to the list of migrations. It
/// will execute after previously registered migrations.
///
/// A merged migration merges and replaces a set of migrations defined
/// in a previous version of the application. For example, to merge the
/// migrations "v1", "v2" and "v3", redefine the "v3" migration so that
/// it merges "v1" and "v2", as in the example below.
///
/// The second argument of the `migrate` closure is the subset of merged
/// migrations that have already been applied when the merged
/// migration runs.
///
/// ```swift
/// // Old code
/// migrator.registerMigration("v1") { db in
/// // Apply schema version 1
/// }
/// migrator.registerMigration("v2") { db in
/// // Apply schema version 2
/// }
/// migrator.registerMigration("v3") { db in
/// // Apply schema version 3
/// }
///
/// // New code:
/// // - Migrations v1 and v2 are deleted.
/// // - Migration v3 is redefined and merges v1 and v2:
/// migrator.registerMigration("v3", merging: ["v1", "v2"]) { db, appliedIDs in
/// if !appliedIDs.contains("v1") {
/// // Apply schema version 1
/// }
/// if !appliedIDs.contains("v2") {
/// // Apply schema version 2
/// }
/// // Apply schema version 3
/// }
/// ```
///
/// In the above sample code, the merged migration is named like the
/// last one of the merged set. You can also give it a brand new name,
/// as in the alternative below. Notice the different logic in the
/// migration code.
///
/// **In all cases avoid naming the merged migration like the first
/// elements in the merged set** (`v1` or `v2` in our example).
///
/// ```swift
/// // Alternative new code:
/// // - Migrations v1, v2 and v3 are deleted.
/// // - The new migration v3-new merges v1, v2 and v3:
/// migrator.registerMigration("v3-new", merging: ["v1", "v2", "v3"]) { db, appliedIDs in
/// if !appliedIDs.contains("v1") {
/// // Apply schema version 1
/// }
/// if !appliedIDs.contains("v2") {
/// // Apply schema version 2
/// }
/// if !appliedIDs.contains("v3") {
/// // Apply schema version 3
/// }
/// }
/// ```
///
/// - parameters:
/// - identifier: The migration identifier.
/// - mergedIdentifiers: A set of previous migration identifiers
/// that are merged in this migration.
/// - foreignKeyChecks: This parameter is ignored if the database
/// ``Configuration`` has disabled foreign keys.
///
/// The default `.deferred` checks have the migration run with
/// disabled foreign keys, until foreign keys are checked right before
/// changes are committed on disk. These deferred checks are not
/// executed if the migrator is the result of
/// ``disablingDeferredForeignKeyChecks()``.
///
/// The `.immediate` checks have the migration run with foreign
/// keys enabled. Make sure you only use `.immediate` if the migration
/// does not perform schema changes described in
/// <https://www.sqlite.org/lang_altertable.html#making_other_kinds_of_table_schema_changes>
/// - migrate: A closure that performs database operations. The
/// first argument is a database connection. The second argument
/// is the set of previous migrations that has been applied when
/// the merged migration runs.
/// - precondition: No migration with the same identifier as already
/// been registered.
public mutating func registerMigration(
_ identifier: String,
foreignKeyChecks: ForeignKeyChecks = .deferred,
merging mergedIdentifiers: Set<String> = [],
migrate: @escaping @Sendable (_ db: Database, _ appliedIdentifiers: Set<String>) throws -> Void)
{
let migrationChecks: Migration.ForeignKeyChecks
switch foreignKeyChecks {
@@ -226,7 +327,11 @@ public struct DatabaseMigrator: Sendable {
case .immediate:
migrationChecks = .immediate
}
registerMigration(Migration(identifier: identifier, foreignKeyChecks: migrationChecks, migrate: migrate))
registerMigration(Migration(
identifier: identifier,
mergedIdentifiers: mergedIdentifiers,
foreignKeyChecks: migrationChecks,
migrate: migrate))
}
// MARK: - Applying Migrations
@@ -450,6 +555,16 @@ public struct DatabaseMigrator: Sendable {
// MARK: - Non public
private struct Execution {
enum Mode {
case run(mergedIdentifiers: Set<String>)
case deleteMergedIdentifiers
}
var migration: Migration
var mode: Mode
}
private mutating func registerMigration(_ migration: Migration) {
GRDBPrecondition(
!_migrations.map({ $0.identifier }).contains(migration.identifier),
@@ -457,8 +572,8 @@ public struct DatabaseMigrator: Sendable {
_migrations.append(migration)
}
/// Returns unapplied migration identifier,
private func unappliedMigrations(upTo targetIdentifier: String, appliedIdentifiers: [String]) -> [Migration] {
/// Returns unapplied migration executions
private func unappliedExecutions(upTo targetIdentifier: String, appliedIdentifiers: Set<String>) -> [Execution] {
var expectedMigrations: [Migration] = []
for migration in _migrations {
expectedMigrations.append(migration)
@@ -472,32 +587,52 @@ public struct DatabaseMigrator: Sendable {
expectedMigrations.last?.identifier == targetIdentifier,
"undefined migration: \(String(reflecting: targetIdentifier))")
return expectedMigrations.filter { !appliedIdentifiers.contains($0.identifier) }
return expectedMigrations.compactMap { migration in
if appliedIdentifiers.contains(migration.identifier) {
if migration.mergedIdentifiers.isDisjoint(with: appliedIdentifiers) {
// Nothing to do
return nil
} else {
// Migration is applied, but we have some merged identifiers to delete
return Execution(migration: migration, mode: .deleteMergedIdentifiers)
}
} else {
// Migration is not applied yet.
let appliedMergedIdentifiers = migration.mergedIdentifiers.intersection(appliedIdentifiers)
return Execution(migration: migration, mode: .run(mergedIdentifiers: appliedMergedIdentifiers))
}
}
}
private func runMigrations(_ db: Database, upTo targetIdentifier: String) throws {
try db.execute(sql: "CREATE TABLE IF NOT EXISTS grdb_migrations (identifier TEXT NOT NULL PRIMARY KEY)")
let appliedIdentifiers = try self.appliedMigrations(db)
// Subsequent migration must not be applied
let appliedMigrations = try self.appliedMigrations(db) // Only known ids
if let targetIndex = _migrations.firstIndex(where: { $0.identifier == targetIdentifier }),
let lastAppliedIdentifier = appliedIdentifiers.last,
let lastAppliedIndex = _migrations.firstIndex(where: { $0.identifier == lastAppliedIdentifier }),
let lastAppliedMigration = appliedMigrations.last,
let lastAppliedIndex = _migrations.firstIndex(where: { $0.identifier == lastAppliedMigration }),
targetIndex < lastAppliedIndex
{
fatalError("database is already migrated beyond migration \(String(reflecting: targetIdentifier))")
}
let unappliedMigrations = self.unappliedMigrations(
let appliedIdentifiers = try self.appliedIdentifiers(db) // All ids, even unknown ones
let unappliedExecutions = self.unappliedExecutions(
upTo: targetIdentifier,
appliedIdentifiers: appliedIdentifiers)
if unappliedMigrations.isEmpty {
if unappliedExecutions.isEmpty {
return
}
for migration in unappliedMigrations {
try migration.run(db)
for execution in unappliedExecutions {
switch execution.mode {
case .run(let mergedIdentifiers):
try execution.migration.run(db, mergedIdentifiers: mergedIdentifiers)
case .deleteMergedIdentifiers:
try execution.migration.deleteMergedIdentifiers(db)
}
}
}
+31 -18
View File
@@ -6,22 +6,27 @@ struct Migration: Sendable {
case disabled
}
typealias Migrate = @Sendable (_ db: Database, _ mergedIdentifiers: Set<String>) throws -> Void
let identifier: String
let mergedIdentifiers: Set<String>
var foreignKeyChecks: ForeignKeyChecks
// Private so that the guarantees of `run(_:)` are enforced.
private let migrate: @Sendable (Database) throws -> Void
private let migrate: Migrate
init(
identifier: String,
mergedIdentifiers: Set<String>,
foreignKeyChecks: ForeignKeyChecks,
migrate: @escaping @Sendable (Database) throws -> Void
migrate: @escaping Migrate
) {
self.identifier = identifier
self.mergedIdentifiers = mergedIdentifiers
self.foreignKeyChecks = foreignKeyChecks
self.migrate = migrate
}
func run(_ db: Database) throws {
func run(_ db: Database, mergedIdentifiers: Set<String>) throws {
// Migrations access the raw SQLite schema, without alteration due
// to the schemaSource. The goal is to ensure that migrations are
// immutable, immune from spooky actions at a distance.
@@ -29,33 +34,40 @@ struct Migration: Sendable {
if try Bool.fetchOne(db, sql: "PRAGMA foreign_keys") ?? false {
switch foreignKeyChecks {
case .deferred:
try runWithDeferredForeignKeysChecks(db)
try runWithDeferredForeignKeysChecks(db, mergedIdentifiers: mergedIdentifiers)
case .immediate:
try runWithImmediateForeignKeysChecks(db)
try runWithImmediateForeignKeysChecks(db, mergedIdentifiers: mergedIdentifiers)
case .disabled:
try runWithDisabledForeignKeysChecks(db)
try runWithDisabledForeignKeysChecks(db, mergedIdentifiers: mergedIdentifiers)
}
} else {
try runWithImmediateForeignKeysChecks(db)
try runWithImmediateForeignKeysChecks(db, mergedIdentifiers: mergedIdentifiers)
}
}
}
private func runWithImmediateForeignKeysChecks(_ db: Database) throws {
func deleteMergedIdentifiers(_ db: Database) throws {
if mergedIdentifiers.isEmpty == false {
try db.execute(literal: "DELETE FROM grdb_migrations WHERE identifier IN \(mergedIdentifiers)")
}
}
private func runWithImmediateForeignKeysChecks(_ db: Database, mergedIdentifiers: Set<String>) throws {
try db.inTransaction(.immediate) {
try migrate(db)
try insertAppliedIdentifier(db)
try migrate(db, mergedIdentifiers)
try updateAppliedIdentifier(db)
return .commit
}
}
private func runWithDisabledForeignKeysChecks(_ db: Database) throws {
private func runWithDisabledForeignKeysChecks(_ db: Database, mergedIdentifiers: Set<String>) throws {
try db.execute(sql: "PRAGMA foreign_keys = OFF")
try throwingFirstError(
execute: {
try db.inTransaction(.immediate) {
try migrate(db)
try insertAppliedIdentifier(db)
try migrate(db, mergedIdentifiers)
try updateAppliedIdentifier(db)
return .commit
}
},
@@ -64,7 +76,7 @@ struct Migration: Sendable {
})
}
private func runWithDeferredForeignKeysChecks(_ db: Database) throws {
private func runWithDeferredForeignKeysChecks(_ db: Database, mergedIdentifiers: Set<String>) throws {
// Support for database alterations described at
// https://www.sqlite.org/lang_altertable.html#otheralter
//
@@ -76,8 +88,8 @@ struct Migration: Sendable {
execute: {
// > 2. Start a transaction.
try db.inTransaction(.immediate) {
try migrate(db)
try insertAppliedIdentifier(db)
try migrate(db, mergedIdentifiers)
try updateAppliedIdentifier(db)
// > 10. If foreign key constraints were originally enabled
// > then run PRAGMA foreign_key_check to verify that the
@@ -96,7 +108,8 @@ struct Migration: Sendable {
})
}
private func insertAppliedIdentifier(_ db: Database) throws {
try db.execute(sql: "INSERT INTO grdb_migrations (identifier) VALUES (?)", arguments: [identifier])
private func updateAppliedIdentifier(_ db: Database) throws {
try deleteMergedIdentifiers(db)
try db.execute(literal: "INSERT INTO grdb_migrations (identifier) VALUES (\(identifier))")
}
}
+1 -1
View File
@@ -25,7 +25,7 @@
---
**Latest release**: September 29, 2025 • [version 7.7.1](https://github.com/groue/GRDB.swift/tree/v7.7.0) • [CHANGELOG](CHANGELOG.md) • [Migrating From GRDB 6 to GRDB 7](Documentation/GRDB7MigrationGuide.md)
**Latest release**: October 2, 2025 • [version 7.8.0](https://github.com/groue/GRDB.swift/tree/v7.8.0) • [CHANGELOG](CHANGELOG.md) • [Migrating From GRDB 6 to GRDB 7](Documentation/GRDB7MigrationGuide.md)
**Requirements**: iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 7.0+ &bull; SQLite 3.20.0+ &bull; Swift 6+ / Xcode 16+
+1 -1
View File
@@ -15,7 +15,7 @@
<key>CFBundlePackageType</key>
<string>FMWK</string>
<key>CFBundleShortVersionString</key>
<string>7.7.1</string>
<string>7.8.0</string>
<key>CFBundleSignature</key>
<string>????</string>
<key>CFBundleVersion</key>
+232
View File
@@ -1166,4 +1166,236 @@ class DatabaseMigratorTests : GRDBTestCase {
}
try migrator.migrate(dbQueue)
}
func test_merged_migrations_named_like_the_last() throws {
// Original migrator
var oldMigrator = DatabaseMigrator()
oldMigrator.registerMigration("v1") { db in
try db.execute(sql: "CREATE TABLE t1(a)")
}
oldMigrator.registerMigration("v2") { db in
try db.execute(sql: "CREATE TABLE t2(a)")
}
oldMigrator.registerMigration("v3") { db in
try db.execute(sql: "CREATE TABLE t3(a)")
}
oldMigrator.registerMigration("v4") { db in
try db.execute(sql: "CREATE TABLE t4(a)")
}
oldMigrator.registerMigration("v5") { db in
try db.execute(sql: "CREATE TABLE t5(a)")
}
// New migrator merges v2, v3, and v4 into v4
var newMigrator = DatabaseMigrator()
newMigrator.registerMigration("v1") { db in
try db.execute(sql: "CREATE TABLE t1(a)")
}
newMigrator.registerMigration("v4", merging: ["v2", "v3"]) { db, appliedIDs in
if !appliedIDs.contains("v2") {
try db.execute(sql: "CREATE TABLE t2(a)")
}
if !appliedIDs.contains("v3") {
try db.execute(sql: "CREATE TABLE t3(a)")
}
try db.execute(sql: "CREATE TABLE t4(a)")
}
newMigrator.registerMigration("v5") { db in
try db.execute(sql: "CREATE TABLE t5(a)")
}
do {
let dbQueue = try makeDatabaseQueue()
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v1")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v2")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v3")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v4")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v5")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
}
func test_merged_migrations_with_a_new_name() throws {
// Original migrator
var oldMigrator = DatabaseMigrator()
oldMigrator.registerMigration("v1") { db in
try db.execute(sql: "CREATE TABLE t1(a)")
}
oldMigrator.registerMigration("v2") { db in
try db.execute(sql: "CREATE TABLE t2(a)")
}
oldMigrator.registerMigration("v3") { db in
try db.execute(sql: "CREATE TABLE t3(a)")
}
oldMigrator.registerMigration("v4") { db in
try db.execute(sql: "CREATE TABLE t4(a)")
}
oldMigrator.registerMigration("v5") { db in
try db.execute(sql: "CREATE TABLE t5(a)")
}
// New migrator merges v2, v3, and v4 into v4bis
var newMigrator = DatabaseMigrator()
newMigrator.registerMigration("v1") { db in
try db.execute(sql: "CREATE TABLE t1(a)")
}
newMigrator.registerMigration("v4bis", merging: ["v2", "v3", "v4"]) { db, appliedIDs in
if !appliedIDs.contains("v2") {
try db.execute(sql: "CREATE TABLE t2(a)")
}
if !appliedIDs.contains("v3") {
try db.execute(sql: "CREATE TABLE t3(a)")
}
if !appliedIDs.contains("v4") {
try db.execute(sql: "CREATE TABLE t4(a)")
}
}
newMigrator.registerMigration("v5") { db in
try db.execute(sql: "CREATE TABLE t5(a)")
}
do {
let dbQueue = try makeDatabaseQueue()
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4bis", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v1")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4bis", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v2")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4bis", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v3")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4bis", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v4")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4bis", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
do {
let dbQueue = try makeDatabaseQueue()
try oldMigrator.migrate(dbQueue, upTo: "v5")
try newMigrator.migrate(dbQueue)
try dbQueue.read { db in
try XCTAssertEqual(newMigrator.appliedIdentifiers(db), ["v1", "v4bis", "v5"])
try XCTAssertTrue(String
.fetchSet(db, sql: "SELECT name FROM sqlite_master")
.isSuperset(of: ["t1", "t2", "t3", "t4", "t5"]))
}
}
}
}