Skip to main content
GRDB provides detailed migration guides to help you upgrade between major versions. Each guide includes breaking changes, new features, and recommendations for improving your application.

​
Latest Migration Guide

Migrating from GRDB 6 to GRDB 7

The complete guide for upgrading to GRDB 7 with Swift 6 support

​
GRDB 7 Migration Highlights

GRDB 7 brings full support for Swift 6 and requires Xcode 16.3+ and Swift 6.1+.

​
New Requirements

  • Swift Compiler: 6.1+ (was Swift 5.7+)
  • Xcode: 16.3+ (was Xcode 14.0+)
  • iOS: 13.0+ (was 11.0+)
  • macOS: 10.15+ (was 10.13+)
  • tvOS: 13.0+ (was 11.0+)
  • watchOS: 7.0+ (was 4.0+)
  • SQLite: 3.20.0+ (was 3.19.3+)

​
Major Changes

In GRDB 6, coding strategies were static properties. In GRDB 7, they are methods that accept a column argument:
// GRDB 6
struct Player {
    static let databaseDataDecodingStrategy = ...
    static let databaseDateDecodingStrategy = ...
}

// GRDB 7
struct Player {
    static func databaseDataDecodingStrategy(for column: String) -> DatabaseDataDecodingStrategy { ... }
    static func databaseDateDecodingStrategy(for column: String) -> DatabaseDateDecodingStrategy { ... }
}
In GRDB 6, async database accesses completed even if the wrapper Task was cancelled.In GRDB 7, async accesses respect Task cancellation. If a Task is cancelled:
  • Reads and writes throw CancellationError
  • Pending transactions are rolled back
  • The database is not modified
To ignore cancellation:
let task = Task {
    try await writer.write { ... }
}
try await task.value
By default, ValueObservation now fosters the main actor:
@MainActor func startObservation() {
    let observation = ValueObservation.tracking { ... }
    
    let cancellable = observation.start(in: dbQueue) { error in
        // MainActor-isolated
    } onChange: { value in
        // MainActor-isolated
        print("Fresh value", value)
    }
}
Opt-out with a specific scheduler:
observation.start(in: dbQueue, scheduling: .async(onQueue: .main))
Subclassing the Record class is discouraged in GRDB 7. Refactor to Swift structs:
// GRDB 6
class Player: Record {
    var id: UUID
    var name: String
    var score: Int
}

// GRDB 7
struct Player: Codable {
    var id: UUID
    var name: String
    var score: Int
}

extension Player: FetchableRecord, PersistableRecord { }
Additional imports may be needed:
// SPM package
import SQLite3
let version = sqlite3_libversion_number()

// SQLCipher
import SQLCipher
let version = sqlite3_libversion_number()

​
All Migration Guides

GRDB 7 Migration Guide

Swift 6 support, new requirements, and breaking changes

GRDB 6 Migration Guide

UPSERT support, RETURNING clause, and persistence callbacks

GRDB 5 Migration Guide

Major refactoring and Swift 5.2+ requirement

Changelog

Complete version history with all changes

​
Migration Best Practices

1

Update to Latest Minor Version

Before upgrading to a new major version, update to the latest minor version of your current major version and fix all deprecation warnings.
2

Review the Migration Guide

Read the complete migration guide for your target version. Pay special attention to breaking changes that affect your codebase.
3

Update Dependencies

Update companion libraries like GRDBQuery and GRDBSnapshotTesting to compatible versions.
4

Test Thoroughly

Run your test suite and verify all database operations work as expected after the migration.

​
Companion Library Versions

When upgrading GRDB, ensure your companion libraries are compatible:
  • GRDBQuery: Check releases for SwiftUI integration
  • GRDBSnapshotTesting: Check releases for snapshot testing
Each migration guide includes a “Preparing the Migration” section with steps to minimize disruption during the upgrade.

Build docs developers (and LLMs) love

Get started for freeTalk to us