Release Notes

June 1, 2026 · View on GitHub

All notable changes to this project will be documented in this file.

GRDB adheres to Semantic Versioning, with one exception: APIs flagged :fire: EXPERIMENTAL. Those are unstable, and may break between any two minor releases of the library.

7.x Releases

6.x Releases

5.x Releases

4.x Releases

3.x Releases

2.x Releases

1.x Releases

0.x Releases

7.11.0

Released June 1, 2026

  • New: Add option to disable database change filtering in TransactionObserver by @simolus3 in #1864
  • Fixed: Fix upsert for WITHOUT ROWID tables by @groue in #1858

7.10.0

Released February 15, 2026

7.9.0

Released December 13, 2025

  • Breaking Change: Simplify the compiler checks for the availability of SQLite snapshots by @groue in #1826

    This change aims at easing Linux and Android compatibility.

    The library requirements are raised to Swift 6.1+, Xcode 16.3+.

  • Breaking Change: Accept multiple SQLCipher libraries by @groue in #1819

    This change aims at easing building GRDB against various SQLCipher flavors.

    The compiler flag that enables new GRDB APIs for SQLCipher is now SQLITE_HAS_CODEC.

  • Fixed: Fix cancellation of async tasks that use the FTS5 full-text engine by @groue in #1839

    This workarounds an SQLite bug that would trigger a GRDB crash, and improves the robustness of the library regarding database accesses cancellation and database interruption.

  • New: Improve the ergonomics of DatabaseMigrator.registerMigration(_:foreignKeyChecks:merging:migrate), introduced in #1818, by accepting that the name of the merged migration is included in the set of merged migrations:

    // Used to fail, now OK:
migrator.registerMigration("v3", merging: ["v1", "v2", "v3"]) { ... }
//                         ~~~~                        ~~~~

// The above code is equivalent to:
migrator.registerMigration("v3", merging: ["v1", "v2"]) { ... }

7.8.0

Released October 2, 2025

7.7.1

Released September 29, 2025

  • Fixed: Fix the save() method for record types with attached triggers by @groue in #1822

7.7.0

Released September 23, 2025

  • New: Update GRDB7MigrationGuide.md reference by @emmanuel-ferdman in #1807
  • New: Persistable Database Views by @groue in #1810
  • New: Support for Xcode 26 by @groue in #1813
  • Fixed: Fix another race condition regarding Task cancellation, completing #1797

7.6.1

Released July 23, 2025

  • Fixed: Fix race condition regarding Task cancellation by @groue in #1797

7.6.0

Released July 20, 2025

  • New: All closures that accept DatabaseComponents can throw by @groue in #1768
  • New: Add Sendable conformance to DatabasePreUpdateEvent.Kind, matching DatabaseEvent.Kind by @Jason-Abbott in #1773
  • New: Add custom build instruction for hardened runtime by @Jason-Abbott in #1776
  • New: Access task locals from asynchronous database accesses by @groue in #1794
  • New: Throwing row accessors by @groue in #1796

7.5.0

Released May 11, 2025

  • New: Make it possible to create a raw FTS5Pattern without any database connection by @groue in #1764
  • New: Build request with closures by @groue in #1759

7.4.1

Released March 28, 2025

  • Removed a compiler warning

7.4.0

Released March 22, 2025

  • New: Add the MIN and MAX multi-argument SQL functions to the query interface by @groue in #1745
  • Fixed: Transaction observers are not impacted by Task Cancellation by @groue in #1747. This fixes unexpected ValueObservation failures in applications that perform asynchronous writes.

7.3.0

Released February 23, 2025

  • New: Support for temporary virtual tables by @groue in #1731
  • Fixed a compiler error in Xcode 16.3 beta (#1729, #1730)

7.2.0

Released February 12, 2025

7.1.0

Released February 5, 2025

  • New: Expose sqlite3_libversion_number as Database.sqliteLibVersionNumber by @groue in #1713
  • Fixed: DatabaseQueue restores its read/write abilities when an async read-only database access is cancelled by @groue in #1716
  • New: Allow RxGRDB to compile without warning by @groue in #1717

7.0.0

Released January 26, 2025

  • New: Support for JSONB expressions by @groue in #1699
  • Breaking Change: Fix inflections of Bias, Focus, Gas, and Lens by @groue in #1703

7.0.0-beta.7

Released January 19, 2025

  • New: Select all columns from a table, but a few ones by @groue in #1700
  • Fixed: Fix typo in Readme.md by @kevinlg in #1697
  • New: Bump custom SQLite to 3.47.2 by @groue in #1696
  • Fixed: Update LICENSE, fix copyright license year by @JasonnnW3000 in #1695
  • Fixed: Core: import ucrt on Windows for strcmp by @compnerd in #1662
  • Fixed: Foundation: elide extensions on Windows to match Linux by @compnerd in #1661
  • Fixed: Docs: fixes typos "FST"->"FTS" by @nylki in #1660

7.0.0-beta.6

Released October 13, 2024

  • New: Bump custom SQLite builds to 3.46.1 by @groue in #1654

7.0.0-beta.5

Released October 13, 2024

  • Fixed: Fix DatabaseMigrator.hasSchemaChanges failing for readonly connections by @Jnosh in #1653
  • Documentation Update: Enhance the database schema documentation by @groue in #1652

7.0.0-beta.4

Released October 12, 2024

  • New: Allow applications to handle DatabaseMigrator schema changes by @groue in #1651

7.0.0-beta.3

Released October 6, 2024

  • Fix: use #if directives to conditionally @preconcurrency import the Dispatch module to enable building the package on linux by @tayloraswift in #1644
  • New: Add coalesce free function and Row method by @philmitchell in #1645
  • Documentation Update: Add DatabaseValueConvertible tip for JSON columns by @bok- in #1649

7.0.0-beta.2

Released September 29, 2024

7.0.0-beta

Released September 29, 2024

GRDB 7 brings full support for Swift 6.

Migrating From GRDB 6 to GRDB 7 describes in detail how to bump the GRDB version in your application.

The new Swift Concurrency and GRDB guide explains how to best integrate GRDB and Swift Concurrency.

The demo app was rewritten from scratch in a brand new Xcode 16 project.

  • Breaking Change: Bump requirements by @groue in #1598 and #1634
  • Breaking Change: Enhance ergonomics of record methods that insert/save/upsert and fetch by @groue in #1599
  • Breaking Change: Rename the CSQLite module to GRDBSQLite, and stop exporting the C SQLite functions by @groue in #1600
  • Breaking Change: Perform all writes with immediate transactions by default by @groue in #1602
  • Breaking Change: Remove DatabasePool.concurrentRead by @groue in #1603
  • Breaking Change: Coding strategies depend on the column by @groue in #1606
  • Breaking Change: Add missing Sendable conformances by @groue in #1607 and #1639
  • Breaking Change: Async database accesses honor Task cancellation by @groue in #1610
  • Breaking Change: Prefer Collection over Sequence for filter(keys:) and related APIs by @groue in #1617
  • Breaking Change: MainActor ValueObservation scheduling by @groue in #1633
  • Breaking Change: Prefer any DatabaseReader and DatabaseWriter by @groue in #1635
  • New: Sendable database accesses by @groue in #1618
  • New: DatabaseCursor has a primary associated type by @groue in #1605

6.29.3

Released September 7, 2024

  • Fixed: #1613 by @groue: Avoid SQLite misuse when releasing memory on a closed database connection

6.29.2

Released August 24, 2024

6.29.1

Released August 7, 2024

  • New: #1579 by @groue: Modernize the demo apps
  • New: #1584 by @SagarSDagdu: Update README to highlight deployment issue with CocoaPods
  • New: #1589 by @groue: Fix compilation issue with Xcode 16 beta 5 due to a missing import

6.29.0

Released July 20, 2024

6.28.0

Released July 11, 2024

  • New: #1570 by @groue: Support single-value encoding
  • New: Added QueryInterfaceRequest.deleteAndFetchIds(_:) which returns the set of deleted ids.
  • New: Added Set methods union, formUnion, intersection and formIntersection that accept a cursor.
  • New: DatabaseUUIDEncodingStrategy is Sendable.

6.27.0

Released April 21, 2024

  • Fixed: #1533 by @groue: Fix a bug in Decodable support
  • Documentation Update: #1534 The Single-Row Tables guide was updated with guidance about default configuration values.
  • Documentation Update: #1535 The ValueObservation Scheduling documentation chapter explains the default behavior of ValueObservation fetches, and explains how to make sure they are never performed on the main thread.

6.26.0

Released March 23, 2024

  • New: #1503 by @simba909: Conform Database.ColumnType to Sendable
  • New: #1510 by @groue: Add Sendable conformances and unavailabilities
  • New: #1511 by @groue: Database schema dump
  • New: #1515 by @groue: Support for the CAST SQLite function
  • Fixed: #1508 by @groue: Fix ValueObservation mishandling of database schema modification
  • Fixed: #1512: Decoding errors are now correctly reported when decoding NULL into a non-optional property of type Data or Date.

6.25.0

Released February 25, 2024

  • New: #1496 by @danielepantaleone: Add privacy manifest file.

    A PrivacyInfo.xcprivacy resource was added to the GRDB SPM package and Xcode projects. It declares that GRDB does not collect anything.

6.24.2

Released January 21, 2024

  • Documentation Update: #1485 The Sharing a Database guide was updated with a new recommendation for databases shared between multiple processes. Writers should always perform IMMEDIATE transactions in order to avoid the SQLITE_BUSY error that can occur when transactions overlap. The new recommendation fits in a single line of code: configuration.defaultTransactionKind = .immediate.
  • New: Associations that involve views instead of tables were already supported, with an explicit ForeignKey in their definition. When the foreign key is missing, a clear diagnostic message is now emitted, instead of an unhelpful "no such table" runtime error.

6.24.1

Released January 6, 2024

  • New: #1477: Remove shadow tables from database dump

6.24.0

Released January 6, 2024

  • New: #1466 by @barnettben: Add schema name option to database introspection methods

6.23.0

Released December 1, 2023

  • New: #1462 Temporary read-only access

6.22.0

Released November 26, 2023

  • New: #1452 by @groue: SQLite 3.44.0, FILTER and ORDER BY clauses in aggregate functions
  • New: #1460 by @groue: Explicit change notifications help applications deal with undetected database changes.
  • Documentation Update: The documentations of ValueObservation, DatabaseRegionObservation, and TransactionObserver have a new "Dealing with Undetected Changes" that documents possible strategies for notifying applications of undetected database changes.

6.21.0

Released October 29, 2023

  • New: #1448 by @groue: Add support for stable ordering and dump of views
  • New: #1449 by @groue: Backport temporary copies from GRDBSnapshotTesting

6.20.2

Released October 15, 2023 • diff

  • Fixed: #1442 by @groue: Extend the macOS availability of JSON functions

6.20.1

Released October 13, 2023 • diff

  • Fixed: Removed a debug print

6.20.0

Released October 13, 2023 • diff

  • New: #1439 by @groue: Dump requests
  • New: QueryInterfaceRequest.withStableOrder() returns a request with well-defined order, suitable for tests.

6.19.0

Released October 4, 2023 • diff

  • New: #1429 by @JhonnyBillM: Allow DatabaseValueConvertible types to customize their database JSON format
  • New: #1436 by @myyra and @groue: JSON functions
  • New: Database has learned to create indexes on expressions, and specify specific collations on indexed columns, with the create(index:on:expressions:options:condition:) method.
  • New: Codable records can specify coding strategies for their Data properties. See #1436 for more information.
  • Documentation Update: A new JSON Support article provides an overview of JSON handling.
  • Documentation Update: The Recommended Practices for Designing Record Types now recommend that record types with an auto-incremented id avoid conforming to the Identifiable protocol.

6.18.0

Released September 1, 2023 • diff

  • New: Expose the database path from DatabaseReader.

6.17.0

Released August 26, 2023 • diff

  • New: #1421 by @groue: Make it possible to open a DatabaseQueue in the WAL mode

6.16.0

Released July 9, 2023 • diff

6.15.1

Released June 17, 2023 • diff

  • Fixed: Fixed Xcode 15 warnings
  • Fixed: #1391 Fix upsert in FTS5-synchronized tables

6.15.0

Released June 2, 2023 • diff

  • New: #1382 Add DerivableRequest.all()
  • New: #1384 Allow ValueObservation to start from a truncated wal file
  • Documentation Update: The ValueObservation Performance documentation chapter explains how truncating WAL checkpoints impact ValueObservation.

6.14.0

Released May 25, 2023 • diff

  • New: #1376 Bitwise operations
  • New: #1379 Create indexes with a default name

6.13.0

Released May 15, 2023 • diff

  • New: #1373 Deprecate string literal arguments for TableDefinition.check()

6.12.0

Released April 29, 2023 • diff

  • Fixed: #1364 Fix a regression introduced with version 6.10.0, where starting multiple observations while performing writes could create a deadlock.
  • New: FetchableRecordDecoder is an object that decodes Decodable fetchable records from database rows. You may want to use this decoder when you want to use the Decodable initializer from init(row: Row).

6.11.0

Released April 17, 2023 • diff

  • New: #1361 DatabaseMigrator.eraseDatabaseOnSchemaChange ignores internal schema objects

6.10.2

Released April 10, 2023 • diff

6.10.1

Released April 1, 2023 • diff

  • Fixed: #1357 QueryInterfaceRequest.fetchCount no longer executes invalid SQL queries for some requests.

6.10.0

Released March 20, 2023 • diff

  • New: #1350 by @groue: DatabasePool won't close read-only connections if requested, and ValueObservation no longer opens a new database connection when it starts.

6.9.2

Released March 14, 2023 • diff

  • Fixed: #1349 by @JonLz: Fix Migrations.md example so it compiles
  • Fixed: Avoid the risk for pathologically deep stack trace, or stack overflow, introduced by #1348.

6.9.1

Released March 12, 2023 • diff

6.9.0

Released March 12, 2023 • diff

6.8.0

Released February 24, 2023 • diff

  • New: #1338 by @groue: TimestampedRecord sample code
  • New: EncodableRecord.databaseChanges(modify:) modifies a record and returns a dictionary of applied changes.
  • Documentation Update: The Record Timestamps and Transaction Date article provides a sample TimestampedRecord protocol that application may adapt for their own use.

6.7.0

Released February 19, 2023 • diff

6.6.1

Released January 15, 2023 • diff

  • Fixed: #1317 by @groue: Fix handling of multiple deep prefetched associations

6.6.0

Released December 29, 2022 • diff

  • New: #1304 by @groue: Expose generated columns with availability checks

6.5.0

Released December 5, 2022 • diff

  • New: #1299 by @groue: Record.find() convenience methods

6.4.0

Released November 28, 2022 • diff

  • New: #1293 by @groue: Enable concurrent reads from a WAL snapshot.
  • New: #1297 by @groue: SPM: expose the CSQLite product.
  • New: DatabaseReader.configuration.readQoS and writeQoS return the effective quality of service of read-only and write database accesses. This helps application code avoid priority inversion and similar scheduling misuses when needed.
  • New: DatabaseReader.configuration.maximumReaderCount returns the effective capacity for concurrent reads, so that application code can adapt when needed.
  • New: DatabasePool.makeSnapshot() no longer throws an error when the database is not in the WAL mode. In such case, the returned snapshot prevents all database modifications during its lifetime.
  • New: A new DatabaseSnapshotReader protocol was introduced for types that see an unchanging database content (DatabaseSnapshot and the new DatabaseSnapshotPool).
  • New: Database.registerAccess(to:) has ValueObservation track a region. This helps building optimized observations of a constant database region with ValueObservation.trackingConstantRegion(_:).
  • New: Open several connections to the same in-memory database with DatabaseQueue(named:).
  • New: TableDefinition has new methods for defining primary keys, with automatic NOT NULL constraints. They workaround an SQLite bug. Previous techniques for defining primary keys are preserved for backwards compatibility, but their use is not recommended.
  • New: The Database Schema documentation article has a brand new "Database Schema Recommendations" section.
  • New: Multiple improvements to the DocC documentation.

6.3.1

Released November 11, 2022 • diff

6.3.0

Released November 6, 2022 • diff

  • New: #1291 by @groue: DocC inline documentation
  • New: The Row.dataNoCopy methods are deprecated. Use Row.withUnsafeData instead.

6.2.0

Released October 28, 2022 • diff

  • New: #1289 by @arkie: Add support for passing in categories to the FTS5 unicode61 tokenizer (SQLite 3.25+)
  • Fixed: The FTS5Tokenizer.tokenize(query:) method no longer returns incorrect results for certain tokenizer arguments.

6.1.0

Released October 20, 2022 • diff

6.0.0

Released September 9, 2022 • diff

  • New: Bump custom SQLite builds v3.39.3
  • Fixed: #1274 Fixed a bug with HasManyThrough associations when the "through" association has the same association key as the association itself.
  • Fixed: #1275 Enhance error message for some requests involving associations on common table expressions.
  • Fixed: #1276 Fix build error with Xcode 14.0 RC (14A309)
  • Breaking Change: Request methods that accept a closure with a Database argument have been renamed with the WhenConnected suffix: request.filterWhenConnected { db in ... }, etc.

6.0.0-beta.4

Released August 28, 2022 • diff

6.0.0-beta.3

Released August 25, 2022 • diff

  • Fix: #1268 by @groue: Fix SQL generation of CHECK constraints
  • Breaking Change: The Column type is no longer Equatable
  • Documentation Update: Migrating From GRDB 5 to GRDB 6 describes in detail how to update records that customize their persistence methods.
  • Documentation Update: The Single-Row Tables guide was updated for the new persistence callbacks.

6.0.0-beta.2

Released August 23, 2022 • diff

  • New: Extended UPSERT apis with the ability to define the conflict target, and the assignments performed in case of conflicts.
  • Documentation Update: A new Upsert chapter describes upserts in detail.

6.0.0-beta

Released August 21, 2022 • diff

New

Upgrading your app can bring improvements: check Migrating From GRDB 5 to GRDB 6 for some suggestions.

  • :star: Support for UPSERT: player.upsert(db), etc. See Persistence Methods.

  • :star: Support for the RETURNING clause: player.insertAndFetch(db), Player.deleteAndFetchAll(db), etc. See Persistence Methods and the RETURNING clause.

  • :star: Persistence Callbacks allow record types to customize persistence methods: didInsert, willSave, etc.

  • :star: Better support for unexpected database values. Where GRDB 5 would crash during encoding and decoding database values, GRDB 6 has learned to throw errors instead. Record protocols throw decoding and encoding errors, and value requests throw errors on invalid inputs.

  • Request protocols and cursors now define primary associated types, enabled by SE-0346.

  • All persistence methods now accept an explicit conflict policy: player.insert(db, onConflict: .replace), etc.

  • You can append the contents of a cursor to a collection with RangeReplaceableCollection.append(contentsOf:).

  • ValueObservation.map now accepts a throwing closure argument.

Documentation Updates

Breaking Changes

  • Removed deprecated methods
  • :star: Bumped requirements:
    • Swift 5.7+ and Xcode 14+ are required.
    • iOS 11.0+ / macOS 10.13+ / tvOS 11.0+ / watchOS 4.0+ / SQLite 3.19.3+ are required.
  • :star: Record protocols were refactored:
    • The FetchableRecord.init(row:) initializer can now throw errors.
    • The EncodableRecord.encode(to:) method can now throw errors.
    • Record types can no longer override persistence methods. You use Persistence Callbacks instead.
  • Various breaking changes:
    • The in-memory DatabaseQueue() initializer can now throw errors.
    • The selectID() method is replaced with selectPrimaryKey(as:).
    • Cursor.isEmpty is now a throwing property, instead of a method.
    • The Record.copy() method was removed, without replacement.
    • The DerivableRequest.limit(_:offset_:) method was removed, without replacement.
    • DatabaseRegionObservation.start(in:onError:onChange:) now returns a cancellable.
    • The DatabaseRegionObservation.extent property was removed.
    • The statement property of database cursors was replaced with read-only properties such as sql or columnNames.
    • The Database.afterNextTransactionCommit(_:) method was renamed Database.afterNextTransaction(onCommit:onRollback:), and is now able to report rollbacks as well as commits.

5.26.1

Released September 8, 2022 • diff

  • Fixed: #1276 Fix build error with Xcode 14.0 RC (14A309)

5.26.0

Released July 9, 2022 • diff

  • New: #1248 by @groue: Avoid double notification of the initial value for ValueObservation on DatabasePool
  • New: #1253 by @george-signal: Make memory management optional
  • Fixed: DatabasePool no longer prevents database reads when UIKit posts UIApplication.didReceiveMemoryWarningNotification (see #1253 for more information).

5.25.0

Released June 11, 2022 • diff

5.24.1

Released May 26, 2022 • diff

  • Fixed: #1217 by @GetToSet: Fix doc issue on TableRequest.filter(keys:).
  • Fixed: #1225 by @groue: Prevent heavy DatabasePool concurrent reads from creating too many threads

5.24.0

Released May 1, 2022 • diff

  • Fixed: #1203 by @EvanHahn: Fix changelog links
  • Fixed: #1212 by @MartinP7r: Fix apple docs links
  • Fixed: #1213 by @groue: Fix crash when the number of active ValueObservations is high
  • Breaking Change: Transactions performed during a read-only database access are no longer notified to transaction observers. This is, strictly speaking, a breaking change. However it should have no impact since read-only transactions have very little interest.

5.23.0

Released April 16, 2022 • diff

  • Breaking Change: #1200 by @groue: Require Swift 5.6 Compiler for experimental Concurrency Support

5.22.2

Released April 2, 2022 • diff

  • Fixed a 5.22.0 regression: #1196 by @layoutSubviews: Fix a crash when an observation is quickly cancelled

5.22.1

Released March 26, 2022 • diff

  • Fixed a 5.22.0 regression: #1194 ValueObservation could deadlock when the database is configured with a serial target DispatchQueue.

5.22.0

Released March 22, 2022 • diff

  • New: #1186 by @benrb: DatabaseError provide error message as localizedFailureReason
  • Breaking Change: #1183 by @groue: Starting a ValueObservation keeps a strong reference on the database connection.

5.21.0

Released February 6, 2022 • diff

  • New: #1165 by @guidedways: Support dynamic linking via Swift Package Manager
  • Breaking Change: #1164 by @groue: Drop experimental async apis from DatabaseMigrator

5.20.0

Released February 1, 2022 • diff

  • Fixed: Fixed a bug of including(all:) for composite foreign keys and limited requests.
  • Fixed: #1162 by @groue: Fix truncate optimization handling.
  • New: #1160 by @groue: Hide statement arguments by default.
  • New: #1161 by @groue: Target DispatchQueue for non-read-only database connections.
  • Documentation Update: The Database Configuration chapter explains how to opt in for public statement arguments in DEBUG builds.

5.19.0

Released January 19, 2022 • diff

5.18.0

Released January 9, 2022 • diff

5.17.0

Released December 14, 2021 • diff

  • New: :star: #1079 by @groue: Async / Await
  • New: DatabaseRegion(table: tableName) is deprecated. Use Table(tableName) instead.
  • New: The ABS and LENGTH SQL functions are now available on association aggregates, through abs(aggregate) and length(aggregate).
  • New: Support for the TOTAL aggregate function. You can use total in Swift, at all places sum is available.
  • New: ValueObservation.removeDuplicates(by:) with a closure argument.
  • New: Testing for the existence of an associated record with TableAlias.exists now supports associated views, and associated tables WITHOUT ROWID that have a compound primary key.
  • Fixed: Database.primaryKey(_:) throws when given the name of a view.
  • Documentation Update: :star: The Concurrency Guide was updated for the new support for asynchronous Swift.
  • Documentation Update: :star: GRDBAsyncDemo is a new SwiftUI demo app that uses the new async apis.
  • Documentation Update: A new FAQ gives hints for avoiding a Mutation of captured var in concurrently-executing code compiler error.
  • Documentation Update: #1107 by @tcwalther: Fix docstring for Database.create(index: ...)
  • Documentation Update: #1110 by @maxhumber: Minor changes to a tip in the README

5.16.0

Released December 5, 2021 • diff

5.15.0

Released December 2, 2021 • diff

  • Fixed: ValueObservation now always fetches fresh values in an isolated fashion. This prevents all risks of fetching inconsistent data even if an external connection modifies the database.
  • New: Table now conforms to DatabaseRegionConvertible. You can write DatabaseRegionObservation(tracking: Table("player")).
  • New: #1102 by @groue: Explicit tracked region for ValueObservation

5.14.0

Released November 25, 2021 • diff

  • Fix: ForeignKeyViolation.failureDescription(_:) now accepts table names that require quoting.
  • Fix: Add missing public qualifier on ForeignKeyViolation properties.
  • New: ForeignKeyViolation.databaseError(_:) turns a foreign key violation into a DatabaseError.
  • Documentation Update: the demo apps were modernized for iOS 15+. The SwiftUI demo app now uses the GRDBQuery package in order to update its views according to the database content.

5.13.0

Released November 7, 2021 • diff

  • Breaking Change: #1076 by @groue: Require Swift 5.3 and Xcode 12
  • New: :star: #1088 by @groue: Shared ValueObservation
  • New: :star: #1095 by @groue: Precise foreign key checks for migrations
  • New: #1078 by @groue: Non-mutating persistence methods saved and inserted, and existence-checking methods isEmpty and exists
  • New: DatabasePool.erase() prevents concurrent reads until it has completed.
  • New: The close() method allows precise closing of database connections.
  • New: Filtering records by single-column primary key now properly encodes dates and uuids according to the customized strategies (filter(id:), deleteAll(_:keys:), etc.)
  • New: DatabaseUUIDEncodingStrategy.lowercaseString can encode UUID as a lowercased string. For clarity, the string strategy has been deprecated and renamed uppercaseString.
  • Documentation Update: :star: The Concurrency Guide got a major overhaul.
  • Documentation Update: :star: A new ValueObservation Sharing chapter describes how to share database observations and spare database resources.
  • Documentation Update: :star: The Migrations guide tells how you can mitigate slow foreign key checks during schema changes.
  • Documentation Update: The Date and UUID Coding Strategies chapter describes the new support for date and uuid primary key coding in requests by single-column primary key.
  • Documentation Update: A new Testing for Record Existence chapter describes the new request.isEmpty(_:), Record.exists(_:id:) and Record.exists(_:key:) methods.

5.12.0

Released September 25, 2021 • diff

  • Breaking Change: Minimum iOS version is now iOS 11.0, and 32-bits devices are no longer supported. This fixes issues introduced by Xcode 13 (#1033, #1059).
  • New: FTS3Pattern(matchingAllPrefixesIn:) and FTS5Pattern(matchingAllPrefixesIn:) let you build full-text search patterns suitable for prefix queries.
  • New: FTS3.tokenize(_:) and FTS5Tokenizer.tokenize(_:) let you tokenize input strings.
  • Documentation Update: Full-text search documentation was updated for the new search pattern initializers (FTS3/4, FTS5), and tokenization methods (FTS3/4, FTS5).

5.11.0

Released September 3, 2021 • diff

  • Fixed: Version 5.10.0, when embedded as an Xcode project, would enable the FTS5 full-text engine on system versions that do not provide it.
  • New: #1046 by @groue: Improve performance of by-index row decoding
  • New: #1029 by @sberrevoets, @groue: Column coding strategies for Codable records

5.10.0

Released August 22, 2021 • diff

  • New: #1036 by @groue: Restore minimal CI tests
  • New: #1037 by @groue: Support BUILD_LIBRARY_FOR_DISTRIBUTION
  • New: #1038 by @GetToSet: Add match operator in ColumnExpression for FTS5
  • New: With Swift 5.5+, enhance access to Column.rowID. Row and PersistenceContainer subscripts now accept row[.rowID] and container[.rowID] (SE-0299)
  • Documentation Update: A new Combine and Data Consistency chapter explains how to make sure database publishers do not break important database invariants.

5.9.0

Released August 15, 2021 • diff

  • Fixed: #980 by @jroselightricks: Fix spelling

  • Fixed: #989 by @pp5x: FTS: add support of ifNotExists in synchronize()

  • Fixed: #999: request(for: association) no longer crashes when the foreign key contains a NULL value.

  • Fixed: #1025 by @mattgallagher: Fix ValueObservation crash

  • Fixed: Fix thread unsafety in ValueObservation.print()

  • New: The selectID() method is now available for Identifiable Records

  • New: Cached prepared statements can profit from SQL Interpolation:

    let updateStatement = try db.cachedStatement(literal: "INSERT ...")
//                                           ~~~~~~~

  • New: #993 by @groue: QueryInterfaceRequest builder with dynamic table/view name

  • New: Types that adopt both DatabaseValueConvertible and Codable now profit from automatic JSON encoding and decoding.

  • New: #1010 by @tternes: Add VACUUM INTO Support

  • New: #1012 by @ZevEisenberg: Add brackets to urls in doc comments to make them clickable

  • New: #1019 by @groue: Merge prepared statement types, and introduce statement cursor

  • Documentation Update: The Requests chapter was updated for the new Table type that can build requests without any record type.

  • Documentation Update: The Custom Value Types chapter was extended about the new support for codable value types encoded as JSON arrays or objects.

  • Documentation Update: The Fetching Methods and Prepared Statements chapters have been updated for the unique Statement class, and the new Database.allStatements() method.

5.8.0

Released May 16, 2021 • diff

  • New: Support for the ESCAPE clause with the LIKE operator.

  • New: You can now define an SQLRequest without any generic qualifier (which defaults to Row):

    let request = SQLRequest("SELECT ...")

  • New: #967 by @steipete: Make SelectStatement conform to CustomStringConvertible

  • Fixed: The DerivableRequest.limit(_:offset:) method was ill-designed, and removed from the documentation. It is unfortunately impossible to deprecate it without triggering warnings on the legit use cases (on QueryInterfaceRequest).

  • Fixed: #973: Restore access to attached databases from record types

  • Fixed: #974: Provide access to included associations when root table is not selected

  • Documentation Update: A new Query Interface Organization document reveals the relationship between the various components of the GRDB query builder.

5.7.4

Released April 11, 2021 • diff

  • New: #953: Refactor the SwiftUI demo app
  • Fixed: #955 by @steipete: Robustness of @Query in the SwiftUI demo app
  • Fixed: #956: Fix case-sensitivity of region-based database observation
  • New: #958 by @chrisballinger: Always add userInfo to databaseJSONDecoder and databaseJSONEncoder
  • New: #960 by @MartinP7r: Add tests for userInfo being applied to database encoder/decoder

5.7.3

Released April 5, 2021 • diff

  • Fixed: #950 by @MartinP7r: Fix memory consumption when encoding JSON columns
  • Fixed: #951 by @alexwlchan: Fix documentation typo
  • Fixed: #952 by @holsety: Fix documentation typo
  • Documentation Update: #953: Refactor the SwiftUI demo app

5.7.2

  • Fixed: Really fix breaking change and restore SQLLiteral as a deprecated alias for SQL.

5.7.1

  • Fixed: Fix breaking change and restore SQLLiteral as a deprecated alias for SQL.

5.7.0

Released March 28, 2021 • diff

  • New: #947 by @chrisballinger: Allow access to Encoder from KeyedEncodingContainer

  • New: Record types that adopt the standard Identifiable protocol have gained type-safe methods that deal with the primary key. For example:

    let player = try Player.fetchOne(db, id: 42)
try Player.deleteAll(db, ids: [1, 2, 3])

    See the new Identifiable Records documentation chapter for more information.

  • New: SQLLiteral has more use cases than initialy expected, and is renamed SQL.

  • New: SQL literal can now be directly used as an expression, an ordering term, or a selection item.:

    let name = "O'Brien"
let request = Player
    .select(SQL("id, score"), ...)
    .filter(SQL("name = \(name)") && ...)
    .order(SQL("score DESC"), ...)

  • New: Table creation DSL now supports columns and constraints defined with raw SQL String or SQL literal:

    try db.create(table: "player") do { t in
    t.column(sql: "id INTEGER PRIMARY KEY AUTOINCREMENT")
    t.column(literal: "name TEXT DEFAULT \("Anonymous")")
    t.constraint(sql: "CHECK (LENGTH(name) > 0)")
    t.constraint(literal: "CHECK (LENGTH(name) <= \(100))")
}

  • New: Prepared statements can profit from SQL Interpolation:

    let updateStatement = try db.makeUpdateStatement(literal: "INSERT ...")
let selectStatement = try db.makeSelectStatement(literal: "SELECT ...")
//                                               ~~~~~~~

  • New: DatabaseMigrator can now asynchronously migrate a database. A Combine publisher is also available.

  • New: Added support for the EXISTS and NOT EXISTS subquery operators. See the updated SQL Operators documentation.

  • New: Foundation.Decimal can now be stored in the database, and all Foundation number types can be decoded from decimal numbers stored as strings. See the NSNumber, NSDecimalNumber, and Decimal chapter for details.

5.6.0

Released March 12, 2021 • diff

5.5.0

Released March 3, 2021 • diff

  • New: You can now define common table expressions without any generic qualifier (which defaults to Row):

    let cte = CommonTableExpression(...)

    The Common Table Expressions Guide was updated accordingly.

  • New: DatabaseQueue reading methods are now wrapped in a deferred transaction. This guarantees snapshot isolation in case of concurrent writes performed by external connections, and makes DatabaseQueue a type suitable for shared databases.

  • Fixed: DatabaseQueue.read is now declared throws instead of rethrows.

  • Fixed: #930: Fix SQL generation for COLLATE, IN, NOT IN

5.4.0

Released February 15, 2021 • diff

  • Breaking Change: The query interface was refactored and some types such as SQLExpression are no longer a protocol.

    This may break some applications that rely on Swift type inference, such as in the following example:

    // No longer compiles
let values = [Column("score"), Column("score") + Column("bonus")]

    The fix is to add an explicit declaration of the desired type:

    // A possible fix
let values: [SQLExpressible] = [Column("score"), Column("score") + Column("bonus")]

    Occurrences of such code breakage should be very rare.

  • New: SQL Interpolation supports embedding collations into SQL literals:

    let request: SQLRequest<Player> = "SELECT * FROM player ORDER BY email COLLATION \(.nocase)"
let request: SQLRequest<Player> = "SELECT * FROM player ORDER BY name COLLATION \(.localizedCompare)"

  • Documentation update: Adding support for missing SQL functions or operators explains how to extend the query interface when needed.

  • Documentation update: The Demo Applications now provide tests for the database access layer.

5.3.0

Released January 9, 2021 • diff

5.2.0

Released November 29, 2020 • diff

  • New: #868: ValueObservation optimization is opt-in.
  • New: #872: Parse time zones
  • Documentation update: The ValueObservation Performance chapter was extended with a tip for observations that track a constant database region.
  • Documentation update: The Date and DateComponents chapter describes the support for time zones.
  • Documentation update: A caveat (#871) with the including(all:) method, which may fail with a database error of code SQLITE_ERROR (1) "Expression tree is too large" when you use a compound foreign key and there are a lot of parent records, is detailed in the Joining And Prefetching Associated Records chapter.

5.1.0

Released November 1, 2020 • diff

5.0.3

Released October 25, 2020 • diff

  • Fixed: #859: Database.close() is idempotent
  • Fixed: #850 by @mtancock: Add buildActiveScheme to playground settings so they'll build under Xcode 12
  • Fixed: #849 by @MarshalGeazipp: Fix grammar mistake AssociationsBasics.md

5.0.2

Released October 6, 2020 • diff

  • Fixed: #844: Fix a crash in the demo app
  • Fixed: #847: Remove dependency on SQLITE_ENABLE_SNAPSHOT

5.0.1

Released September 27, 2020 • diff

  • Fixed: #841: Fix GRDB 5 regression with indexes on expressions
  • The GRDBCombineDemo Combine + SwiftUI demo application was updated for the SwiftUI App lifecycle introduced in iOS 14.

5.0.0

Released September 20, 2020 • diff

  • Fixed: #838: Have indexed columns inherit the ifNotExists flag from table creation.

5.0.0-beta.11

Released September 7, 2020 • diff

  • Breaking Change: #831: Improve Configuration.prepareDatabase

5.0.0-beta.10

Released July 30, 2020 • diff

  • New: DatabasePool readers don't invalidate their database schema cache until schema is actually changed.
  • Breaking Change: #817: Allow query planner to optimize some boolean tests

5.0.0-beta.9

Released July 23, 2020 • diff

  • New: #813: Expose SQLite 3.31.1 APIs to iOS, macOS, tvOS, watchOS
  • Fixed: #814: Fix regression with views

5.0.0-beta.8

Released July 19, 2020 • diff

  • New: #811: Introduce RenameColumnAdapter

5.0.0-beta.7

Released July 14, 2020 • diff

  • New: #802 by @GetToSet: Add tokenchars support for ascii tokenizer in FTS5
  • New: fetchSet has joined fetchCursor, fetchAll and fetchOne in the group of universal fetching methods.
  • Breaking Change: #803: Remove FetchedRecordsController
  • Breaking Change: Removed TableRecord.primaryKey and selectPrimaryKey(as:) introduced in 5.0.0-beta.5
  • Breaking Change: Many types and methods that support the query builder used to be publicly exposed and flagged as experimental. They are now private, or renamed with an underscore prefix, which means they are not for public use.
  • Breaking Change: Defining custom FetchRequest types is no longer supported.
  • Breaking Change: Defining custom RowAdapter types is no longer supported.
  • Fixed: Fix rare occurences of an SQLITE_BUSY error when opening a DatabaseSnapshot.
  • Fixed: Work around an SQLite bug which prevents rollbacking a transaction with sqlite3_commit_hook.
  • The How do I filter records and only keep those that are NOT associated to another record? FAQ has been updated.

5.0.0-beta.6

Released June 29, 2020 • diff

  • New: #798: Debugging operators for ValueObservation
  • New: #800: Xcode 12 support
  • New: #801: Combine support
  • New: Faster decoding of Date and DateComponents

Documentation Diff

  • The ValueObservation Operators chapter was extended with a description of the two new debugging operators handleEvents and print.

  • A new GRDB ❤️ Combine guide describes the various Combine publishers that read, write, and observe the database.

  • GRDBCombineDemo is a new Combine + SwiftUI demo application.

5.0.0-beta.5

Released June 15, 2020 • diff

  • Breaking Change #795: Enhanced support for WAL Checkpoints
  • New: Database.maximumStatementArgumentCount returns the maximum number of arguments accepted by an SQLite statement.
  • New: Optimize DatabasePool handling of ValueObservation when SQLite is compiled with the SQLITE_ENABLE_SNAPSHOT option. We are now able to avoid fetching the observed value when we can prove that the database wasn't changed between the initial fetch and the beginning of transaction tracking. This optimization avoids duplicate notifications.
  • New: The query interface now exposes the primary key through TableRecord.primaryKey, as well as the selectPrimaryKey(as:) method.

Documentation Diff

5.0.0-beta.4

Released June 6, 2020 • diff

Documentation Diff

  • Migrating From GRDB 4 to GRDB 5 was updated for RxGRDB and GRDBCombine 1.0 beta 2, which haved change their way to configure how ValueObservation schedules fresh database values.
  • The SQL Functions chapter was updated for the new julianDay and dateTime functions.

New

  • #794: Name of Database Connections
  • Add the julianDay and dateTime functions

5.0.0-beta.3

Released June 1, 2020 • diff

Documentation Diff

Fixed

  • #784: Fix observation of eager-loaded to-many associations

Breaking Changes

  • #790: Bump required iOS version to 10.0
  • #791: Extend tracing of statement execution

5.0.0-beta.2

Released May 11, 2020 • diff

Documentation Diff

New

  • #772: Update the Database Sharing Guide with mention of the persistent WAL mode
  • #775: DatabaseMigrator can check if it has been superseded

Breaking Changes

  • #774: All requests are usable as SQL expressions and collections

Fixed

  • #773: Allow subqueries to refer to outer tables

5.0.0-beta

Released May 2, 2020 • diff

GRDB 5 is a release focused on Swift 5.2, and removing technical debt.

There are breaking changes, though as few as possible. They open the door for future library improvements. And they have GRDB, GRDBCombine, and RxGRDB offer a common behavior.

New features include support for SQL subqueries, and a simplified handling of database errors. The most demanding users will also find it easier to switch between the system SQLite, SQLCipher, and custom SQLite builds.

A glimpse on the new features

All requests can now be used as subqueries:

// Define a request with the query interface or raw SQL
let maximumScore = Player.select(max(Column("score")))
let maximumScore: SQLRequest<Int> = "SELECT MAX(score) FROM player"

// Use the request as a subquery in the query interface
let request = Player.filter(Column("score") == maximumScore)
let bestPlayers = try request.fetchAll(db)

// Use the request as a subquery in SQL requests
let request: SQLRequest<Player> = "SELECT * FROM player WHERE score = (\(maximumScore))"
let bestPlayers = try request.fetchAll(db)

Catch specific SQLite error codes in a simplified fashion:

do {
    try ...
} catch DatabaseError.SQLITE_CONSTRAINT_FOREIGNKEY {
    // foreign key constraint error
} catch DatabaseError.SQLITE_CONSTRAINT {
    // any other constraint error
} catch {
    // any other database error
}

Reuse the same code for system SQLite, SQLCipher, and custom SQLite builds:

// Supported in all GRDB flavors
import GRDB
let sqliteVersion = String(cString: sqlite3_libversion())

Documentation Diff

New

  • #749: Drop submodules used by performance tests
  • #754: Match DatabaseError on ResultCode
  • #756: Export the underlying SQLite library

Breaking Changes

  • #719: Bump required Swift version to 5.2
  • #720: Turn deprecated APIs into unavailable ones
  • #722: SE-0253: Callable values of user-defined nominal types
  • #728: Make ValueObservation error handling mandatory
  • #729: ValueObservation always emits an initial value
  • #731: Hide ValueObservation implementation details
  • #732: Remove ValueObservation.compactMap
  • #736: Relax ValueObservation Guarantees
  • #737: Force implicit database region for ValueObservation
  • #738: Remove all observationForCount/All/First methods
  • #742: ValueObservation scheduling is no longer an attribute of the observation
  • #745: Explicit ValueObservation cancellation
  • #747: Rename GRDBCustomSQLite to GRDB
  • #750: Batch updates do not need any operator
  • #752: Remove ValueObservation.combine
  • #770: Subqueries

Fixed

  • #601: ValueObservation won't start until concurrent write transaction has ended
  • #697: SQLInterpolation could not work with QueryInterfaceRequest
  • #743: Rename GRDBCustomSQLite to GRDB for compatibility with dependents?

4.14.0

Released April 23, 2020 • diff

New

  • #766 by @mtancock: Add Codable support to DatabaseDateComponents

4.13.0

Released April 15, 2020 • diff

Fixed

  • Restored support for Xcode 10.0 and Xcode 10.1, broken in 4.12.2
  • #759: Fix batch updates of complex requests

New

  • #761: Deprecate the batch update <- operator

4.12.2

Released April 13, 2020 • diff

Fixed

  • #757: Don't load association inflections unless necessary

4.12.1

Released March 29, 2020 • diff

Fixed

  • #744: Fix DatabaseMigrator deadlock with serial target queues

4.12.0

Released March 21, 2020 • diff

New

  • Batch updates now accept nil assignments:

    // UPDATE player SET score = NULL
try Player.updateAll(db, scoreColumn <- nil)

  • DatabaseMigrator can now recreate the database if a migration has been removed, or renamed (addresses #725).

  • DatabaseMigrator querying methods have been enhanced:

    // New
dbQueue.read(migrator.hasCompletedMigrations)
dbQueue.read(migrator.completedMigrations).contains("v2")
dbQueue.read(migrator.completedMigrations).last == "v2"
dbQueue.read(migrator.appliedMigrations)

// Deprecated
migrator.hasCompletedMigrations(in: dbQueue)
migrator.hasCompletedMigrations(in: dbQueue, through: "v2")
migrator.lastCompletedMigration(in: dbQueue) == "v2"
migrator.appliedMigrations(in: dbQueue)

4.11.0

Released March 2, 2020 • diff

New

  • #706: Enhance SQLLiteral and SQL interpolation again
  • #710: Check if all migrations have been applied
  • #712 by @pakko972: Automatic iOS memory management
  • #713: Enhance DatabaseMigrator isolation

Breaking Change

  • #709: Simplify DatabaseMigrator API

Database migrations have a new behavior which is a breaking change. However, it is very unlikely to impact your application.

In previous versions of GRDB, a foreign key violation would immediately prevent a migration from successfully complete. Now, foreign key checks are deferred until the end of each migration. This means that some migrations will change their behavior:

// Used to fail, now succeeds
migrator.registerMigration(...) { db in
    try violateForeignKeyConstraint(db)
    try fixForeignKeyConstraint(db)
}

// The catch clause is no longer called
migrator.registerMigration(...) { db in
    do {
        try performChanges(db)
    } catch let error as DatabaseError where error.resultCode == .SQL_CONSTRAINT {
        // Handle foreign key error
    }
}

If your application happens to define migrations that are impacted by this change, please open an issue so that we find a way to restore the previous behavior.

4.10.0

Released February 23, 2020 • diff

New

  • #689 by @gjeck: Add support for renaming columns within a table
  • #690: Enhance SQLLiteral and SQL interpolation

4.9.0

Released January 17, 2020 • diff

New

  • #683: String concatenation
  • #685 by @gjeck: Add cache for TableRecord.defaultDatabaseTableName

4.8.1

Released January 12, 2020 • diff

Fixed

  • #677: Fix associations altered by another association

4.8.0

Released January 8, 2020 • diff

New

  • #676: More batch delete and update

4.7.0

Released December 18, 2019 • diff

New

  • #656: Type inference of selected columns
  • #659: Database interruption
  • #660: Database Lock Prevention
  • #662: Upgrade custom SQLite builds to version 3.30.1 (thanks to @swiftlyfalling)
  • #668: Database Suspension

Breaking Changes

Custom SQLite builds now disable by default the support for the Double-quoted String Literals misfeature. This is a technically a breaking change, but it fixes an SQLite bug. You can restore the previous behavior if your application relies on it:

// Enable support for the Double-quoted String Literals misfeature
var configuration = Configuration()
configuration.acceptsDoubleQuotedStringLiterals = true
let dbQueue = try DatabaseQueue(path: ..., configuration: configuration)

Documentation Diff

The new Interrupt a Database chapter documents the new interrupt() method.

The new Sharing a Datatase in an App Group Container guide explains how to setup GRDB when you share a database in an iOS App Group container.

API Diff

 struct Configuration {
+    var observesSuspensionNotifications: Bool // Experimental
+    var acceptsDoubleQuotedStringLiterals: Bool
 }

 class Database {
+    static let suspendNotification: Notification.Name // Experimental
+    static let resumeNotification: Notification.Name  // Experimental
 }

 extension DatabaseError {
+    var isInterruptionError: Bool { get }
 }
 
 protocol DatabaseReader {
+    func interrupt()
 }
 
 extension SQLSpecificExpressible {
+    #if GRDBCUSTOMSQLITE
+    var ascNullsLast: SQLOrderingTerm { get }
+    var descNullsFirst: SQLOrderingTerm { get }
+    #endif
 }

4.6.2

Released November 20, 2019 • diff

Fixed

4.6.1

Released November 10, 2019 • diff

Fixed

  • #647: Honor conflict resolution for batch updates

4.6.0

Released November 9, 2019 • diff

New

  • #646: Batch updates

Documentation Diff

The Update Requests chapter documents the new support for batch updates introduced in the query interface.

The Associations Guide has gained a new Ordered Associations chapter which explains how to define ordered HasMany and HasManyThrough associations.

4.5.0

Released October 15, 2019 • diff

Fixed

  • The DatabaseMigrator.eraseDatabaseOnSchemaChange option no longer fails when migrations depend on database configuration.
  • Fixed DatabasePool.reentrantRead which was not actually reentrant.
  • #631: Fix custom SQLite builds
  • #632 by @runhum: Fix documentation typo

New

  • #622: Allow observation of FTS4 virtual tables
  • #627: Swift Package Manager: define SQLite as a system library target
  • #633: SQLITE_ENABLE_PREUPDATE_HOOK support with CocoaPods
  • #635: Sunset FetchedRecordsController

Documentation Diff

The Support for SQLite Pre-Update Hooks chapter has been updated with a way to enable extra GRDB APIs for the SQLITE_ENABLE_PREUPDATE_HOOK option with CocoaPods.

The Demo Application no longer uses FetchedRecordsController, which has been sunsetted. Instead, it tracks database changes with ValueObservation, and animates its table view with the Swift built-in difference(from:) method.

4.4.0

Released September 6, 2019 • diff

New

  • #602: Don't keep the sqlCipher passphrase in memory longer than necessary
  • #603: DatabasePool write barrier

Documentation Diff

SQLCipher passphrase management has been refactored: you will get deprecation warnings. Check out the rewritten Encryption chapter in order to migrate your code and remove those warnings.

The Advanced DatabasePool chapter has been extended for the new barrierWriteWithoutTransaction method.

API Diff

Deprecations

 class DatabaseQueue {
+    @available(*, deprecated)
     func change(passphrase: String) throws
 }
 
 class DatabasePool {
+    @available(*, deprecated)
     func change(passphrase: String) throws
 }
 
 struct Configuration {
+    @available(*, deprecated)
     var passphrase: String?
 }

New Methods

 class DatabasePool {
+    func barrierWriteWithoutTransaction<T>(_ updates: (Database) throws -> T) rethrows -> T
+    func invalidateReadOnlyConnections()
 }
 
 class Database {
+    func usePassphrase(_ passphrase: String) throws
+    func changePassphrase(_ passphrase: String) throws
+    var lastErrorCode: ResultCode
+    var lastErrorMessage: String?
 }

4.3.0

Released August 28, 2019 • diff

New

4.2.1

Released August 13, 2019 • diff

Fixed

  • #592: Fix Data interpolation

4.2.0

Released August 6, 2019 • diff

New

  • #570 by @chrisballinger: Allow Swift static library integration via CocoaPods
  • #576: Expose table name and full-text filtering methods to DerivableRequest
  • #586: Automatic region tracking for ValueObservation

Fixed

  • #560 by @bellebethcooper: Minor typo fix
  • #562: Fix crash when using more than one DatabaseCollation
  • #577: Rename aliased(_:) methods to forKey(_:)
  • #585: Fix use of SQLite authorizers

Other

  • #563: More tests for eager loading of hasMany associations
  • #574: SwiftLint

Documentation Diff

The ValueObservation chapter has been updated so that it fosters the new ValueObservation.tracking(value:) method. Other ways to define observations are now described as optimizations.

API Diff

-protocol DerivableRequest: FilteredRequest, JoinableRequest, OrderedRequest, SelectionRequest { }
+protocol DerivableRequest: FilteredRequest, JoinableRequest, OrderedRequest, SelectionRequest, TableRequest { }

-extension QueryInterfaceRequest {
-    func matching(_ pattern: FTS3Pattern?) -> QueryInterfaceRequest<T>
-}
-extension QueryInterfaceRequest {
-    func matching(_ pattern: FTS5Pattern?) -> QueryInterfaceRequest<T>
-}
+extension TableRequest where Self: FilteredRequest {
+    func matching(_ pattern: FTS3Pattern?) -> Self
+}
+extension TableRequest where Self: FilteredRequest {
+    func matching(_ pattern: FTS5Pattern?) -> Self
+}
 
 protocol Association: DerivableRequest {
-    associatedtype OriginRowDecoder
+    associatedtype OriginRowDecoder: TableRecord
 }

-struct BelongsToAssociation<Origin, Destination>: AssociationToOne { }
-struct HasManyAssociation<Origin, Destination>: AssociationToMany { }
-struct HasManyThroughAssociation<Origin, Destination>: AssociationToMany { }
-struct HasOneAssociation<Origin, Destination>: AssociationToOne { }
-struct HasOneThroughAssociation<Origin, Destination>: AssociationToOne { }
+struct BelongsToAssociation<Origin: TableRecord, Destination: TableRecord>: AssociationToOne { }
+struct HasManyAssociation<Origin: TableRecord, Destination: TableRecord>: AssociationToMany { }
+struct HasManyThroughAssociation<Origin: TableRecord, Destination: TableRecord>: AssociationToMany { }
+struct HasOneAssociation<Origin: TableRecord, Destination: TableRecord>: AssociationToOne { }
+struct HasOneThroughAssociation<Origin: TableRecord, Destination: TableRecord>: AssociationToOne { }

-struct QueryInterfaceRequest<T>: DerivableRequest { }
+struct QueryInterfaceRequest<T>: FilteredRequest, OrderedRequest, SelectionRequest, TableRequuest { }
+extension QueryInterfaceRequest: JoinableRequest where T: TableRecord { }
+extension QueryInterfaceRequest: DerivableRequest where T: TableRecord { }

 extension AssociationAggregate {
+    @available(*, deprecated, renamed: "forKey(_:)")
     func aliased(_ name: String) -> AssociationAggregate<RowDecoder>
+    func forKey(_ name: String) -> AssociationAggregate<RowDecoder>
 
+    @available(*, deprecated, renamed: "forKey(_:)")
     func aliased(_ key: CodingKey) -> AssociationAggregate<RowDecoder>
+    func forKey(_ key: CodingKey) -> AssociationAggregate<RowDecoder>
 }
 
 extension SQLSpecificExpressible {
+    @available(*, deprecated, renamed: "forKey(_:)")
     func aliased(_ name: String) -> SQLSelectable
+    func forKey(_ name: String) -> SQLSelectable
 
+    @available(*, deprecated, renamed: "forKey(_:)")
     func aliased(_ key: CodingKey) -> SQLSelectable
+    func forKey(_ key: CodingKey) -> SQLSelectable
 }
 
 extension ValueObservation where Reducer == Void {
+    static func tracking<Value>(fetch: @escaping (Database) throws -> Value) -> ValueObservation<ValueReducers.Fetch<Value>>
 }

4.1.1

Released June 22, 2019 • diff

This version is identical to 4.1.0.

4.1.0

Released June 20, 2019 • diff

  • #537: Remove useless parenthesis from generated SQL
  • #538 by @Timac: Add FAQ to clarify "Wrong number of statement arguments" error with "like '%?%'"
  • #539: Expose joining methods on both requests and associations
  • #540: Update SQLite to 3.28.0 (thanks to @swiftlyfalling)
  • #542: Move eager loading of hasMany associations to FetchRequest
  • #546 by @robcas3: Fix SPM errors with Xcode 11 beta
  • #549 Support for Combine
  • #550 Asynchronous Database Access Methods
  • #555 Avoid a crash when read-only access can't be established

Documentation Diff

Good practices evolve: the Define Record Requests chapter of the The Good Practices for Designing Record Types has been rewritten.

The Examples of Record Definitions has been extended with a sample record optimized for fetching performance.

The ValueObservation chapter has been updated with new APIs for building observation, and combining observations together in order to avoid data races.

The ValueObservation Error Handling chapter explains with more details how to deal with observation errors.

API Diff

Asynchronous database access methods 
 protocol DatabaseReader {
+    var configuration: Configuration { get }
+
+    #if compiler(>=5.0)
+    func asyncRead(_ block: @escaping (Result<Database, Error>) -> Void)
+    #endif
 }
 
 protocol DatabaseWriter {
+    func asyncWriteWithoutTransaction(_ updates: @escaping (Database) -> Void)
+
+    #if compiler(>=5.0)
+    func asyncWrite<T>(_ updates: @escaping (Database) throws -> T, completion: @escaping (Database, Result<T, Error>) -> Void)
+    #endif
 }
ValueObservation changes 
+extension FetchRequest {
+    func observationForCount() -> ValueObservation<...>
+}
+extension FetchRequest where RowDecoder: ... {
+    func observationForAll() -> ValueObservation<...>
+    func observationForFirst() -> ValueObservation<...>
+)
+extension TableRecord {
+    static func observationForCount() -> ValueObservation<...>
+    static func observationForAll() -> ValueObservation<...>
+    static func observationForFirst() -> ValueObservation<...>
+}
 extension ValueObservation where ... {
+    @available(*, deprecated)
     static func trackingCount<Request: FetchRequest>(_ request: Request) -> ValueObservation<...>
+    @available(*, deprecated)
     static func trackingAll<Request: FetchRequest>(_ request: Request) -> ValueObservation<...>
+    @available(*, deprecated)
     static func trackingOne<Request: FetchRequest>(_ request: Request) -> ValueObservation<...>
 }
 extension ValueObservation where Reducer: ValueReducer {
-    func start(in reader: DatabaseReader, onError: ((Error) -> Void)? = nil, onChange: @escaping (Reducer.Value) -> Void) throws -> TransactionObserver
+    func start(in reader: DatabaseReader, onChange: @escaping (Reducer.Value) -> Void) throws -> TransactionObserver
+    func start(in reader: DatabaseReader, onError: @escaping (Error) -> Void, onChange: @escaping (Reducer.Value) -> Void) -> TransactionObserver
+    func combine<..., Combined>(..., transform: @escaping (...) -> Combined) -> ValueObservation<...>
 }
 extension ValueObservation where Reducer: ValueReducer, Reducer.Value: Equatable {
+    @available(*, deprecated)
     func distinctUntilChanged() -> ValueObservation<...>
+    func removeDuplicates() -> ValueObservation<...>
 }
Joining methods on both requests and associations 
+protocol JoinableRequest {
+    associatedtype RowDecoder
+}
+
+extension JoinableRequest {
+    func including<A: AssociationToMany>(all association: A) -> Self where A.OriginRowDecoder == RowDecoder
+    func including<A: Association>(optional association: A) -> Self where A.OriginRowDecoder == RowDecoder
+    func including<A: Association>(required association: A) -> Self where A.OriginRowDecoder == RowDecoder
+    func joining<A: Association>(optional association: A) -> Self where A.OriginRowDecoder == RowDecoder
+    func joining<A: Association>(required association: A) -> Self where A.OriginRowDecoder == RowDecoder
+}

-protocol DerivableRequest: SelectionRequest, FilteredRequest, OrderedRequest { }
+protocol DerivableRequest: SelectionRequest, FilteredRequest, OrderedRequest, JoinableRequest { }
FetchRequest changes 
+struct PreparedRequest {
+    var statement: SelectStatement
+    var adapter: RowAdapter?
+    init(statement: SelectStatement, adapter: RowAdapter? = nil)
+}

 protocol FetchRequest {
+    // deprecated
     func prepare(_ db: Database, forSingleResult singleResult: Bool) throws -> (SelectStatement, RowAdapter?)
+    func makePreparedRequest(_ db: Database, forSingleResult singleResult: Bool) throws -> PreparedRequest
 }

The core FetchRequest preparation method is now makePreparedRequest(_:forSingleResult:). The former core method prepare(_:forSingleResult:) will remain a requirement of the FetchRequest protocol until GRDB 5 due to semantic versioning constraints. Both methods are provided with a default implementation which makes each one depend on the other: this creates an infinite loop unless you provide at least one of them. If you have a choice, implement only makePreparedRequest(_:forSingleResult:).

4.0.1

Released May 25, 2019 • diff

  • #533: Fix eager loading of HasManyThrough associations
  • #534: Support for CocoaPods 1.7.0
  • #535: Update the Good Practices for Designing Record Types

Documentation Diff

The Good Practices for Designing Record Types have been enhanced and completed with a whole new section about "database managers".

4.0.0

Released May 23, 2019 • diff

GRDB 4 is a release focused on Swift 5, and enhancements on associations between record types.

It comes with new features, but also a few breaking changes. The GRDB 4 Migration Guide will help you upgrading your applications.

New

  • #478: Swift 5: SQL interpolation
  • #484: SE-0193 Cross-module inlining and specialization
  • #486: Refactor PersistenceError.recordNotFound
  • #488: ValueObservation Cleanup
  • #490: Indirect Associations
  • #493: Bump SQLite to 3.27.2
  • #499: Extract EncodableRecord from MutablePersistableRecord
  • #502: Rename Future to DatabaseFuture
  • #503: IFNULL support for association aggregates
  • #508 by @michaelkirk-signal: Allow Database Connection Configuration
  • #510 by @charlesmchen-signal: Expose DatabaseRegion(table:) initializer
  • #515 by @alextrob: Add "LIMIT 1" to fetchOne requests
  • #517: Support for SQLCipher 4
  • #525: Eager Loading of HasMany associations

Fixed

Breaking Changes

  • Swift 4.0 and Swift 4.1 are no longer supported. Minimum Swift version is now Swift 4.2.
  • iOS 8 is no longer supported. Minimum deployment target is now iOS 9.0.
  • Deprecated APIs are no longer available.
  • See the Migration Guide and the API diff below for other changes.

Documentation Diff

API diff

Associations: indirect associations and eager loading of HasMany associations

New AssociationToOne and AssociationToMany protocols

+protocol AssociationToOne: Association { }
+protocol AssociationToMany: Association { }
+extension AssociationToMany {
+    var count: AssociationAggregate<OriginRowDecoder> { get }
+    var isEmpty: AssociationAggregate<OriginRowDecoder> { get }
+    func average(_ expression: SQLExpressible) -> AssociationAggregate<OriginRowDecoder>
+    func max(_ expression: SQLExpressible) -> AssociationAggregate<OriginRowDecoder>
+    func min(_ expression: SQLExpressible) -> AssociationAggregate<OriginRowDecoder>
+    func sum(_ expression: SQLExpressible) -> AssociationAggregate<OriginRowDecoder>
+}

+extension BelongsToAssociation: AssociationToOne { }
+extension HasManyAssociation: AssociationToMany { }
+extension HasOneAssociation: AssociationToOne { }

New HasManyThroughAssociation and HasOneThroughAssociation

+struct HasManyThroughAssociation<Origin, Destination>: AssociationToMany { }
+extension HasManyThroughAssociation: TableRequest where Destination: TableRecord { }
+struct HasOneThroughAssociation<Origin, Destination>: AssociationToOne { }
+extension HasOneThroughAssociation: TableRequest where Destination: TableRecord { }
 
 extension TableRecord {
+    static func hasMany<Pivot, Target>(_ destination: Target.RowDecoder.Type, through pivot: Pivot, using target: Target, key: String? = nil) -> HasManyThroughAssociation<Self, Target.RowDecoder> where Pivot: Association, Target: Association, Pivot.OriginRowDecoder == Self, Pivot.RowDecoder == Target.OriginRowDecoder
+    static func hasOne<Pivot, Target>(_ destination: Target.RowDecoder.Type, through pivot: Pivot, using target: Target, key: String? = nil) -> HasOneThroughAssociation<Self, Target.RowDecoder> where Pivot: AssociationToOne, Target: AssociationToOne, Pivot.OriginRowDecoder == Self, Pivot.RowDecoder == Target.OriginRowDecoder
 }

Eager loading of HasMany associations

 extension TableRecord {
+    static func including<A: AssociationToMany>(all association: A) -> QueryInterfaceRequest<Self> where A.OriginRowDecoder == Self
 }
 
 extension Association {
+    func including<A: AssociationToMany>(all association: A) -> Self where A.OriginRowDecoder == RowDecoder
 }
 
 extension QueryInterfaceRequest {
+    func including<A: AssociationToMany>(all association: A) -> QueryInterfaceRequest where A.OriginRowDecoder == RowDecoder
 }

Accessing eager loaded rows

 class Row {
+    var prefetchedRows: Row.PrefetchedRowsView { get }
+    subscript<Collection>(_ key: String) -> Collection where Collection: RangeReplaceableCollection, Collection.Element: FetchableRecord { get }
+    subscript<Record: FetchableRecord & Hashable>(_ key: String) -> Set<Record> { get }
 }

 extension Row {
+    struct PrefetchedRowsView: Equatable {
+       var isEmpty: Bool { get }
+       var keys: Set<String> { get }
+       subscript(_ key: String) -> [Row]? { get }
+    }
 }
SQL Interpolation 
+extension SQLRequest: ExpressibleByStringInterpolation {
+    init(stringInterpolation sqlInterpolation: SQLInterpolation)
+}
 
+struct SQLLiteral: ExpressibleByStringInterpolation {
+    var sql: String { get }
+    var arguments: StatementArguments { get }
+    init(stringInterpolation sqlInterpolation: SQLInterpolation)
+    init(sql: String, arguments: StatementArguments = StatementArguments())
+    func mapSQL(_ transform: (String) throws -> String) rethrows -> SQLLiteral
+    mutating func append(sql: String, arguments: StatementArguments = StatementArguments())
+    mutating func append(literal sqlLiteral: SQLLiteral)
+    static func + (lhs: SQLLiteral, rhs: SQLLiteral) -> SQLLiteral
+    static func += (lhs: inout SQLLiteral, rhs: SQLLiteral)
+}

+extension Sequence where Element == SQLLiteral {
+    func joined(separator: String = "") -> SQLLiteral
+}

+struct SQLInterpolation: StringInterpolationProtocol {
+    mutating func appendLiteral(_ sql: String)
+    mutating func appendInterpolation(sql: String, arguments: StatementArguments = StatementArguments())
+    mutating func appendInterpolation(literal sqlLiteral: SQLLiteral)
+    mutating func appendInterpolation<T: TableRecord>(_ table: T.Type)
+    mutating func appendInterpolation<T: TableRecord>(tableOf record: T)
+    mutating func appendInterpolation(_ selection: SQLSelectable)
+    mutating func appendInterpolation<T: SQLExpressible>(_ expressible: T?)
+    mutating func appendInterpolation(_ codingKey: CodingKey)
+    mutating func appendInterpolation<S>(_ sequence: S) where S: Sequence, S.Element: SQLExpressible
+    mutating func appendInterpolation(_ ordering: SQLOrderingTerm)
+    mutating func appendInterpolation<T>(_ request: SQLRequest<T>)
+}
Raw SQL breaking changes 
 class Database {
-    func makeSelectStatement(_ sql: String) throws -> SelectStatement
-    func makeUpdateStatement(_ sql: String) throws -> UpdateStatement
+    func makeSelectStatement(sql: String) throws -> SelectStatement
+    func makeUpdateStatement(sql: String) throws -> UpdateStatement

-    func cachedSelectStatement(_ sql: String) throws -> SelectStatement
-    func cachedUpdateStatement(_ sql: String) throws -> UpdateStatement
+    func cachedSelectStatement(sql: String) throws -> SelectStatement
+    func cachedUpdateStatement(sql: String) throws -> UpdateStatement

-    func execute(_ sql: String, arguments: StatementArguments? = nil) throws
+    func execute(sql: String, arguments: StatementArguments = StatementArguments()) throws
 }
 
 class Row {
-    static func fetchCursor(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> RowCursor
-    static func fetchAll(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> [Row]
-    static func fetchOne(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> Row?
+    static func fetchCursor(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> RowCursor
+    static func fetchAll(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> [Row]
+    static func fetchOne(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> Row?
 }
 
 extension FetchableRecord {
-    static func fetchCursor(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> RecordCursor<Self>
-    static func fetchAll(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> [Self]
-    static func fetchOne(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> Self?
+    static func fetchCursor(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> RecordCursor<Self>
+    static func fetchAll(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> [Self]
+    static func fetchOne(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> Self?
 }

 extension DatabaseValueConvertible {
-    static func fetchCursor(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> DatabaseValueCursor<Self>
-    static func fetchAll(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> [Self]
-    static func fetchOne(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> Self?
+    static func fetchCursor(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> DatabaseValueCursor<Self>
+    static func fetchAll(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> [Self]
+    static func fetchOne(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> Self?
 }
 
 extension Optional where Wrapped: DatabaseValueConvertible {
-    static func fetchCursor(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> NullableDatabaseValueCursor<Wrapped>
-    static func fetchAll(_ db: Database, _ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws -> [Wrapped?]
+    static func fetchCursor(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> NullableDatabaseValueCursor<Wrapped>
+    static func fetchAll(_ db: Database, sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws -> [Wrapped?]
 }
 
 extension TableRecord {
-    static func select(sql: String, arguments: StatementArguments? = nil) -> QueryInterfaceRequest<Self>
+    static func select(sql: String, arguments: StatementArguments = StatementArguments()) -> QueryInterfaceRequest<Self>
+    static func select(literal sqlLiteral: SQLLiteral) -> QueryInterfaceRequest<Self>
-    static func select<RowDecoder>(sql: String, arguments: StatementArguments? = nil, as type: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder>
+    static func select<RowDecoder>(sql: String, arguments: StatementArguments = StatementArguments(), as type: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder>
+    static func select<RowDecoder>(literal sqlLiteral: SQLLiteral, as type: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder>
-    static func filter(sql: String, arguments: StatementArguments? = nil) -> QueryInterfaceRequest<Self>
+    static func filter(sql: String, arguments: StatementArguments = StatementArguments()) -> QueryInterfaceRequest<Self>
+    static func filter(literal sqlLiteral: SQLLiteral) -> QueryInterfaceRequest<Self>
-    static func order(sql: String, arguments: StatementArguments? = nil) -> QueryInterfaceRequest<Self>
+    static func order(sql: String, arguments: StatementArguments = StatementArguments()) -> QueryInterfaceRequest<Self>
+    static func order(literal sqlLiteral: SQLLiteral) -> QueryInterfaceRequest<Self>
 }
 
 final class FetchedRecordsController<Record: FetchableRecord> {
-    func setRequest(sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil) throws
+    func setRequest(sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil) throws
 }

 extension SelectionRequest {
-    func select(sql: String, arguments: StatementArguments? = nil) -> Self
+    func select(sql: String, arguments: StatementArguments = StatementArguments()) -> Self
+    func select(literal sqlLiteral: SQLLiteral) -> Self
 }
 
 extension FilteredRequest {
-    func filter(sql: String, arguments: StatementArguments? = nil) -> Self
+    func filter(sql: String, arguments: StatementArguments = StatementArguments()) -> Self
+    func filter(literal sqlLiteral: SQLLiteral) -> Self
 }
 
 extension AggregatingRequest {
-    func group(sql: String, arguments: StatementArguments? = nil) -> Self
+    func group(sql: String, arguments: StatementArguments = StatementArguments()) -> Self
+    func group(literal sqlLiteral: SQLLiteral) -> Self
-    func having(sql: String, arguments: StatementArguments? = nil) -> Self
+    func having(sql: String, arguments: StatementArguments = StatementArguments()) -> Self
+    func having(literal sqlLiteral: SQLLiteral) -> Self
 }
 
 extension OrderedRequest {
-    func order(sql: String, arguments: StatementArguments? = nil) -> Self
+    func order(sql: String, arguments: StatementArguments = StatementArguments()) -> Self
+    func order(literal sqlLiteral: SQLLiteral) -> Self
 }

 struct SQLRequest<T> : FetchRequest {
-    init(_ sql: String, arguments: StatementArguments? = nil, adapter: RowAdapter? = nil, cached: Bool = false)
+    init(sql: String, arguments: StatementArguments = StatementArguments(), adapter: RowAdapter? = nil, cached: Bool = false)
+    init(literal sqlLiteral: SQLLiteral, adapter: RowAdapter? = nil, cached: Bool = false)
 }

 struct SQLExpressionLiteral {
-    init(_ sql: String, arguments: StatementArguments? = nil)
+    init(sql: String, arguments: StatementArguments = StatementArguments())
+    init(literal sqlLiteral: SQLLiteral)
 }
EncodableRecord 
+protocol EncodableRecord {
+    func encode(to container: inout PersistenceContainer)
+    static var databaseEncodingUserInfo: [CodingUserInfoKey: Any] { get }
+    static func databaseJSONEncoder(for column: String) -> JSONEncoder
+    static var databaseDateEncodingStrategy: DatabaseDateEncodingStrategy { get }
+    static var databaseUUIDEncodingStrategy: DatabaseUUIDEncodingStrategy { get }
+}
+
+extension EncodableRecord where Self: Encodable {
+    func encode(to container: inout PersistenceContainer)
+}
+
+extension EncodableRecord {
+    var databaseDictionary: [String: DatabaseValue] { get }
+    func databaseEquals(_ record: Self) -> Bool
+    func databaseChanges<Record: EncodableRecord>(from record: Record) -> [String: DatabaseValue]
+}

-protocol MutablePersistableRecord: TableRecord { }
+protocol MutablePersistableRecord: EncodableRecord, TableRecord { }
ValueObservation breaking changes 
 enum ValueScheduling {
-    case onQueue(DispatchQueue, startImmediately: Bool)
+    case async(onQueue: DispatchQueue, startImmediately: Bool)
 }
 
 struct ValueObservation<Reducer> {
-    var extent: Database.TransactionObservationExtent
-    static func tracking(_ regions: DatabaseRegionConvertible..., reducer: Reducer) -> ValueObservation
-    static func tracking<Value>(_ regions: DatabaseRegionConvertible..., fetchDistinct fetch: @escaping (Database) throws -> Value) -> ValueObservation<DistinctUntilChangedValueReducer<RawValueReducer<Value>>> where Value: Equatable
 }
Customizing pluralization and singularization 
+struct Inflections {
+    init()
+    func pluralize(_ string: String) -> String
+    func singularize(_ string: String) -> String

     // Configuration
+    mutating func plural(_ pattern: String, options: NSRegularExpression.Options = [.caseInsensitive], _ template: String)
+    mutating func singular(_ pattern: String, options: NSRegularExpression.Options = [.caseInsensitive], _ template: String)
+    mutating func uncountableWords(_ words: [String])
+    mutating func irregularSuffix(_ singular: String, _ plural: String)
+}
+
+extension Inflections {
+   static var `default`: Inflections { get set }
+}
Full Text Search breaking changes: support for SQLite 3.27 
 struct FTS3 {
+    enum Diacritics {
+        case keep
+        case removeLegacy
+        #if GRDBCUSTOMSQLITE
+        case remove
+        #endif
+    }
 }
 
 struct FTS3TokenizerDescriptor {
-    static func unicode61(removeDiacritics: Bool = true, separators: Set<Character> = [], tokenCharacters: Set<Character> = []) -> FTS3TokenizerDescriptor
+    static func unicode61(diacritics: FTS3.Diacritics = .removeLegacy, separators: Set<Character> = [], tokenCharacters: Set<Character> = []) -> FTS3TokenizerDescriptor
 }
 
 struct FTS5 {
+    enum Diacritics {
+        case keep
+        case removeLegacy
+        #if GRDBCUSTOMSQLITE
+        case remove
+        #endif
+    }
 }
 
 struct FTS5TokenizerDescriptor {
-    static func unicode61(removeDiacritics: Bool = true, separators: Set<Character> = [], tokenCharacters: Set<Character> = []) -> FTS5TokenizerDescriptor
+    static func unicode61(diacritics: FTS5.Diacritics = .removeLegacy, separators: Set<Character> = [], tokenCharacters: Set<Character> = []) -> FTS5TokenizerDescriptor
 }
SQLCipher breaking changes 
 struct Configuration {
-    var cipherPageSize: Int
-    var kdfIterations: Int
 }
Miscellaneous additions

Column initializer from CodingKey

 struct Column {
+    init(_ codingKey: CodingKey)
 }

Association aggregates: support for the IFNULL sql operator

+func ?? <RowDecoder>(lhs: AssociationAggregate<RowDecoder>, rhs: SQLExpressible) -> AssociationAggregate<RowDecoder>

Remove all orderings from a request

 protocol OrderedRequest {
+    func unordered()
 }

Annotate requests with any value, not only association aggregates

 protocol SelectionRequest {
+    annotated(with selection: [SQLSelectable]) -> Self
 }
 
 extension SelectionRequest {
+    func annotated(with selection: SQLSelectable...) -> Self
 }
 
 extension TableRecord {
+    static func annotated(with selection: [SQLSelectable]) -> QueryInterfaceRequest<Self>
+    static func annotated(with selection: SQLSelectable...) -> QueryInterfaceRequest<Self>
 }

Build a DatabaseRegion from a table name

 struct DatabaseRegion {
+    init(table: String)
 }
Miscellaneous breaking changes 
 enum PersistenceError: Error {
-    case recordNotFound(MutablePersistableRecord)
+    case recordNotFound(databaseTableName: String, key: [String: DatabaseValue])
 }

- class Future<Value> { }
+ class DatabaseFuture<Value> { }

 protocol FetchRequest {
-    func prepare(_ db: Database) throws -> (SelectStatement, RowAdapter?)
+    func prepare(_ db: Database, forSingleResult singleResult: Bool) throws -> (SelectStatement, RowAdapter?)
 }
 
 struct AnyFetchRequest<T> : FetchRequest {
-    init(_ prepare: @escaping (Database) throws -> (SelectStatement, RowAdapter?))
+    init(_ prepare: @escaping (Database, _ singleResult: Bool) throws -> (SelectStatement, RowAdapter?))
 }
 
-final class StatementCursor: Cursor { }

Discarded deprecated methods

 extension Cursor {
-    func flatMap<ElementOfResult>(_ transform: @escaping (Element) throws -> ElementOfResult?) -> MapCursor<FilterCursor<MapCursor<Self, ElementOfResult?>>, ElementOfResult>
 }
 
 struct DatabaseValue {
-    func losslessConvert<T>(sql: String? = nil, arguments: StatementArguments? = nil) -> T where T : DatabaseValueConvertible
-    func losslessConvert<T>(sql: String? = nil, arguments: StatementArguments? = nil) -> T? where T : DatabaseValueConvertible
 }
 
 protocol DatabaseWriter {
-    func readFromCurrentState(_ block: @escaping (Database) -> Void) throws
 }

3.7.0

Released March 9, 2019 • diff

Fixed

  • #496: Fix crash when trying to perform fetchCount or ValueObservation.trackCount on joined query

New

  • #494 by @davidkraus: Document how to enable FTS5 with GRDB.swift CocoaPod
  • #497 by @Marus: Add additional SQLCipher configuration options

Documentation Diff

3.6.2

Released January 5, 2019 • diff

Fixed

  • #464: Make updateChanges(_:with:) available to PersistableRecord structs

3.6.1

Released December 9, 2018 • diff

Fixed

  • #458: Fix ValueObservation duration - code & doc

3.6.0

Released December 7, 2018 • diff

This release comes with:

  • A nice sugar for updating records (my personal favorite of this release):

    // Does not hit the database if player is not modified
try player.update(db) {
    \$0.score = 1000
    \$0.hasAward = true
}

  • Enhanced ValueObservation, with methods such as compactMap, combine, ...

  • Observation of specific transactions, with the new DatabaseRegionObservation.

  • Various other improvements listed below.

Fixed

  • #449: Fix JSON encoding of empty containers

New

  • #442: Reindex
  • #443: In place record update
  • #445: Quality of service and target dispatch queue
  • #446: ValueObservation: delayed reducer creation
  • #444: Combine Value Observations
  • #451: ValueObservation.compactMap
  • #452: ValueObservation.mapReducer
  • #454: ValueObservation.distinctUntilChanged
  • #455: DatabaseRegionObservation
  • ValueObservation methods which used to accept a variadic list of observed regions now also accept an array.
  • ValueReducer, the protocol that fuels ValueObservation, is flagged :fire: EXPERIMENTAL. It will remain so until more experience has been acquired.

Documentation Diff

  • Record Comparison: this chapter has been updated for the new updateChanges(_:with:) method.
  • ValueObservation: this chapter has been updated for the new ValueObservation.combine, ValueObservation.compactMap, and Value.distinctUntilChanged methods.
  • DatabaseRegionObservation: this chapter describes the new DatabaseRegionObservation type.

API diff

 extension Database {
+    func reindex(collation: Database.CollationName) throws
+    func reindex(collation: DatabaseCollation) throws
 }
 
 extension MutablePersistableRecord {
+    mutating func updateChanges(_ db: Database, with change: (inout Self) throws -> Void) throws -> Bool
 }

 extension PersistableRecord {
+    func updateChanges(_ db: Database, with change: (Self) throws -> Void) throws -> Bool
 }

 struct ValueObservation<Reducer> {
+    static func tracking(
+        _ regions: [DatabaseRegionConvertible],
+        reducer: @escaping (Database) throws -> Reducer)
+        -> ValueObservation
 }
 
+extension ValueObservation where Reducer == Void {
+    static func tracking<Value>(
+        _ regions: [DatabaseRegionConvertible],
+        fetch: @escaping (Database) throws -> Value)
+        -> ValueObservation<ValueReducers.Raw<Value>>
+    static func combine<R1: ValueReducer, ...>(_ o1: ValueObservation<R1>, ...)
+        -> ValueObservation<...>
+}
 
+extension ValueObservation where Reducer: ValueReducer {
+    func compactMap<T>(_ transform: @escaping (Reducer.Value) -> T?)
+        -> ValueObservation<CompactMapValueReducer<Reducer, T>>
+}

+ extension ValueObservation where Reducer: ValueReducer, Reducer.Value: Equatable {
+     public func distinctUntilChanged()
+         -> ValueObservation<DistinctUntilChangedValueReducer<Reducer>>
+ }

+extension ValueObservation {
+    func mapReducer<R>(_ transform: @escaping (Database, Reducer) throws -> R)
+        -> ValueObservation<R>
+}
 
 struct Configuration {
+    var qos: DispatchQoS
+    var targetQueue: DispatchQueue?
 }
 
+struct DatabaseRegionObservation {
+    var extent: Database.TransactionObservationExtent
+    init(tracking regions: DatabaseRegionConvertible...)
+    init(tracking regions: [DatabaseRegionConvertible])
+    func start(in dbWriter: DatabaseWriter, onChange: @escaping (Database) -> Void) throws -> TransactionObserver
+}

3.5.0

Released November 2, 2018 • diff

This release comes with ValueObservation, a new type which tracks the results of database requests, and notifies fresh values whenever the database changes:

let observer = ValueObversation
    .trackingOne(Player.filter(key: 42))
    .start(in: dbQueue) { player: Player? in
        print("Player has changed")
    }

ValueObservation also aims at providing support for third-party code that needs to react to database changes. For example, RxSwiftCommunity/RxGRDB#46 is the pull request which implements RxGRDB, the companion library based on RxSwift, on top of ValueObservation.

New

  • #435: Improved support for values observation
  • It is now possible to observe database change from a DatabaseReader.

Breaking Change

It used to be possible to define custom types that adopt the DatabaseReader and DatabaseWriter protocols, with a major drawback: it was impossible to add concurrency-related APIs to GRDB without breaking user code. Now all types that adopt those protocols are defined by GRDB: DatabaseQueue, DatabasePool, DatabaseSnapshot, AnyDatabaseReader, and AnyDatabaseWriter. Expanding this set is no longer supported.

Documentation Diff

  • ValueObservation: this new chapter describes the new way to observe database values.

API diff

 protocol DatabaseReader: class {
+    func add<Reducer: ValueReducer>(
+        observation: ValueObservation<Reducer>,
+        onError: ((Error) -> Void)?,
+        onChange: @escaping (Reducer.Value) -> Void)
+        throws -> TransactionObserver
+    func remove(transactionObserver: TransactionObserver)
 }
 
 protocol DatabaseWriter: DatabaseReader {
-    func remove(transactionObserver: TransactionObserver)
 }

+protocol DatabaseRegionConvertible {
+    func databaseRegion(_ db: Database) throws -> DatabaseRegion
+}
+
+extension DatabaseRegion: DatabaseRegionConvertible { }
+
+struct AnyDatabaseRegionConvertible: DatabaseRegionConvertible {
+    init(_ region: @escaping (Database) throws -> DatabaseRegion)
+    init(_ region: DatabaseRegionConvertible)
+}

-protocol FetchRequest { ... }
+protocol FetchRequest: DatabaseRegionConvertible { ... }

+enum ValueScheduling {
+    case mainQueue
+    case onQueue(DispatchQueue, startImmediately: Bool)
+    case unsafe(startImmediately: Bool)
+}

+protocol ValueReducer {
+    associatedtype Fetched
+    associatedtype Value
+    func fetch(_ db: Database) throws -> Fetched
+    mutating func value(_ fetched: Fetched) -> Value?
+}
+
+extension ValueReducer {
+    func map<T>(_ transform: @escaping (Value) -> T?) -> MapValueReducer<Self, T>
+}
+
+struct AnyValueReducer<Fetched, Value>: ValueReducer {
+    init(fetch: @escaping (Database) throws -> Fetched, value: @escaping (Fetched) -> Value?)
+    init<Reducer: ValueReducer>(_ reducer: Reducer) where Reducer.Fetched == Fetched, Reducer.Value == Value
+}

+struct ValueObservation<Reducer> {
+    var extent: Database.TransactionObservationExtent
+    var requiresWriteAccess: Bool
+    var scheduling: ValueScheduling
+    static func tracking(_ regions: DatabaseRegionConvertible..., reducer: Reducer) -> ValueObservation
+}
+
+extension ValueObservation where Reducer: ValueReducer {
+    func map<T>(_ transform: @escaping (Reducer.Value) -> T)
+        -> ValueObservation<MapValueReducer<Reducer, T>>
+    func start(
+        in reader: DatabaseReader,
+        onError: ((Error) -> Void)? = nil,
+        onChange: @escaping (Reducer.Value) -> Void) throws -> TransactionObserver
+}
+
+extension ValueObservation where Reducer == Void {
+    static func tracking<Value>(
+        _ regions: DatabaseRegionConvertible...,
+        fetch: @escaping (Database) throws -> Value)
+        -> ValueObservation<ValueReducers.Raw<Value>>
+
+    static func tracking<Value>(
+        _ regions: DatabaseRegionConvertible...,
+        fetchDistinct: @escaping (Database) throws -> Value)
+        -> ValueObservation<ValueReducers.Distinct<Value>>
+        where Value: Equatable
+
+    static func trackingCount<Request: FetchRequest>(_ request: Request)
+        -> ValueObservation<ValueReducers.Raw<Int>>
+    static func trackingAll<Request: FetchRequest>(_ request: Request)
+        -> ValueObservation<ValueReducers.Raw<[Request.RowDecoder]>>
+    static func trackingOne<Request: FetchRequest>(_ request: Request)
+        -> ValueObservation<ValueReducers.Raw<Request.RowDecoder?>>
+}

3.4.0

Released October 8, 2018 • diff

This release comes with Association Aggregates. They let you compute values out of collections of associated records, such as their count, or the maximum value of an associated record column.

Fixed

  • #425: Fix "destination database is in use " error during database backup
  • #427: Have cursors reset SQLite statements in deinit

New

  • #422: Refining Association Requests
  • #423: Association Aggregates
  • #428: Upgrade custom SQLite builds to version 3.25.2 (thanks to @swiftlyfalling)

Documentation Diff

API diff

 protocol AggregatingRequest {
-    func group(_ expressions: [SQLExpressible]) -> Self
+    func group(_ expressions: @escaping (Database) throws -> [SQLExpressible]) -> Self
 }

+extension AggregatingRequest {
+    func group(_ expressions: [SQLExpressible]) -> Self
+}

+extension TableRequest where Self: AggregatingRequest {
+    func groupByPrimaryKey() -> Self {
+}

+struct AssociationAggregate<RowDecoder> {
+    func aliased(_ name: String) -> AssociationAggregate<RowDecoder>
+    func aliased(_ key: CodingKey) -> AssociationAggregate<RowDecoder>
+}

+extension HasManyAssociation where Origin: TableRecord, Destination: TableRecord {
+    var count: AssociationAggregate<Origin>
+    var isEmpty: AssociationAggregate<Origin>
+    func average(_ expression: SQLExpressible) -> AssociationAggregate<Origin>
+    func max(_ expression: SQLExpressible) -> AssociationAggregate<Origin>
+    func min(_ expression: SQLExpressible) -> AssociationAggregate<Origin>
+    func sum(_ expression: SQLExpressible) -> AssociationAggregate<Origin>
+}

+extension QueryInterfaceRequest {
+    func annotated(with selection: [SQLSelectable]) -> QueryInterfaceRequest<RowDecoder>
+}

+extension QueryInterfaceRequest where RowDecoder: TableRecord {
+    func annotated(with aggregates: AssociationAggregate<RowDecoder>...) -> QueryInterfaceRequest<RowDecoder>
+    func annotated(with aggregates: [AssociationAggregate<RowDecoder>]) -> QueryInterfaceRequest<RowDecoder>
+    func having(_ aggregate: AssociationAggregate<RowDecoder>) -> QueryInterfaceRequest<RowDecoder>
+}

+extension TableRecord {
+    static func annotated(with aggregates: AssociationAggregate<Self>...) -> QueryInterfaceRequest<Self>
+    static func annotated(with aggregates: [AssociationAggregate<Self>]) -> QueryInterfaceRequest<Self>
+    static func having(_ aggregate: AssociationAggregate<Self>) -> QueryInterfaceRequest<Self>
+}

+extension SQLSpecificExpressible {
+    func aliased(_ key: CodingKey) -> SQLSelectable
+}

3.3.1

Released September 23, 2018 • diff

Fixed

  • #414: Fix database pool use of FTS5 tokenizers

Documentation Diff

3.3.0

Released September 16, 2018 • diff

New

  • #409: DatabaseWriter.concurrentRead

Documentation Diff

API diff

 protocol DatabaseWriter : DatabaseReader {
+    func concurrentRead<T>(_ block: @escaping (Database) throws -> T) -> Future<T>
+    @available(*, deprecated)
     func readFromCurrentState(_ block: @escaping (Database) -> Void) throws
 }

+class Future<Value> {
+    func wait() throws -> Value
+}

 extension Cursor {
+    func isEmpty() throws -> Bool
 }

3.3.0-beta1

Released September 5, 2018 • diff

This release focuses on enhancing the relationships between Codable records and the database, with JSON columns, customized date formats, and better diagnostics when things go wrong.

Other notable enhancements are:

  • Support for Swift 4.2 and Xcode 10 (Xcode 9.3 is still supported).
  • Support for the FTS5 full-text engine when available in the operating system (iOS 11.4+ / macOS 10.13+ / watchOS 4.3+).

Fixed

  • The write and unsafeReentrantRead DatabaseQueue methods used to have an incorrect throws/rethrows qualifier.

New

  • #397 by @gusrota and @valexa: Codable records: JSON encoding and decoding of codable record properties
  • #399: Codable records: customize the userInfo context dictionary, and the format of JSON columns
  • #403: Codable records: customize date and uuid format
  • #401: Query Interface: set the selection and the fetched type in a single method call
  • #393 by @Marus: Upgrade SQLCipher to 3.4.2, enable FTS5 on GRDBCipher and new pod GRDBPlus.
  • #384: Improve database value decoding diagnostics
  • #396: Support for Xcode 10 and Swift 4.2
  • Cursors of optimized values (Strint, Int, Date, etc.) have been renamed: FastDatabaseValueCursor and FastNullableDatabaseValueCursor replace the deprecated ColumnCursor and NullableColumnCursor.

Documentation Diff

API diff

Fixes:

 class DatabaseQueue {
-    func write<T>(_ block: (Database) throws -> T) rethrows -> T {
+    func write<T>(_ block: (Database) throws -> T) throws -> T {
-    func unsafeReentrantRead<T>(_ block: (Database) throws -> T) throws -> T {
+    func unsafeReentrantRead<T>(_ block: (Database) throws -> T) rethrows -> T {
 }

Enhancements to Codable support:

 protocol FetchableRecord {
+    static var databaseDecodingUserInfo: [CodingUserInfoKey: Any] { get }
+    static var databaseDateDecodingStrategy: DatabaseDateDecodingStrategy { get }
+    static func databaseJSONDecoder(for column: String) -> JSONDecoder
 }

 protocol MutablePersistableRecord: TableRecord {
+    static var databaseEncodingUserInfo: [CodingUserInfoKey: Any] { get }
+    static var databaseDateEncodingStrategy: DatabaseDateEncodingStrategy { get }
+    static var databaseUUIDEncodingStrategy: DatabaseUUIDEncodingStrategy { get }
+    static func databaseJSONEncoder(for column: String) -> JSONEncoder
 }

Query Interface: set the selection and the fetched type in a single method call:

 extension QueryInterfaceRequest {
+    func select<RowDecoder>(_ selection: [SQLSelectable], as type: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder>
+    func select<RowDecoder>(_ selection: SQLSelectable..., as type: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder>
+    func select<RowDecoder>(sql: String, arguments: StatementArguments? = nil, as type: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder>
 }
 
 extension TableRecord {
+    static func select<RowDecoder>(_ selection: [SQLSelectable], as type: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder>
+    static func select<RowDecoder>(_ selection: SQLSelectable..., as type: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder>
+    static func select<RowDecoder>(sql: String, arguments: StatementArguments? = nil, as type: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder>
 }

Deprecations:

+final class FastDatabaseValueCursor<Value: DatabaseValueConvertible & StatementColumnConvertible> : Cursor { }
+@available(*, deprecated, renamed: "FastDatabaseValueCursor")
+typealias ColumnCursor<Value: DatabaseValueConvertible & StatementColumnConvertible> = FastDatabaseValueCursor<Value>

+final class FastNullableDatabaseValueCursor<Value: DatabaseValueConvertible & StatementColumnConvertible> : Cursor { }
+@available(*, deprecated, renamed: "FastNullableDatabaseValueCursor")
+typealias NullableColumnCursor<Value: DatabaseValueConvertible & StatementColumnConvertible> = FastNullableDatabaseValueCursor<Value>

3.2.0

Released July 8, 2018 • diff

New

  • #381: Nuking db during development

Documentation Diff

API diff

 struct DatabaseMigrator {
+    var eraseDatabaseOnSchemaChange: Bool
 }
 
 extension DatabaseWriter {
+    func erase() throws
+    func vacuum() throws
 }

3.1.0

Released June 17, 2018 • diff

New

  • #371: Database can have a label.
  • #372: Upgrade custom SQLite builds to 3.24.0.

3.0.0

Released June 7, 2018 • diff

GRDB 3 is a release focused on modernization, safety, and associations between record types.

It comes with new features, but also a few breaking changes, and a set of updated good practices. The GRDB 2 Migration Guide will help you upgrading your applications.

New

  • Associations and Joins (#319).
  • Enhancements to logical operators (#336).
  • Foster auto-incremented primary keys (#337).
  • ColumnExpression Protocol (#340).
  • Improved parsing of dates and date components (#334 by @sobri909).
  • Common API for requests and associations derivation (#347).
  • DatabaseMigrator.appliedMigrations(in:) returns the set of applied migrations identifiers in a database (#321).
  • Database.isSQLiteInternalTable(_:) returns whether a table name is an internal SQLite table (#321).
  • Database.isGRDBInternalTable(_:) returns whether a table name is an internal GRDB table (#321).
  • Upgrade custom SQLite builds to v3.23.0 (thanks to @swiftlyfalling).
  • Improve Row descriptions (#331).
  • Request derivation protocols (#329).
  • Preliminary Linux support for the main framework (#354).
  • Automatic table name generation (#355).
  • Delayed Request Ordering (#365).

Breaking Changes

  • Swift 4.1 is now required.
  • iOS 8 sunsetting: GRDB 3 is only tested on iOS 9+, due to a limitation in Xcode 9.3. Code that targets older versions of SQLite and iOS is still there, but is not supported.
  • The Record protocols have been renamed: RowConvertible to FetchableRecord, Persistable to PersistableRecord, and TableMapping to TableRecord (#314).
  • Implicit transaction in DatabasePool.write and DatabaseQueue.write (#332).
  • Request and TypedRequest protocols have been merged into FetchRequest (#311, #328, #348).
  • Reversing unordered requests has no effect (#342).
  • The IteratorCursor type has been removed. Use AnyCursor instead (#312).
  • Row scopes collection, breadth-first scope search (#335).
  • Expressions are no longer PATs (#330).
  • Deprecated APIs have been removed.

Documentation Diff

  • Associations: Discover the major GRDB 3 feature
  • Database Queues: focus on the read and write methods.
  • Database Pools: focus on the read and write methods.
  • Transactions and Savepoints: the chapter has been rewritten in order to introduce transactions as a power-user feature.
  • ScopeAdapter: do you use row adapters? If so, have a look.
  • TableRecord Protocol: updated for the new automatic generation of database table name.
  • Examples of Record Definitions: this new chapter provides a handy reference of the three main ways to define record types (Codable, plain struct, Record subclass).
  • SQL Operators: the chapter introduces the new joined(operator:) method that lets you join a chain of expressions with AND or OR without nesting: [cond1, cond2, ...].joined(operator: .and).
  • Custom Requests: the old Request and TypedRequest protocols have been replaced with FetchRequest. If you want to know more about custom requests, check this chapter.
  • Customized Decoding of Database Rows: learn how to escape the ready-made FetchableRecord protocol when it does not fit your needs.
  • Migrations: learn how to check if a migration has been applied (very useful for migration tests).

2.10.0

Released March 30, 2018 • diff

New

  • Support for Swift 4.1 and Xcode 9.3
  • Added Cursor.compactMap (SE-0187)

Deprecated

  • Cursor.flatMap is deprecated. Use compactMap instead.

2.9.0

Released February 25, 2018 • diff

New

  • Changes tracking overhaul: changes tracking, a feature previously restricted to the Record class and its subclasses, is now available for all records. And it has a better looking API (documentation).
  • Database snapshots: Database pools can now take database snapshots. A snapshot sees an unchanging database content, as it existed at the moment the snapshot was created (documentation).
  • Improved support for joined queries: more than a set on new APIs, we provide a set of guidelines that will help you deal with your wildest joined queries. Check the new Joined Queries Support documentation chapter.
  • Database.columns(in:) returns information about the columns of a table.
  • Request.adapted(_:) is no longer experimental.
  • Configuration.allowsUnsafeTransactions lets you leave transactions opened between two database accesses (see below).
  • Support for explicit transaction management, via the new Database.beginTransaction, commit, and rollback methods.

Fixed

  • It is now a programmer error to leave a transaction opened at the end of a database access block:

    // Fatal error: A transaction has been left opened at the end of a database access
try dbQueue.inDatabase { db in
    try db.beginTransaction()
}

    One can still opt-in for the unsafe behavior by setting the new allowsUnsafeTransactions configuration flag:

    var config = Configuration()
config.allowsUnsafeTransactions = true
let dbQueue = DatabaseQueue(configuration: config)

// OK
try dbQueue.inDatabase { db in
    try db.beginTransaction()
}

Deprecated

  • Database.columnCount(in:) is deprecated. Use db.columns(in:).count instead.
  • RecordBox, introduced in 2.7.0, was ill-advised. It has been deprecated. Use changes tracking methods on the Persistable protocol instead.
  • Record.hasPersistentChangedValues has been deprecated, renamed hasDatabaseChanges.
  • Record.persistentChangedValues has been deprecated, renamed databaseChanges.

Documentation Diff

API diff

+struct ColumnInfo {
+    let name: String
+    let type: String
+    let isNotNull: Bool
+    let defaultValueSQL: String?
+    let primaryKeyIndex: Int
+}

 struct Configuration {
+    var allowsUnsafeTransactions: Bool
 }
 
 class Database {
+     @available(*, deprecated, message: "Use db.columns(in: tableName).count instead")
      func columnCount(in tableName: String) throws -> Int
+     func columns(in tableName: String) throws -> [ColumnInfo]
+     func beginTransaction(_ kind: TransactionKind? = nil) throws
+     func rollback() throws
+     func commit() throws
 }
 
 class DatabasePool {
+    func makeSnapshot() throws -> DatabaseSnapshot
 }
 
+class DatabaseSnapshot: DatabaseReader { }

 extension MutablePersistable {
+    @discardableResult
+    func updateChanges(_ db: Database, from record: MutablePersistable) throws -> Bool
+    func databaseEqual(_ record: Self) -> Bool
+    func databaseChanges(from record: MutablePersistable) -> [String: DatabaseValue]
 }
 class Record {
-    final func updateChanges(_ db: Database) throws
+    @discardableResult
+    final func updateChanges(_ db: Database) throws -> Bool
 }
 
+@available(*, deprecated, message: "Prefer changes methods defined on the MutablePersistable protocol: databaseEqual(_:), databaseChanges(from:), updateChanges(from:)")
 class RecordBox: Record { }

 class Row {
+    var unscoped: Row
+    var containsNonNullValue: Bool
+    func hasNull(atIndex index: Int) -> Bool
+    subscript<Record: RowConvertible>(_ scope: String) -> Record
+    subscript<Record: RowConvertible>(_ scope: String) -> Record?
 }

 extension TableMapping {
+    static func selectionSQL(alias: String? = nil) -> String
+    static func numberOfSelectedColumns(_ db: Database) throws -> Int
 }

+struct EmptyRowAdapter: RowAdapter { }

 struct ScopeAdapter {
+    init(base: RowAdapter, scopes: [String: RowAdapter])
 }

+func splittingRowAdapters(columnCounts: [Int]) -> [RowAdapter]

2.8.0

Released January 29, 2018 • diff

New

  • Upgrade custom SQLite builds to v3.22.0 (thanks to @swiftlyfalling).
  • The FTS5 full-text search engine has been enhanced with initial token queries, and FTS5Pattern has gained a new initializer: FTS5Pattern(matchingPrefixPhrase:)
  • The Cursor protocol is extended with more methods inspired by the standard Sequence protocol: drop(while:), dropFirst(), dropFirst(_:), dropLast(), dropLast(_:), joined(separator:), prefix(_:), max(), max(by:), min(), min(by:), prefix(while:), reduce(into:_:), suffix(_:),

2.7.0

Released January 21, 2018 • diff

New

  • The new RecordBox class brings changes tracking to any record type (documentation):

    // A regular record struct
struct Player: RowConvertible, MutablePersistable { ... }

try dbQueue.inDatabase { db in
    // Fetch a boxed player
    if let boxedPlayer = try RecordBox<Player>.fetchOne(db, key: 1) {
        // boxedPlayer.value is Player
        boxedPlayer.value.score = 300
        
        if boxedPlayer.hasPersistentChangedValues {
            print("player has been modified")
        }
        
        // Does nothing if player has not been modified:
        try boxedPlayer.updateChanges(db)
    }
}

2.6.1

Released January 19, 2018 • diff

Fixed

  • Fixed a crash that could happen when a transaction observer uses the stopObservingDatabaseChangesUntilNextTransaction() method.

2.6.0

Released January 18, 2018 • diff

New

  • Database observation has been enhanced:

    • TransactionObserver.stopObservingDatabaseChangesUntilNextTransaction() allows transaction observers to stop observing the database for the remaining extent of a transaction.
    • GRDB no longer prevents the truncate optimization when no transaction observers are interested in deleted rows.
    • FetchedRecordsController now avoids checking for changes in untracked rowIds.
    • DatabaseRegion is a new public type that helps transaction observers recognize impactful database changes. This type is not documented in the main documentation. For more information, see DatabaseRegion reference, and look at FetchedRecordsController implementation.
    • TransactionObserver protocol provides default implementations for rarely used callbacks.

  • Row adopts RandomAccessCollection

API diff

 extension TransactionObserver {
+    func stopObservingDatabaseChangesUntilNextTransaction()
+
+    // Default implementation
+    func databaseWillCommit() throws
+
+    #if SQLITE_ENABLE_PREUPDATE_HOOK
+    // Default implementation
+    func databaseWillChange(with event: DatabasePreUpdateEvent)
+    #endif
 }

+struct DatabaseRegion: Equatable {
+    var isEmpty: Bool
+
+    init()
+
+    func union(_ other: DatabaseRegion) -> DatabaseRegion
+    mutating func formUnion(_ other: DatabaseRegion)
+
+    func isModified(byEventsOfKind eventKind: DatabaseEventKind) -> Bool
+    func isModified(by event: DatabaseEvent) -> Bool
+}

 class SelectStatement {
+    var fetchedRegion: DatabaseRegion
+
+    @available(*, deprecated, renamed:"DatabaseRegion")
+    typealias SelectionInfo = DatabaseRegion
+    
+    @available(*, deprecated, renamed:"fetchedRegion")
+    var selectionInfo: DatabaseRegion
 }

 enum DatabaseEventKind {
-    func impacts(_ selectionInfo: SelectStatement.SelectionInfo) -> Bool
+    @available(*, deprecated, message: "Use DatabaseRegion.isModified(byEventsOfKind:) instead")
+    func impacts(_ region: DatabaseRegion) -> Bool
 }
 
 protocol Request {
+    // Default implementation
+    func fetchedRegion(_ db: Database) throws -> DatabaseRegion
 }
 
+extension Row: RandomAccessCollection {
+}
+extension RowIndex: Strideable {
}

2.5.0

Released January 11, 2018 • diff

Fixed

  • Transaction observers used to be notified of some database changes they were not interested into, in case of complex statements with side effects (foreign key cascades or sql triggers). This has been fixed.

New

  • The query interface has learned to build requests from any key (primary keys and unique keys) (documentation):

    // SELECT * FROM players WHERE id = 1
let request = Player.filter(key: 1)
let player = try request.fetchOne(db)    // Player?

// SELECT * FROM countries WHERE isoCode IN ('FR', 'US')
let request = Country.filter(keys: ["FR", "US"])
let countries = try request.fetchAll(db) // [Country]

// SELECT * FROM players WHERE email = 'arthur@example.com'
let request = Player.filter(key: ["email": "arthur@example.com"])
let player = try request.fetchOne(db)    // Player?

    This feature has been introduced in order to ease the use of RxGRDB:

    // New
Player.filter(key: 1).rx
    .fetchOne(in: dbQueue)
    .subscribe(onNext: { player: Player? in
        print("Player 1 has changed")
    })

API diff

 extension TableMapping {
+    static func filter<PrimaryKeyType: DatabaseValueConvertible>(key: PrimaryKeyType?) -> QueryInterfaceRequest<Self>
+    static func filter<Sequence: Swift.Sequence>(keys: Sequence) -> QueryInterfaceRequest<Self> where Sequence.Element: DatabaseValueConvertible
+    static func filter(key: [String: DatabaseValueConvertible?]?) -> QueryInterfaceRequest<Self>
+    static func filter(keys: [[String: DatabaseValueConvertible?]]) -> QueryInterfaceRequest<Self>
 }
 
 extension QueryInterfaceRequest where T: TableMapping {
+    func filter<PrimaryKeyType: DatabaseValueConvertible>(key: PrimaryKeyType?) -> QueryInterfaceRequest<T>
+    func filter<Sequence: Swift.Sequence>(keys: Sequence) -> QueryInterfaceRequest<T> where Sequence.Element: DatabaseValueConvertible
+    func filter(key: [String: DatabaseValueConvertible?]?) -> QueryInterfaceRequest<T>
+    func filter(keys: [[String: DatabaseValueConvertible?]]) -> QueryInterfaceRequest<T>
 }
 
 extension RowConvertible where Self: TableMapping {
-    static func fetchOne(_ db: Database, key: [String: DatabaseValueConvertible?]) throws -> Self?
+    static func fetchOne(_ db: Database, key: [String: DatabaseValueConvertible?]?) throws -> Self?
 }

2.4.2

Released January 6, 2018 • diff

Fixed

  • When using a database pool, the schema introspection methods could return wrong values whenever the database schema was concurrently read and modified. This has been fixed.
  • DatabasePool.readFromCurrentState no longer accepts to spawn a reader when a transaction is currently opened on the writer connection.

2.4.1

Released December 16, 2017 • diff

Fixed

  • #284: fixes a misuse of the sqlite3_config() function when configuring the global SQLite Error Log

2.4.0

Released December 3, 2017 • diff

New

  • #280: It is now possible to add an untyped column to an existing table.

    try db.alter(table: "players") { t in
    t.add(column: "score")
}

  • #281: The Database.dropFTS4SynchronizationTriggers & Database.dropFTS5SynchronizationTriggers method help cleaning up synchronized full-text table (documentation)

Breaking Change

  • #282: This version comes with a breaking change that affects users who manually embed the GRDBCipher and GRDBCustom frameworks in their projects. This change does not affect users of the GRDB framework, or users of GRDBCipher through CocoaPods. Now, instead of embedding the GRDB.xcodeproj project, you have to embed the GRDBCipher.xcodeproj or GRDBCustom.xcodeproj. Please have a look at the updated Encryption and Custom SQLite Builds documentation chapters.

2.3.1

Released November 8, 2017 • diff

Fixed

  • GRDB 2.2.0 has introduced a fix in the way transaction observers are notified of empty deferred transactions (BEGIN; COMMIT;). That fix was incomplete, and inconsistent.

    Now all transactions are notified, without any exception, including:

    try db.execute("BEGIN; COMMIT;")
try db.execute("SAVEPOINT foo; RELEASE SAVEPOINT foo;")

    Rationale

2.3.0

Released November 5, 2017 • diff

New

2.2.0

Released October 31, 2017 • diff

New

  • Database.viewExists(_:) returns whether a view exists in the database.
  • Database.triggerExists(_:) returns whether a trigger exists in the database.

Fixed

  • DROP VIEW statements would not drop views (#267)

  • GRDB used to incorrectly send incomplete transaction notifications to transaction observers in the case of empty deferred transactions. This is no longer the case. Since empty deferred transactions have SQLite consider that no transaction started at all, they are no longer notified to transaction observers:

    -- Nothing happens, and thus no notification is sent
BEGIN TRANSACTION
COMMIT

    Those empty deferred transactions still count for the afterNextTransactionCommit database method, and the .nextTransaction observation extent.

2.1.0

Released October 24, 2017 • diff

New

  • GRDBCipher can now build from command line (groue/sqlcipher/pull/1 by Darren Clark)

  • Upgrade custom SQLite builds to v3.20.1 (thanks to @swiftlyfalling).

  • The new method Request.asSQLRequest allows to inspect the sql and arguments of any request:

    let request = Player.all()
let sql = try request.asSQLRequest(db).sql
print(sql) // Prints "SELECT * FROM players"

  • StatementArguments adopts Equatable

Fixed

  • DROP TABLE statements would not drop temporary tables.

Documentation Diff

API diff

 extension Request {
+    func asSQLRequest(_ db: Database, cached: Bool = false) throws -> SQLRequest
}
struct SQLRequest {
+    let sql: String
+    let arguments: StatementArguments?
+    let adapter: RowAdapter?
 }

2.0.3

Released October 9, 2017 • diff

Fixed: Record types that conform to Encodable now encode their null columns.

2.0.2

Released October 5, 2017 • diff

Fixed: DROP TABLE statements would not drop tables when run through a prepared statement.

2.0.1

Released September 17, 2017 • diff

Fixed: restored support for Swift Package Manager

2.0.0

Released September 16, 2017 • diff

GRDB 2.0 brings support for Swift 4. Notable changes are:

  • Use subscript notation when extracting row values (documentation):

    let name: String = row[0]              // 0 is the leftmost column
let name: String = row["name"]         // Leftmost matching column - lookup is case-insensitive
let name: String = row[Column("name")] // Using query interface's Column

  • Support for the Codable protocol (documentation)

    Record types that adopt the standard Codable protocol are granted with automatic adoption of GRDB record protocols. This means that you no longer have to write boilerplate code :tada::

    struct Player : RowConvertible, Persistable, Codable {
    static let databaseTableName = "players"
    let name: String
    let score: Int
}

// Automatically derived:
//
// extension Player {
//     init(row: Row) {
//         name = row["name"]
//         score = row["score"]
//     }
//     
//     func encode(to container: inout PersistenceContainer) {
//         container["name"] = name
//         container["score"] = score
//     }
// }

try dbQueue.inDatabase { db in
    let arthur = Player(name: "Arthur", score: 100)
    try arthur.insert(db)
    let players = try Player.fetchAll(db) // [Players]
}

  • Records can now specify the columns they feed from (documentation).

    In previous versions of GRDB, SELECT * was the norm. GRDB 2.0 introduces databaseSelection, which allows any type to define its preferred set of columns:

    struct Player : RowConvertible, TableMapping {
    let id: Int64
    let name: String
    
    enum Columns {
        static let id = Column("id")
        static let name = Column("name")
    }
    
    init(row: Row) {
        id = row[Columns.id]
        name = row[Columns.name]
    }
    
    static let databaseTableName = "players"
    static let databaseSelection: [SQLSelectable] = [Columns.id, Columns.name]
}

// SELECT id, name FROM players
let players = Player.fetchAll(db)

  • Record protocols have more precise semantics: RowConvertible reads database rows, TableMapping builds SQL requests, and Persistable writes (documentation).

    This means that with GRDB 2.0, being able to write Player.fetchAll(db) does not imply that Player.deleteAll(db) is available: you have a better control on the abilities of your record types.

Fixed

  • GRDB is now able to store and load zero-length blobs.

New

New features have been added in order to plug a few holes and support the RxGRDB and GRDBObjc companion projects:

  • Persistable records can export themselves as dictionaries:

    let player = try Player.fetchOne(db, key: 1)
let dict = player.databaseDictionary // [String: DatabaseValue]
print(dict)
// Prints {"id": 1, "name": "Arthur", "score": 1000}

  • Query interface requests learned how to limit the number of deleted rows:

    // Delete the last ten players:
// DELETE FROM players ORDER BY score LIMIT 10
let request = Player.order(scoreColumn).limit(10)
try request.deleteAll(db)

  • Prepared statements know the index of their columns:

    let statement = try db.makeSelectStatement("SELECT a, b FROM t")
statement.index(ofColumn: "b")  // 1

  • Row cursors (of type RowCursor) expose their underlying statement:

    let rows = try Row.fetchCursor(db, "SELECT ...")
let statement = rows.statement

  • One can build a Set from a cursor:

    let strings = try Set(String.fetchCursor(...))

  • The new AnyDatabaseReader and AnyDatabaseWriter type erasers help dealing with the DatabaseReader and DatabaseWriter protocols.

Breaking Changes

  • Requirements have changed: Xcode 9+ / Swift 4

  • WatchOS extension targets no longer need libsqlite3.tbd to be added to the Linked Frameworks and Libraries section of their General tab.

  • The Row.value method has been replaced with subscript notation:

    -row.value(atIndex: 0)
-row.value(named: "id")
-row.value(Column("id"))
+row[0]
+row["id"]
+row[Column("id")]

  • Date and NSDate now interpret numerical database values as timestamps that fuel Date(timeIntervalSince1970:). Previous version of GRDB would interpret numbers as julian days (a date representation supported by SQLite). Support for julian days remains, with the Date(julianDay:) initializer.

  • All TableMapping methods that would modify the database have moved to MutablePersistable, now the only record protocol that is able to write.

  • The TableMapping.selectsRowID property has been replaced with TableMapping.databaseSelection.

    To upgrade, replace:

     struct Player: TableMapping {
-    static let selectsRowID = true
+    static let databaseSelection: [SQLSelectable] = [AllColumns(), Column.rowID]
 }

  • The DatabaseCursor type has been removed, and replaced with several concrete types that all adopt the Cursor protocol. Those new types allow dedicated optimizations depending on the type of the fetched elements.

    If your application has code that depends on DatabaseCursor, make it target the new concrete types, or make it generic on the Cursor protocol, just like you'd write generic methods on the Swift Sequence protocol.

  • RowConvertible.fetchCursor(_:keys:) returns a non-optional cursor.

  • Database.primaryKey(_:) returns a non-optional PrimaryKeyInfo. When a table has no explicit primary key, the result is the hidden rowid column.

  • The deprecated TableMapping.primaryKeyRowComparator method has been removed.

Documentation Diff

API diff

 class Row {
-    func value(atIndex index: Int) -> DatabaseValueConvertible?
-    func value<Value: DatabaseValueConvertible>(atIndex index: Int) -> Value?
-    func value<Value: DatabaseValueConvertible>(atIndex index: Int) -> Value
-    func value(named columnName: String) -> DatabaseValueConvertible?
-    func value<Value: DatabaseValueConvertible>(named columnName: String) -> Value?
-    func value<Value: DatabaseValueConvertible>(named columnName: String) -> Value
-    func value(_ column: Column) -> DatabaseValueConvertible?
-    func value<Value: DatabaseValueConvertible>(_ column: Column) -> Value?
-    func value<Value: DatabaseValueConvertible>(_ column: Column) -> Value
+    subscript(_ index: Int) -> DatabaseValueConvertible?
+    subscript<Value: DatabaseValueConvertible>(_ index: Int) -> Value?
+    subscript<Value: DatabaseValueConvertible>(_ index: Int) -> Value
+    subscript(_ columnName: String) -> DatabaseValueConvertible?
+    subscript<Value: DatabaseValueConvertible>(_ columnName: String) -> Value?
+    subscript<Value: DatabaseValueConvertible>(_ columnName: String) -> Value
+    subscript(_ column: Column) -> DatabaseValueConvertible?
+    subscript<Value: DatabaseValueConvertible>(_ column: Column) -> Value?
+    subscript<Value: DatabaseValueConvertible>(_ column: Column) -> Value
 }

 class SelectStatement {
+    func index(ofColumn columnName: String) -> Int?
 }
 
+extension MutablePersistable {
+    var databaseDictionary: [String: DatabaseValue]
+}
 
-extension TableMapping {
+extension MutablePersistable {
     @discardableResult static func deleteAll(_ db: Database) throws -> Int
     @discardableResult static func deleteAll<Sequence: Swift.Sequence>(_ db: Database, keys: Sequence) throws -> Int where Sequence.Element: DatabaseValueConvertible
     @discardableResult static func deleteOne<PrimaryKeyType: DatabaseValueConvertible>(_ db: Database, key: PrimaryKeyType?) throws -> Bool
     @discardableResult static func deleteAll(_ db: Database, keys: [[String: DatabaseValueConvertible?]]) throws -> Int
     @discardableResult static func deleteOne(_ db: Database, key: [String: DatabaseValueConvertible?]) throws -> Bool
 }
-extension QueryInterfaceRequest {
+extension QueryInterfaceRequest where RowDecoder: MutablePersistable {
     @discardableResult func deleteAll(_ db: Database) throws -> Int
 }

 protocol TableMapping {
-    static var selectsRowID: Bool { get }
+    static var databaseSelection: [SQLSelectable] { get }
 }
 class Record {
-    open class var selectsRowID: Bool
+    open class var databaseSelection: [SQLSelectable]
 }
+struct AllColumns {
+    init()
+}

 class Database {
-    func primaryKey(_ tableName: String) throws -> PrimaryKeyInfo?
+    func primaryKey(_ tableName: String) throws -> PrimaryKeyInfo
 }
 struct PrimaryKeyInfo {
+    var isRowID: Bool { get }
 }

+extension Set {
+    init<C: Cursor>(_ cursor: C) throws where C.Element == Element
+}

-final class DatabaseCursor { }
+final class ColumnCursor<Value: DatabaseValueConvertible & StatementColumnConvertible> : Cursor {
+    typealias Element = Value
+}
+final class DatabaseValueCursor<Value: DatabaseValueConvertible> : Cursor  {
+    typealias Element = Value
+}
+final class NullableColumnCursor<Value: DatabaseValueConvertible & StatementColumnConvertible> : Cursor  {
+    typealias Element = Value?
+}
+final class NullableDatabaseValueCursor<Value: DatabaseValueConvertible> : Cursor  {
+    typealias Element = Value?
+}
+final class RecordCursor<Record: RowConvertible> : Cursor  {
+    typealias Element = Record
+}
+final class RowCursor : Cursor {
+    typealias Element = Row
+    let statement: SelectStatement
+}
 extension DatabaseValueConvertible {
-    static func fetchCursor(...) throws -> DatabaseCursor<Self>
+    static func fetchCursor(...) throws -> DatabaseValueCursor<Self>
 }
 extension DatabaseValueConvertible where Self: StatementColumnConvertible {
+    static func fetchCursor(...) throws -> ColumnCursor<Self>
 }
 extension Optional where Wrapped: DatabaseValueConvertible {
-    static func fetchCursor(...) throws -> DatabaseCursor<Wrapped?>
+    static func fetchCursor(...) throws -> NullableDatabaseValueCursor<Wrapped>
 }
 extension Optional where Wrapped: DatabaseValueConvertible & StatementColumnConvertible {
+    static func fetchCursor(...) throws -> NullableColumnCursor<Wrapped>
 }
 extension Row {
-    static func fetchCursor(...) throws -> DatabaseCursor<Row>
+    static func fetchCursor(...) throws -> RowCursor
 }
 extension RowConvertible where Self: TableMapping {
-    static func fetchCursor(...) throws -> DatabaseCursor<Self>?
+    static func fetchCursor(...) throws -> RecordCursor<Self>
 }
 extension TypedRequest where RowDecoder: RowConvertible {
-    func fetchCursor(_ db: Database) throws -> DatabaseCursor<RowDecoder>
+    func fetchCursor(_ db: Database) throws -> RecordCursor<RowDecoder>
 }
 extension TypedRequest where RowDecoder: DatabaseValueConvertible {
-    func fetchCursor(_ db: Database) throws -> DatabaseCursor<RowDecoder>
+    func fetchCursor(_ db: Database) throws -> DatabaseValueCursor<RowDecoder>
 }
 extension TypedRequest where RowDecoder: DatabaseValueConvertible & StatementColumnConvertible {
+    func fetchCursor(_ db: Database) throws -> ColumnCursor<RowDecoder>
 }
 extension TypedRequest where RowDecoder: _OptionalProtocol, RowDecoder._Wrapped: DatabaseValueConvertible {
-    func fetchCursor(_ db: Database) throws -> DatabaseCursor<RowDecoder._Wrapped?>
+    func fetchCursor(_ db: Database) throws -> NullableDatabaseValueCursor<RowDecoder._Wrapped>
 }
 extension TypedRequest where RowDecoder: _OptionalProtocol, RowDecoder._Wrapped: DatabaseValueConvertible & StatementColumnConvertible {
+    func fetchCursor(_ db: Database) throws -> NullableColumnCursor<RowDecoder._Wrapped>
 }
 extension TypedRequest where RowDecoder: Row {
-    func fetchCursor(_ db: Database) throws -> DatabaseCursor<Row>
+    func fetchCursor(_ db: Database) throws -> RowCursor
 }

 extension TableMapping {
-    @available(*, deprecated) static func primaryKeyRowComparator(_ db: Database) throws -> (Row, Row) -> Bool
 }

+final class AnyDatabaseReader : DatabaseReader {
+     init(_ base: DatabaseReader)
+}
+final class AnyDatabaseWriter : DatabaseWriter {
+     init(_ base: DatabaseWriter)
+}

Experimental API diff

 enum SQLCount {
-    case star
+    case all
 }

1.3.0

Released August 18, 2017 • diff

New

  • Upgrade custom SQLite builds to v3.20.0 (thanks to @swiftlyfalling).
  • Complete support for all signed and unsigned integer types: from Int8 toUInt64, all integers can be stored and loaded from the database.

API diff

+extension Int8: DatabaseValueConvertible, StatementColumnConvertible { }
+extension Int16: DatabaseValueConvertible, StatementColumnConvertible { }
+extension UInt8: DatabaseValueConvertible, StatementColumnConvertible { }
+extension UInt16: DatabaseValueConvertible, StatementColumnConvertible { }
+extension UInt32: DatabaseValueConvertible, StatementColumnConvertible { }
+extension UInt64: DatabaseValueConvertible, StatementColumnConvertible { }
+extension UInt: DatabaseValueConvertible, StatementColumnConvertible { }

1.2.2

Released July 20, 2017 • diff

Fixed

  • The Configuration.trace function no longer leaks memory.

1.2.1

Released July 19, 2017 • diff

Fixed

  • Upgrade custom SQLite builds to v3.19.3 (thanks to @swiftlyfalling).

  • The Query Interface now generates IS NULL SQL snippets for comparisons with DatabaseValue.null:

    // SELECT * FROM players WHERE email IS NULL
Player.filter(Column("email") == DatabaseValue.null)

    It used to generate = NULL which would not behave as expected.

1.2.0

Released July 13, 2017 • diff

New

  • Record types that do not provide values for all table columns in their encode(to:) method are now supported.

  • The table creation API has been enhanced:

    • SQLite supports untyped columns:

      try dbQueue.inDatabase { db in
    // CREATE TABLE t(a, b)
    try db.create(table: "t") { t in
        t.column("a")
        t.column("b")
    }
}

      Untyped columns behave like decimal, boolean, date columns, and generally all columns with NUMERIC type affinity.

      This feature addresses #169.

    • The indexed() methods lets you create a non-unique index on a table column:

      try dbQueue.inDatabase { db in
    // CREATE TABLE rounds(score INTEGER)
    // CREATE INDEX rounds_on_score ON rounds(score)
    try db.create(table: "rounds") { t in
        t.column("score", .integer).indexed()
    }
}

    • It is now possible to define references to tables without any explicit primary key. The generated SQL then uses the rowid hidden primary key column:

      try dbQueue.inDatabase { db in
    // CREATE TABLE nodes(
    //   name TEXT,
    //   parentId INTEGER REFERENCES nodes(rowid)
    // )
    try db.create(table: "nodes") { t in
        t.column("name", .text)
        t.column("parentId", .integer).references("nodes")
    }
}

  • DatabaseQueue, DatabasePool and their common protocol DatabaseReader can now perform "unsafe reentrant reads" (documentation):

    try dbPool.read { db in
    // This is allowed
    try dbPool.unsafeReentrantRead { db in
        ...
    }
}

Fixed

  • DatabasePool.read, and DatabasePool.unsafeRead now raise a fatal error when used in a reentrant way:

    try dbPool.read { db in
    // fatal error: "Database methods are not reentrant."
    try dbPool.read { db in
        ...
    }
}

    While this change may appear as a breaking change, it is really a fix: reentrant reads deadlock as soon as the maximum number of readers has been reached.

API diff

 final class ColumnDefinition {
+    @discardableResult func indexed() -> Self
 }
 
 final class TableDefinition {
-    func column(_ name: String, _ type: Database.ColumnType) -> ColumnDefinition
+    func column(_ name: String, _ type: Database.ColumnType? = nil) -> ColumnDefinition
 }
 
 protocol DatabaseReader {
+    func unsafeReentrantRead<T>(_ block: (Database) throws -> T) throws -> T
 }

1.1.0

Released July 1, 2017 • diff

New

  • DatabaseAggregate is the protocol for custom aggregate functions (fixes #236, documentation):

    struct MySum : DatabaseAggregate {
    var sum: Int = 0
    
    mutating func step(_ dbValues: [DatabaseValue]) {
        if let int = Int.fromDatabaseValue(dbValues[0]) {
            sum += int
        }
    }
    
    func finalize() -> DatabaseValueConvertible? {
        return sum
    }
}

let dbQueue = DatabaseQueue()
let fn = DatabaseFunction("mysum", argumentCount: 1, aggregate: MySum.self)
dbQueue.add(function: fn)
try dbQueue.inDatabase { db in
    try db.execute("CREATE TABLE test(i)")
    try db.execute("INSERT INTO test(i) VALUES (1)")
    try db.execute("INSERT INTO test(i) VALUES (2)")
    try Int.fetchOne(db, "SELECT mysum(i) FROM test")! // 3
}

Fixed

  • QueryInterfaceRequest.order(_:) clears the eventual reversed flag, and better reflects the documentation of this method: "Any previous ordering is replaced."

Deprecated

  • TableMapping.primaryKeyRowComparator is deprecated, without any replacement.

API diff

 final class DatabaseFunction {
+    init<Aggregate: DatabaseAggregate>(_ name: String, argumentCount: Int32? = nil, pure: Bool = false, aggregate: Aggregate.Type)
 }
 
+protocol DatabaseAggregate {
+    init()
+    mutating func step(_ dbValues: [DatabaseValue]) throws
+    func finalize() throws -> DatabaseValueConvertible?
+}

 extension TableMapping {
+    @available(*, deprecated)
     static func primaryKeyRowComparator(_ db: Database) throws -> (Row, Row) -> Bool
 }

1.0.0

Released June 20, 2017 :tada:

GRDB 1.0 comes with enhancements, and API stability.

It comes with breaking changes, but the good news is that they are the last (until GRDB 2.0) :sweat_smile:!

  • Requirements have changed: Xcode 8.3+ / Swift 3.1

    As a matter of fact, GRDB 1.0 still supports Xcode 8.1 and Swift 3.0. But future versions are free to use Swift 3.1 features, and will require Xcode 8.3+.

    The targetted operating systems are unchanged: iOS 8.0+ / macOS 10.9+ / watchOS 2.0+

  • Record types have their persistentDictionary property replaced with the encode(to:) method:

    struct Player : Persistable {
    let name: String
    let score: Int

    // Old
//    var persistentDictionary: [String: DatabaseValueConvertible?] {
//        return [
//            "name": name,
//            "score": score,
//        ]
//    }

    // New
    func encode(to container: inout PersistenceContainer) {
        container["name"] = name
        container["score"] = score
    }
}

    This is good for applications that declare lists of columns:

    struct Player : RowConvertible, Persistable {
    let name: String
    let score: Int
    
    static let databaseTableName = "players"
    
    // Declare Player columns
    enum Columns {
        static let name = Column("name")
        static let score = Column("score")
    }
    
    // Use columns in `init(row:)`
    init(row: Row) {
        name = row.value(Columns.name)
        score = row.value(Columns.score)
    }
    
    // Use columns in the new `encode(to:)` method:
    func encode(to container: inout PersistenceContainer) {
        container[Columns.name] = name
        container[Columns.score] = score
    }
}

  • Database Observation has been enhanced:

    Database.afterNextTransactionCommit(_:) is the simplest way to handle successful transactions, and synchronize the database with other resources such as files, or system sensors (documentation).

    // Make sure the database is inside a transaction
db.inSavepoint {
    // Perform some database job
    try ...
    
    // Register extra job that is only executed after database changes
    // have been committed and written to disk.
    db.afterNextTransactionCommit { ... }
}

    On the low-level side, applications can now specify the extent of database observation (documentation).

  • DatabaseMigrator is easier to test, with its DatabaseMigrator.migrate(_:upTo:) method which partially migrates your databases (documentation).

  • On the side of database schema introspection, the new Database.foreignKeys(on:) method lists the foreign keys defined on a table.

Full list of changes

 class Database {
-    func add(transactionObserver: TransactionObserver)
+    func add(transactionObserver: TransactionObserver, extent: TransactionObservationExtent = .observerLifetime)
+    func afterNextTransactionCommit(_ closure: @escaping (Database) -> ())
+    func foreignKeys(on tableName: String) throws -> [ForeignKeyInfo]
 }

-struct DatabaseCoder: DatabaseValueConvertible

 struct DatabaseMigrator {
+    func migrate(_ writer: DatabaseWriter, upTo targetIdentifier: String) throws
 }

 protocol DatabaseWriter : DatabaseReader {
-    func add(transactionObserver: TransactionObserver)
+    func add(transactionObserver: TransactionObserver, extent: TransactionObservationExtent = .observerLifetime)
 }

 protocol MutablePersistable : TableMapping {
-    var persistentDictionary: [String: DatabaseValueConvertible?] { get }
+    func encode(to container: inout PersistenceContainer)
 }

 extension QueryInterfaceRequest {
-    func contains(_ value: SQLExpressible) -> SQLExpression
-    func exists() -> SQLExpression
 }

 extension Request {
-    func adapted(_ adapter: @escaping (Database) throws -> RowAdapter) -> AnyRequest
+    func adapted(_ adapter: @escaping (Database) throws -> RowAdapter) -> AdaptedRequest<Self>
 }

protocol TypedRequest : Request {
-    associatedtype Fetched
+    associatedtype RowDecoder
}

 extension TypedRequest {
-    func adapted(_ adapter: @escaping (Database) throws -> RowAdapter) -> AnyTypedRequest<Fetched>
+    func adapted(_ adapter: @escaping (Database) throws -> RowAdapter) -> AdaptedTypedRequest<Self>
 }

0.110.0

Released May 28, 2017

New

Fixed

0.109.0

Released May 22, 2017

Fixed

  • Failed value conversions now consistently crash with a fatal error.

New

  • DatabaseValue.losslessConvert() performs a lossless conversion to a value type.

Breaking Changes

  • DatabaseEventKind.impacts(_ selectionInfo:SelectStatement.SelectionInfo) now returns an non-optional boolean.
  • DatabaseWriter.availableDatabaseConnection has been replaced by DatabaseWriter.unsafeReentrantWrite().
  • Request.bound(to:) has been renamed Request.asRequest(of:).

0.108.0

Released May 17, 2017

New

  • Use CocoaPods to install GRDB with SQLCipher:

    pod 'GRDBCipher'

Breaking Changes

  • RowConvertible.awakeFromFetch() has been removed.

0.107.0

Released May 5, 2017

New

  • SQLRequest learned how to reuse cached prepared statements: SQLRequest("SELECT ...", cached: true)

  • Database.logError lets you register a global error logging function:

    Database.logError = { resultCode, message in
    NSLog("%@", "SQLite error \(resultCode): \(message)")
}

0.106.1

Released April 12, 2017

No change, but a better support for Swift Package Manager at the git repository level.

0.106.0

Released April 11, 2017

New

0.105.0

Released April 6, 2017

Fixed

  • FetchedRecordsController used to be able to miss changes performed on requests that use the COUNT SQL function. This is fixed.

New

  • DatabaseWriter.availableDatabaseConnection allows reentrant uses of GRDB, and improves support for reactive programming.

Breaking Changes

  • DatabaseEventKind.impacts(_ selectionInfo:SelectStatement.SelectionInfo) now returns an optional boolean which, when nil, tells that GRDB doesn't know if a statement has any impact on the selection of a request. In practice, this happens as soon as a request uses the COUNT SQL function.

0.104.0

Released April 3, 2017

New

  • Support for Xcode 8.3 and Swift 3.1 (Xcode 8.1 and Swift 3 are still supported).
  • Upgrade custom SQLite builds to v3.18.0 (thanks to @swiftlyfalling).
  • Support for reactive extensions:
    • SelectStatement.SelectionInfo is an opaque value that knows which database tables and columns are read by a select statement.
    • DatabaseEventKind.impacts(_ selectionInfo:SelectStatement.SelectionInfo) tells whether a database change has any impact on the results of a select statement. See Database Changes Observation
    • TableMapping.primaryKeyRowComparator(_ db: Database) returns a function that compares two database rows and return true if and only if they have the same non-null primary key.

Breaking Changes

  • SQLite C API is now available right from the GRDB module: you don't need any longer to import SQLiteiPhoneOS module et al (see documentation for Raw SQLite Pointers).
  • The manual installation procedure for WatchOS extensions has changed.
  • Carthage is no longer supported. At the present time it is unable to support the various frameworks built by GRDB (system SQLite, SQLCipher, custom SQLite builds, etc.)

0.103.0

Released March 26, 2017

Fixed

  • DatabaseError conversion to NSError preserves extended result codes.
  • DatabaseQueue.read and DatabaseQueue.readFromCurrentState throw an error upon database modifications.
  • Added missing availability checks for SQLite features that are not available on all versions of iOS, macOS, watchOS.
  • Removed useless availability checks for SQLite features that are available with SQLCipher and custom SQLite builds.
  • Prevent wrong linking of SQLCipher

Breaking Changes

  • DatabaseQueue.writeInTransaction, alias for DatabaseQueue.inTransaction, has been removed.
  • DatabaseValue.value() has been removed, in favor of DatabaseValue.storage.

0.102.0

Released March 2, 2017

New: Error Handling (fixes #171)

  • GRDB activates SQLite's extended result codes for more detailed error reporting.

  • The new ResultCode type defines constants for all SQLite result codes and extended result codes.

  • The SQLite error code of DatabaseError can be queried with resultCode, or extendedResultCode, depending on the level of details you need (documentation):

    do {
    ...
} catch let error as DatabaseError where error.extendedResultCode == .SQLITE_CONSTRAINT_FOREIGNKEY {
    // handle foreign key constraint error
} catch let error as DatabaseError where error.resultCode == .SQLITE_CONSTRAINT {
    // handle any other constraint error
}

New: Request

  • The Request protocol for custom requests learned how to count:

    let request: Request = ...
let count = try request.fetchCount(db) // Int

    Default implementation performs a naive counting based on the request SQL: SELECT COUNT(*) FROM (...). Adopting types can refine the counting SQL by providing their own fetchCount implementation.

    Thanks David Hart for this suggestion.

Breaking Changes

  • DatabaseError.code has been removed, replaced with DatabaseError.resultCode and DatabaseError.extendedResultCode (documentation).
  • DatabaseMigrator.registerMigrationWithDisabledForeignKeyChecks has been renamed DatabaseMigrator.registerMigrationWithDeferredForeignKeyCheck (documentation)

0.101.1

Released January 20, 2017

New

  • DatabaseEventKind.tableName makes it easier to track any change that may happen to a database table (documentation)
  • FetchedRecordsController.allowBackgroundChangesTracking(in:): call this FetchedRecordsController method when changes performed while the application is in the background should be processed before the application enters the suspended state.

Breaking Changes

0.100.0

Released January 10, 2017

New

Breaking Changes

  • It is now a programmer error to invoke FetchedRecordsController.fetchedRecords before performFetch():

    final class FetchedRecordsController<Record: RowConvertible> {
-    var fetchedRecords: [Record]?
+    var fetchedRecords: [Record]
}

  • The fetched record type of a FetchedRecordsController is now infered from the request that feeds the controller:

    final class FetchedRecordsController<Record: RowConvertible> {
-    convenience init(...:request: Request) throws
+    convenience init<Request>(...:request: Request) throws where Request: TypedRequest, Request.Fetched == Record
}

  • FetchedRecordsController now automatically compares records by primary key when the record type adopts the TableMapping protocol, such as all Record subclasses. This feature used to require an explicit compareRecordsByPrimaryKey initialization parameter:

    extension FetchedRecordsController where Record: TableMapping {
-    convenience init(...:compareRecordsByPrimaryKey: Bool) throws
}

  • Change tracking APIs have been modified:

    final class FetchedRecordsController<Record: RowConvertible> {
-    func trackChanges(recordsWillChange:tableViewEvent:recordsDidChange:)
+    func trackChanges(willChange:onChange:didChange:)
}

0.99.2

Released December 22, 2016

Fixed

  • Database.cachedSelectStatement() no longer returns a statement that can not be reused because it has already failed.

0.99.1

Released December 21, 2016

Fixed

0.99.0 (don't use)

Released December 20, 2016

Fixed

New

  • FetchedRecordsController no longer crashes whenever an error prevents it from looking for changes after a transaction has potentially modified the tracked request. Instead, it notifies its optional error handler:

    controller.trackErrors { (controller, error) in
    print("Missed a transaction because \(error)")
}

0.98.0

Released December 16, 2016

New

  • StatementArguments can be concatenated with the append(contentsOf:) method and the +, &+, += operators (documentation)

  • Rows expressed as dictionary literals now preserve column ordering, and allow duplicated column names:

    let row: Row = ["foo": 1, "foo": Date(), "baz": nil]
print(row)
// Prints <Row foo:1 foo:"2016-12-16 13:19:49.230" baz:NULL>

0.97.0

Released December 15, 2016

Fixed

  • DatabasePool read and readFromCurrentState methods now properly throw errors whenever they can't acquire an isolated access to the database.

New

  • Raw transaction and savepoint SQL statements are properly reflected in transaction observers, Database.isInsideTransaction, etc.

0.96.0

Released December 11, 2016

New

  • Request.adapted modifies a request with a row adapter.

    // Person has `email` column, but User expects `identifier` column:
Person.all()
    .adapted { _ in ColumnMapping(["identifier": "email"]) }
    .bound(to: User.self)

Breaking Changes

  • RowAdapter protocol has been refactored. This only affects your code if you implement your own row adapter.

0.95.0

Released December 9, 2016

New

  • SQLRequest, AnyRequest, TypedRequest and AnyTypedRequest are new protocols and concrete types that let you build custom fetch requests.
  • RangeRowAdapter is a new kind of row adapter which exposes a range of columns.

Breaking Changes

  • FetchRequest protocol has been renamed Request.

0.94.0

Released December 7, 2016

New

  • Database.columnCount(in:) returns the number of columns in a database table. This helps building row adapters for joined requests.

0.93.1

Released December 7, 2016

Fixed

  • Removed Record.hasPersistentChangedValues dependency on awakeFromFetch(). This makes it easier to wrap records in other RowConvertible types, since awakeFromFetch() can be overlooked without bad consequences on changes tracking.

0.93.0

Released December 4, 2016

New

0.92.1

Released December 2, 2016

Fixed

  • Database.execute(_:) now iterates all rows of statements (and executes any side effect performed by the evaluation of each row).

0.92.0

Released December 1, 2016

Fixed

  • Fixed a bug in DatabasePool.readFromCurrentState where its block argument could see database changes that it should not have seen (documentation).

Breaking Changes

  • DatabaseWriter.readFromWrite has been renamed DatabaseWriter.readFromCurrentState
  • DatabaseReader.nonIsolatedRead has been renamed DatabaseReader.unsafeRead

0.91.0

Released November 30, 2016

Breaking Changes

Generally speaking, fetching methods can now throw errors. The fetch method have been removed, along with DatabaseSequence and DatabaseIterator, replaced by the fetchCursor method and DatabaseCursor (documentation):

// No longer supported
let persons = Person.fetch(db) // DatabaseSequence<Person>
for person in persons {        // Person
    ...
}

// New
let persons = try Person.fetchCursor(db) // DatabaseCursor<Person>
while person = try persons.next() {      // Person
    ...
}

Many APIs were changed:

Database Connections

 final class Database {
-    func tableExists(_ tableName: String) -> Bool
-    func indexes(on tableName: String) -> [IndexInfo]
+    func tableExists(_ tableName: String) throws -> Bool
+    func indexes(on tableName: String) throws -> [IndexInfo]
 }
 
 final class DatabasePool {
-    func read<T>(_ block: (Database) throws -> T) rethrows -> T
-    func nonIsolatedRead<T>(_ block: (Database) throws -> T) rethrows -> T
-    func readFromWrite(_ block: @escaping (Database) -> Void)
+    func read<T>(_ block: (Database) throws -> T) throws -> T
+    func nonIsolatedRead<T>(_ block: (Database) throws -> T) throws -> T
+    func readFromWrite(_ block: @escaping (Database) -> Void) throws
 }
 
 protocol DatabaseReader {
-    func read<T>(_ block: (Database) throws -> T) rethrows -> T
-    func nonIsolatedRead<T>(_ block: (Database) throws -> T) rethrows -> T
+    func read<T>(_ block: (Database) throws -> T) throws -> T
+    func nonIsolatedRead<T>(_ block: (Database) throws -> T) throws -> T
 }
 
 protocol DatabaseWriter {
-    func readFromWrite(_ block: @escaping (Database) -> Void)
+    func readFromWrite(_ block: @escaping (Database) -> Void) throws
 }

Fetching Rows and Values

 final class Row {
-    static func fetch(...) -> DatabaseSequence<Row>
-    static func fetchAll(...) -> [Row]
-    static func fetchOne(...) -> Row?
+    static func fetchCursor(...) -> DatabaseCursor<Row>
+    static func fetchAll(...) throws -> [Row] {
+    static func fetchOne(...) throws -> Row?
 }
 
 extension DatabaseValueConvertible {
-    static func fetch(...) -> DatabaseSequence<Self>
-    static func fetchAll(...) -> [Self]
-    static func fetchOne(...) -> Self?
+    static func fetchCursor(...) -> DatabaseCursor<Self>
+    static func fetchAll(...) throws -> [Self]
+    static func fetchOne(...) throws -> Self?
 }
 
 extension Optional where Wrapped: DatabaseValueConvertible {
-    static func fetch(...) -> DatabaseSequence<Wrapped?>
-    static func fetchAll(...) -> [Wrapped?]
+    static func fetchCursor(...) throws -> DatabaseCursor<Wrapped?>
+    static func fetchAll(...) throws -> [Wrapped?]
 }

Records and the Query Interface

 final class FetchedRecordsController<Record: RowConvertible> {
-    init(...)
-    func performFetch(...)
-    func setRequest(...)
+    init(...) throws
+    func performFetch(...) throws
+    func setRequest(...) throws
 }
 
 protocol MutablePersistable : TableMapping {
-    func exists(_ db: Database) -> Bool
+    func exists(_ db: Database) throws -> Bool
 }
 
 extension MutablePersistable {
-    func performExists(_ db: Database) -> Bool
+    func performExists(_ db: Database) throws -> Bool
 }

 extension QueryInterfaceRequest {
-    func fetchCount(...) -> Int
+    func fetchCount(...) throws -> Int
 }
 
 extension QueryInterfaceRequest where T: RowConvertible {
-    func fetch(...) -> DatabaseSequence<T>
-    func fetchAll(...) -> [T]
-    func fetchOne(...) -> T?
+    func fetchCursor(...) throws -> DatabaseCursor<T>
+    func fetchAll(...) throws -> [T]
+    func fetchOne(...) throws -> T?
 }
 
 extension RowConvertible {
-    static func fetch(...) -> DatabaseSequence<Self>
-    static func fetchAll(...) -> [Self]
-    static func fetchOne(...) -> Self?
+    static func fetchCursor(...) throws -> DatabaseCursor<Self> {
+    static func fetchAll(...) throws -> [Self] {
+    static func fetchOne(...) throws -> Self?
 }
 
 extension TableMapping {
-    static func fetchCount(_ db: Database) -> Int
+    static func fetchCount(_ db: Database) throws -> Int
 }

Cursors

-struct DatabaseSequence<Element>: Sequence
-final class DatabaseIterator<Element>: IteratorProtocol

+extension Array {
+    init<C : Cursor>(_ cursor: C) throws where C.Element == Element
+}

+class AnyCursor<Element> : Cursor {
+    init<C : Cursor>(_ base: C) where C.Element == Element
+    init(_ body: @escaping () throws -> Element?)
+}

+protocol Cursor : class {
+    associatedtype Element
+    func next() throws -> Element?
+}

+extension Cursor {
+    func contains(where predicate: (Element) throws -> Bool) throws -> Bool
+    func enumerated() -> EnumeratedCursor<Self>
+    func filter(_ isIncluded: @escaping (Element) throws -> Bool) -> FilterCursor<Self>
+    func first(where predicate: (Element) throws -> Bool) throws -> Element?
+    func flatMap<ElementOfResult>(_ transform: @escaping (Element) throws -> ElementOfResult?) -> MapCursor<FilterCursor<MapCursor<Self, ElementOfResult?>>, ElementOfResult>
+    func flatMap<SegmentOfResult : Sequence>(_ transform: @escaping (Element) throws -> SegmentOfResult) -> FlattenCursor<MapCursor<Self, IteratorCursor<SegmentOfResult.Iterator>>>
+    func flatMap<SegmentOfResult : Cursor>(_ transform: @escaping (Element) throws -> SegmentOfResult) -> FlattenCursor<MapCursor<Self, SegmentOfResult>>
+    func forEach(_ body: (Element) throws -> Void) throws
+    func map<T>(_ transform: @escaping (Element) throws -> T) -> MapCursor<Self, T>
+    func reduce<Result>(_ initialResult: Result, _ nextPartialResult: (Result, Element) throws -> Result) throws -> Result
+}

+extension Cursor where Element: Equatable {
+    func contains(_ element: Element) throws -> Bool
+}

+extension Cursor where Element: Cursor {
+    func joined() -> FlattenCursor<Self>
+}

+extension Cursor where Element: Sequence {
+    func joined() -> FlattenCursor<MapCursor<Self, IteratorCursor<Self.Element.Iterator>>>
+}

+final class DatabaseCursor<Element> : Cursor
+final class EnumeratedCursor<Base : Cursor> : Cursor
+final class FilterCursor<Base : Cursor> : Cursor
+final class FlattenCursor<Base: Cursor> : Cursor where Base.Element: Cursor
+final class MapCursor<Base : Cursor, Element> : Cursor
+final class IteratorCursor<Base : IteratorProtocol> : Cursor {
+    init(_ base: Base)
+    init<S : Sequence>(_ s: S) where S.Iterator == Base
+}

+extension Sequence {
+    func flatMap<SegmentOfResult : Cursor>(_ transform: @escaping (Iterator.Element) throws -> SegmentOfResult) -> FlattenCursor<MapCursor<IteratorCursor<Self.Iterator>, SegmentOfResult>>
+}

0.90.1

Released November 18, 2016

Fixed

  • Fixed a couple Xcode 8.1 warnings

0.90.0

Released November 5, 2016

New

Fixed

  • FetchedRecordsController no longer exposes record comparison options to platforms that don't need them. The isSameRecord and compareRecordsByPrimaryKey parameters are now iOS only:

    // iOS only
let controller = FetchedRecordsController<MyRecord>(
    dbQueue,
    request: ...,
    compareRecordsByPrimaryKey: true)

// All platforms
let controller = FetchedRecordsController<MyRecord>(
    dbQueue,
    request: ...)

0.89.2

Released October 26, 2016

Fixed

  • Query Interface: CountableRange.contains() no longer generates BETWEEN operator.

    For example, 1..<10.contains(Column("x")) now generates x >= 1 AND x < 10 instead of x BETWEEN 1 AND 9. This should better reflect the user intent whenever an Int range tests Double values.

0.89.1

Released October 19, 2016

Fixed

  • When Database.create(virtualTable:using:) throws, it is now guaranteed that the virtual table table is not created.
  • FetchedRecordsController learned about TableMapping.selectsRowID, and is now able to animate table views populated with records without explicit primary key.
  • Restored SQLCipher installation procedure

0.89.0

Released October 17, 2016

Fixed

  • FetchedRecordsController could miss database changes after its fetch request was modified. Now it properly updates the set of tracked columns and tables.

New

  • TableMapping.none(): a fetch request which fetches nothing.

0.88.0

Released October 16, 2016

New

  • Full-text matching methods accept nil search patterns:

    let pattern = FTS3SearchPattern(matchingAllTokensIn: "") // nil
let documents = Document.matching(pattern).fetchAll(db)  // Empty array

  • Synchronization of an FTS4 or FTS5 full-text table with an external content table (documentation):

    // A regular table
try db.create(table: "books") { t in
    t.column("author", .text)
    t.column("title", .text)
    t.column("content", .text)
    ...
}

// A full-text table synchronized with the regular table
try db.create(virtualTable: "books_ft", using: FTS4()) { t in // or FTS5()
    t.synchronize(withTable: "books")
    t.column("author")
    t.column("title")
    t.column("content")
}

  • Upgrade custom SQLite builds to v3.15.0 (thanks to @swiftlyfalling).

Breaking Change

  • The VirtualTableModule protocol has been modified:

     protocol VirtualTableModule {
-    func moduleArguments(_ definition: TableDefinition) -> [String]
+    func moduleArguments(for definition: TableDefinition, in db: Database) throws -> [String]
+    func database(_ db: Database, didCreate tableName: String, using definition: TableDefinition) throws
 }

0.87.0

Released October 12, 2016

New

Breaking Changes

  • FTS3Tokenizer has been renamed FTS3TokenizerDescriptor
  • FTS5Tokenizer has been renamed FTS5TokenizerDescriptor

0.86.0

Released October 8, 2016

New

  • Full-Text Search. GRDB learned about FTS3, FTS4 and FTS5 full-text engines of SQLite (documentation).

  • Improved support for the hidden "rowid" column:

    • TableMapping.selectsRowID: this optional static property allows records to fetch their hidden rowID column (documentation):

      // SELECT *, rowid FROM books
Book.fetchAll(db)

    • fetchOne(_:key:), fetch(_:keys:), fetchAll(_:keys:), deleteOne(_:key:), deleteAll(_:keys:) now use the hidden rowid column when the table has no explicit primary key.

      // DELETE FROM books WHERE rowid = 1
try Book.deleteOne(db, key: 1)

  • Upgrade custom SQLite builds to v3.14.2.

Breaking Changes

  • Row.value(column:) has lost its parameter name: row.value(Column("id")).
  • QueryInterfaceRequest has lost its public initializer.

0.85.0

Released September 28, 2016

New

  • Enhanced extensibility. The low-level types that fuel the query interface requests and expressions have been refactored, have lost their underscore prefix, and are stabilizing. A new GRDB Extension Guide covers common extension use cases.

  • TableMapping protocol learned how to delete all records right from the adopting type:

    try Person.deleteAll(db)

  • Support for the LIKE operator (fixes #133):

    // SELECT * FROM persons WHERE email LIKE '%@example.com'
Person.filter(Column("email").like("%@example.com")).fetchAll(db)

Breaking Changes

  • The SQLForeignKeyAction, SQLColumnType, SQLConflictResolution, and SQLCollation types have been renamed Database.ForeignKeyAction, Database.ColumnType, Database.ConflictResolution, and Database.CollationName.

0.84.0

Released September 16, 2016

New

  • The Persistable protocol learned about conflict resolution, and can run INSERT OR REPLACE queries (documentation, fixes #118).

0.83.0

Released September 16, 2016

New

  • Upgrade custom SQLite builds to v3.14.1.

Fixed

  • Restore support for SQLite pre-update hooks
  • DatabaseValue.fromDatabaseValue() returns .Null for NULL input, instead of nil (fixes #119)

Breaking Change

  • Row.databaseValue(atIndex:) and Row.databaseValue(named:) have been removed. Use value(atIndex:) and value(named:) instead:

    -let dbValue = row.databaseValue(atIndex: 0)
+let dbValue: DatabaseValue = row[0]

0.82.1

Released September 14, 2016

Fixed

  • GRDB builds in the Release configuration (fix #116, #117, workaround SR-2623)

0.82.0

Released September 11, 2016

New

  • Swift 3

Breaking Changes

  • The Swift 3 Grand Renaming has impacted GRDB a lot.

    General

    • All enum cases now start with a lowercase letter.

    Database Connections

    -typealias BusyCallback = (numberOfTries: Int) -> Bool
-enum BusyMode
-enum CheckpointMode
-enum TransactionKind
-enum TransactionCompletion
 struct Configuration {
-    var fileAttributes: [String: AnyObject]?
+    var fileAttributes: [FileAttributeKey: Any]
 }
 class Database {
+    typealias BusyCallback = (_ numberOfTries: Int) -> Bool
+    enum BusyMode {
+        case immediateError
+        case timeout(TimeInterval)
+        case callback(BusyCallback)
+    }
+    enum CheckpointMode: Int32 {
+        case passive
+        case full
+        case restart
+        case truncate
+    }
+    enum TransactionKind {
+        case deferred
+        case immediate
+        case exclusive
+    }
+    enum TransactionCompletion {
+        case commit
+        case rollback
+    }
 }
 class DatabasePool {
#if os(iOS)
-    func setupMemoryManagement(application application: UIApplication)
+    func setupMemoryManagement(in application: UIApplication) 
#endif
#if SQLITE_HAS_CODEC
-    func changePassphrase(passphrase: String) throws
+    func change(passphrase: String) throws
#endif
 }
 class DatabaseQueue {
#if os(iOS)
-    func setupMemoryManagement(application application: UIApplication)
+    func setupMemoryManagement(in application: UIApplication) 
#endif
#if SQLITE_HAS_CODEC
-    func changePassphrase(passphrase: String) throws
+    func change(passphrase: String) throws
#endif
 }

    Rows

     final class Row {
-    init?(_ dictionary: NSDictionary)
-    func toNSDictionary() -> NSDictionary
+    init?(_ dictionary: [AnyHashable: Any])
 }

    Values

     struct DatabaseValue {
-    init?(object: AnyObject)
-    func toAnyObject() -> AnyObject
+    init?(value: Any)
 }
 protocol DatabaseValueConvertible {
-    static func fromDatabaseValue(dbValue: DatabaseValue) -> DatabaseValue?
+    static func fromDatabaseValue(_ dbValue: DatabaseValue) -> DatabaseValue?
 }
+extension Data : DatabaseValueConvertible
+extension Date : DatabaseValueConvertible
+extension URL : DatabaseValueConvertible
+extension UUID : DatabaseValueConvertible

    SQL Functions

     class Database {
-    func addFunction(function: DatabaseFunction)
-    func removeFunction(function: DatabaseFunction)
+    func add(function: DatabaseFunction)
+    func remove(function: DatabaseFunction)
 }
 class DatabasePool {
-    func addFunction(function: DatabaseFunction)
-    func removeFunction(function: DatabaseFunction)
+    func add(function: DatabaseFunction)
+    func remove(function: DatabaseFunction)
 }
 class DatabaseQueue {
-    func addFunction(function: DatabaseFunction)
-    func removeFunction(function: DatabaseFunction)
+    func add(function: DatabaseFunction)
+    func remove(function: DatabaseFunction)
 }
 protocol DatabaseReader {
-    func addFunction(function: DatabaseFunction)
-    func removeFunction(function: DatabaseFunction)
+    func add(function: DatabaseFunction)
+    func remove(function: DatabaseFunction)
 }
 extension DatabaseFunction {
-static let capitalizedString: DatabaseFunction
-static let lowercaseString: DatabaseFunction
-static let uppercaseString: DatabaseFunction
-static let localizedCapitalizedString: DatabaseFunction
-static let localizedLowercaseString: DatabaseFunction
-static let localizedUppercaseString: DatabaseFunction
+static let capitalize: DatabaseFunction
+static let lowercase: DatabaseFunction
+static let uppercase: DatabaseFunction
+static let localizedCapitalize: DatabaseFunction
+static let localizedLowercase: DatabaseFunction
+static let localizedUppercase: DatabaseFunction
 }

    SQL Collations

     class Database {
-    func addCollation(collation: DatabaseCollation)
-    func removeCollation(collation: DatabaseCollation)
+    func add(collation: DatabaseCollation)
+    func remove(collation: DatabaseCollation)
 }
 class DatabasePool {
-    func addCollation(collation: DatabaseCollation)
-    func removeCollation(collation: DatabaseCollation)
+    func add(collation: DatabaseCollation)
+    func remove(collation: DatabaseCollation)
 }
 class DatabaseQueue {
-    func addCollation(collation: DatabaseCollation)
-    func removeCollation(collation: DatabaseCollation)
+    func add(collation: DatabaseCollation)
+    func remove(collation: DatabaseCollation)
 }
 protocol DatabaseReader {
-    func addCollation(collation: DatabaseCollation)
-    func removeCollation(collation: DatabaseCollation)
+    func add(collation: DatabaseCollation)
+    func remove(collation: DatabaseCollation)
 }

    Prepared Statements

     class Database {
-    func selectStatement(sql: String) throws -> SelectStatement
-    func updateStatement(sql: String) throws -> SelectStatement
+    func makeSelectStatement(_ sql: String) throws -> SelectStatement
+    func makeUpdateStatement(_ sql: String) throws -> SelectStatement
 }
 class Statement {
-    func validateArguments(arguments: StatementArguments) throws
+    func validate(arguments: StatementArguments) throws
 }
 struct StatementArguments {
-    init?(_ array: NSArray)
-    init?(_ dictionary: NSDictionary)
+    init?(_ array: [Any])
+    init?(_ dictionary: [AnyHashable: Any])
 }

    Transaction Observers

    Database events filtering is now performed by transaction observers themselves, in the new observes(eventsOfKind:) method of the TransactionObserver protocol.

     class Database {
-    func addTransactionObserver(transactionObserver: TransactionObserverType, forDatabaseEvents filter: ((DatabaseEventKind) -> Bool)? = nil)
-    func removeTransactionObserver(transactionObserver: TransactionObserverType)
+    func add(transactionObserver: TransactionObserver)
+    func remove(transactionObserver: TransactionObserver)
 }
 protocol DatabaseWriter : DatabaseReader {
-    func addTransactionObserver(transactionObserver: TransactionObserverType, forDatabaseEvents filter: ((DatabaseEventKind) -> Bool)? = nil)
-    func removeTransactionObserver(transactionObserver: TransactionObserverType)
+    func add(transactionObserver: TransactionObserver)
+    func remove(transactionObserver: TransactionObserver)
 }
-protocol TransactionObserverType : class {
+protocol TransactionObserver : class {
-    func databaseDidChangeWithEvent(event: DatabaseEvent)
-    func databaseDidCommit(db: Database)
-    func databaseDidRollback(db: Database)
+    func observes(eventsOfKind eventKind: DatabaseEventKind) -> Bool
+    func databaseDidChange(with event: DatabaseEvent)
+    func databaseDidCommit(_ db: Database)
+    func databaseDidRollback(_ db: Database)
 #if SQLITE_ENABLE_PREUPDATE_HOOK
-    func databaseWillChangeWithEvent(event: DatabasePreUpdateEvent)
+    func databaseWillChange(with event: DatabasePreUpdateEvent)
 #endif
 }

    Records

     protocol RowConvertible {
-    init(_ row: Row)
+    init(row: Row)
 }
 protocol MutablePersistable {
-    mutating func didInsertWithRowID(rowID: Int64, forColumn column: String?)
-    mutating func insert(db: Database) throws
-    func update(db: Database, columns: Set<String>) throws
-    mutating func save(db: Database) throws
-    func delete(db: Database) throws -> Bool
-    func exists(db: Database) -> Bool
+    mutating func didInsert(with rowID: Int64, for column: String?)
+    mutating func insert(_ db: Database) throws
+    func update(_ db: Database, columns: Set<String>) throws
+    mutating func save(_ db: Database) throws
+    @discardableResult func delete(_ db: Database) throws -> Bool
+    func exists(_ db: Database) -> Bool
 }
 protocol Persistable : MutablePersistable {
-    func didInsertWithRowID(rowID: Int64, forColumn column: String?)
-    func insert(db: Database) throws
-    func save(db: Database) throws
+    func didInsert(with rowID: Int64, for column: String?)
+    func insert(_ db: Database) throws
+    func save(_ db: Database) throws
 }
 protocol TableMapping {
-    static func databaseTableName() -> String
+    static var databaseTableName: String { get }
 }
-public class Record : RowConvertible, TableMapping, Persistable {
+open class Record : RowConvertible, TableMapping, Persistable {
-    required init(_ row: Row)
-    class func databaseTableName() -> String
-    func awakeFromFetch(row row: Row)
-    func didInsertWithRowID(rowID: Int64, forColumn column: String?)
-    func update(db: Database, columns: Set<String>) throws
-    func insert(db: Database) throws
-    func save(db: Database) throws
-    func delete(db: Database) throws -> Bool
+    required init(row: Row)
+    class var databaseTableName: String
+    func awakeFromFetch(row: Row)
+    func didInsert(with rowID: Int64, for column: String?)
+    func update(_ db: Database, columns: Set<String>) throws
+    func insert(_ db: Database) throws
+    func save(_ db: Database) throws
+    @discardableResult func delete(_ db: Database) throws -> Bool
 }

    Query Interface

     protocol FetchRequest {
-    func prepare(db: Database) throws -> (SelectStatement, RowAdapter?)
+    func prepare(_ db: Database) throws -> (SelectStatement, RowAdapter?)
 }
-struct SQLColumn {}
+struct Column {}
 struct QueryInterfaceRequest<T> {
-    var distinct: QueryInterfaceRequest<T> { get }
-    var exists: _SQLExpression { get }
-    func reverse() -> QueryInterfaceRequest<T>
+    func distinct() -> QueryInterfaceRequest<T>
+    func exists() -> _SQLExpression
+    func reversed() -> QueryInterfaceRequest<T>
 }
 extension _SpecificSQLExpressible {
-    var capitalizedString: _SQLExpression { get }
-    var lowercaseString: _SQLExpression { get }
-    var uppercaseString: _SQLExpression { get }
-    var localizedCapitalizedString: _SQLExpression { get }
-    var localizedLowercaseString: _SQLExpression { get }
-    var localizedUppercaseString: _SQLExpression { get }
+    var capitalized: _SQLExpression { get }
+    var lowercased: _SQLExpression { get }
+    var uppercased: _SQLExpression { get }
+    var localizedCapitalized: _SQLExpression { get }
+    var localizedLowercased: _SQLExpression { get }
+    var localizedUppercased: _SQLExpression { get }
 }

0.81.2 (Swift 2.3)

Released September 28, 2016

New

0.81.1 (Swift 2.3)

Released September 16, 2016

New

  • Upgrade custom SQLite builds to v3.14.1.

Fixed

  • DatabaseValue.fromDatabaseValue() returns .Null for NULL input, instead of nil (fixes #119)

Breaking Change

  • Row.databaseValue(atIndex:) and Row.databaseValue(named:) have been removed. Use value(atIndex:) and value(named:) instead:

    -let dbValue = row.databaseValue(atIndex: 0)
+let dbValue: DatabaseValue = row[0]

0.81.0 (Swift 2.3)

Released September 10, 2016

New

  • Swift 2.3

0.80.2 (Swift 2.2)

Released September 9, 2016

Fixed

  • WatchOS framework

0.80.1

Released September 8, 2016

Fixed

  • WatchOS framework is now available through CocoaPods.

0.80.0

Released September 7, 2016

Fixed

  • Database.tableExists() learned about temporary tables

New

  • WatchOS support

  • QueryInterfaceRequest.deleteAll() deletes database rows:

    try Wine.filter(corked == true).deleteAll(db)

0.79.4

Released August 17, 2016

Fixed

  • DatabasePool can now open an existing database which is not yet in the WAL mode, and then immediately read from it. It used to crash unless at least one write operation was performed before any read (fixes #102).

0.79.3

Released August 16, 2016

Fixed

  • Table creation DSL accepts auto references with implicit primary key:

    try db.create(table: "nodes") { t in
    t.column("id", .Integer).primaryKey()
    t.column("parentId", .Integer).references("nodes")
}

New

  • Use SQLColumn of the query interface when extracting values from rows:

    let nameColumn = SQLColumn("name")
let name: String = row.value(nameColumn)

0.79.2

Released August 10, 2016

Fixed

  • Persistable used to generate sub optimal UPDATE requests.

0.79.1

Released August 10, 2016

Fixed

  • ColumnDefinition check and references methods can now define several constraints:

    try db.create(table: "users") { t in
    t.column("name", .Text).notNull()
        .check { length(\$0) > 0 }
        .check { !["root", "admin"].contains(\$0) }
}

  • Persistable update, exists and delete methods now work with objects that have a nil primary key. They used to crash.

  • The update(_:columns:) method, which performs partial updates, no longer ignores unknown columns.

0.79.0

Released August 8, 2016

Breaking Change

  • Column creation method defaults(_:) has been renamed defaults(to:).

    try db.create(table: "pointOfInterests") { t in
    t.column("favorite", .Boolean).notNull().defaults(to: false)
    ...
}

0.78.0

Released August 6, 2016

New

  • Upgrade sqlcipher to v3.4.0 (announcement, changelog)

  • DSL for table creation and updates (closes #83, documentation):

    try db.create(table: "pointOfInterests") { t in
    t.column("id", .Integer).primaryKey()
    t.column("title", .Text)
    t.column("favorite", .Boolean).notNull()
    t.column("longitude", .Double).notNull()
    t.column("latitude", .Double).notNull()
}

  • Support for the length SQLite built-in function:

    try db.create(table: "persons") { t in
    t.column("name", .Text).check { length(\$0) > 0 }
}

  • Row adopts DictionaryLiteralConvertible:

    let row: Row = ["name": "foo", "date": NSDate()]

Breaking Changes

  • Built-in SQLite collations used to be named by string: "NOCASE", etc. Now use the SQLCollation enum: .Nocase, etc.

  • PrimaryKey has been renamed PrimaryKeyInfo:

    let pk = db.primaryKey("persons")
pk.columns  // ["id"]

0.77.0

Released July 28, 2016

New

  • Database.indexes(on:) returns the indexes defined on a database table.

  • Database.table(_:hasUniqueKey:) returns true if a sequence of columns uniquely identifies a row, that is to say if the columns are the primary key, or if there is a unique index on them.

  • MutablePersistable types, including Record subclasses, support partial updates:

    try person.update(db)                     // Full update
try person.update(db, columns: ["name"])  // Only updates the name column

Breaking Changes

  • MutablePersistable update and performUpdate methods have changed their signatures. You only have to care about this change if you customize the protocol update method.

     protocol MutablePersistable : TableMapping {
-func update(db: Database) throws
+func update(db: Database, columns: Set<String>) throws
 }
 
 extension MutablePersistable {
 func update(db: Database) throws
+func update(db: Database, columns: Set<String>) throws
+func update<S: SequenceType where S.Generator.Element == SQLColumn>(db: Database, columns: S) throws
+func update<S: SequenceType where S.Generator.Element == String>(db: Database, columns: S) throws
-func performUpdate(db: Database) throws
+func performUpdate(db: Database, columns: Set<String>) throws
 }

0.76.0

Released July 19, 2016

Breaking Change

  • The query interface order method now replaces any previously applied ordering (related issue: #85):

    // SELECT * FROM "persons" ORDER BY "name"
Person.order(scoreColumn).order(nameColumn)

0.75.2

Released July 18, 2016

Fixed

  • Fixed crashes that could happen when using virtual tables (fixes #82)

0.75.1

Released July 8, 2016

Fixed

  • Fixed a crash that would happen when performing a full text search in a DatabasePool (fixes #80)

0.75.0

Released July 8, 2016

Breaking change

  • Row adapters have been refactored (documentation).

     // Row "variants" have been renamed row "scopes":
 struct Row {
-    func variant(named name: String) -> Row?
+    func scoped(on name: String) -> Row?
 }
 
 // Scope definition: VariantRowAdapter has been renamed ScopeAdapter:
-struct VariantRowAdapter : RowAdapter {
-    init(variants: [String: RowAdapter])
-}
+struct ScopeAdapter : RowAdapter {
+    init(_ scopes: [String: RowAdapter])
+}
 
 // Adding scopes to an existing adapter:
 extension RowAdapter {
-    func adapterWithVariants(variants: [String: RowAdapter]) -> RowAdapter
+    func addingScopes(scopes: [String: RowAdapter]) -> RowAdapter
 }
 
 // Implementing custom adapters
 protocol ConcreteRowAdapter {
-    var variants: [String: ConcreteRowAdapter] { get }
+    var scopes: [String: ConcreteRowAdapter] { get }
 }

0.74.0

Released July 6, 2016

New

  • TableMapping protocol lets you delete rows identified by their primary keys, or any columns involved in a unique index (closes #56, documentation):

    try Person.deleteOne(db, key: 1)
try Person.deleteOne(db, key: ["email": "arthur@example.com"])
try Citizenship.deleteOne(db, key: ["personID": 1, "countryCode": "FR"])
try Country.deleteAll(db, keys: ["FR", "US"])

Breaking change

  • The fetch(_:keys:), fetchAll(_:keys:) and fetchOne(_:key:) methods used to accept any dictionary of column/value pairs to identify rows. Now these methods raise a fatal error if the columns are not guaranteed, at the database level, to uniquely identify rows: columns must be the primary key, or involved in a unique index:

    // CREATE TABLE persons (
//   id INTEGER PRIMARY KEY, -- can fetch and delete by id
//   email TEXT UNIQUE,      -- can fetch and delete by email
//   name TEXT               -- nope
// )
Person.fetchOne(db, key: ["id": 1])                       // Person?
Person.fetchOne(db, key: ["email": "arthur@example.com"]) // Person?
Person.fetchOne(db, key: ["name": "Arthur"]) // fatal error: table persons has no unique index on column name.

    This change harmonizes the behavior of those fetching methods with the new deleteOne(_:key:) and deleteAll(_:keys:).

0.73.0

Released June 20, 2016

Improved

  • FetchedRecordsController doesn't check for changes when a database transaction modifies columns that are not present in the request it tracks.

New

  • The query interface lets you provide arguments to your sql snippets (documentation):

    let wines = Wine.filter(sql: "origin = ?", arguments: ["Burgundy"]).fetchAll(db)

  • Transaction observers can efficiently filter the database changes they are interested in (documentation).

  • Support for NSUUID (documentation)

0.72.0

Released June 9, 2016

Improved

  • NSDecimalNumber used to store as a double in the database, for all values. Now decimal numbers that contain integers fitting Int64 attempt to store integers in the database.

Breaking Changes

0.71.0

Released June 5, 2016

Fixed

  • Fix a crash that would sometimes happen when a FetchedRecordsController's callbacks avoid retain cycles by capturing unowned references.
  • Improved handling of numeric overflows. Fixes #68.

New

  • GRDB can now use a custom SQLite build (documentation). Merged #62 by @swiftlyfalling.
  • With a custom SQLite build, transaction observers can observe individual column values in the rows modified by a transaction (documentation). Merged #63 by @swiftlyfalling.
  • FetchedRecordsController can now fetch other values alongside the fetched records. This grants you the ability to fetch values that are consistent with the notified changes. (documentation)

Breaking Changes

  • iOS7 is no longer supported.

0.70.1

Released May 30, 2016

Fixed

  • Database.cachedUpdateStatement(sql) no longer returns a statement that can not be reused because it has already failed.

0.70.0

Released May 28, 2016

New

  • Database.inSavepoint() allows fine-grained committing and rollbacking of database statements (documentation). Closes #61.

0.69.0

Released May 28, 2016

Fixed

  • Database changes that are on hold because of a savepoint are only notified to transaction observers after the savepoint has been released. In previous versions of GRDB, savepoints had the opportunity to rollback a subset of database events, and mislead transaction observers about the actual content of a transaction. Related issue: #61.

New

  • DatabaseEvent.copy() lets you store a database event notified to a transaction observer (documentation).

0.68.0

Released May 28, 2016

New

This release provides tools for your custom persistence mechanisms that don't use the built-in Persistable protocol, and addresses issue #60.

  • Database.primaryKey(tableName) lets you introspect a table's primary key (documentation).
  • Database.cachedSelectStatement(sql) and Database.cachedUpdateStatement(sql) provide robust caching of prepared statements (documentation)

0.67.0

Released May 22, 2016

New

  • Row adapters let you map column names for easier row consumption (documentation). Fixes #50.

0.66.0

Released May 21, 2016

Fixed

  • The Record class no longer adopts the CustomStringConvertible protocol. This frees the description identifier for your record properties. Fixes #58.

  • Several database connections can now be used at the same time: you can move values from one database to another. Fixes #55.

Breaking Changes

  • The maximum number of reader connections in a database pool is now configured in a Configuration object.

     final class DatabasePool {
-    init(path: String, configuration: Configuration = default, maximumReaderCount: Int = default) throws
+    init(path: String, configuration: Configuration = default) throws
 }
 struct Configuration {
+    var maximumReaderCount: Int = default
 }

0.65.0

Released May 19, 2016

Fixed

  • GRDB throws an early error when a connection to a file can not be established because it has the wrong format, or is encrypted. Fixes #54.

Breaking Change

  • The FetchRequest struct has been renamed QueryInterfaceRequest. A new FetchRequest protocol has been introduced. All APIs that used to consume the FetchRequest struct now consume the FetchRequest protocol.

    This change should not have any consequence on your source code, and paves the way for easier configuration of any piece of "code that fetches".

    -struct FetchRequest<T> {
-}
+protocol FetchRequest {
+    func selectStatement(db: Database) throws -> SelectStatement
+}
+struct QueryInterfaceRequest<T> : FetchRequest {
+    init(tableName: String)
+}

0.64.0

Released May 18, 2016

Fixed

  • Restored GRDBCipher framework.

Breaking Changes

  • DatabaseValue.failableValue() has been removed. Instead, use DatabaseConvertible.fromDatabaseValue():

    -let date = dbValue.failableValue() as NSDate?
+let date = NSDate.fromDatabaseValue(dbValue)

  • Row.databaseValue(named:) now returns an optional DatabaseValue. It is nil when the column does not exist in the row.

     class Row {
-    func databaseValue(named columnName: String) -> DatabaseValue
+    func databaseValue(named columnName: String) -> DatabaseValue?
 }

  • Row subscripting by column name has been removed. Instead, use Row.databaseValue(named:)

     class Row {
-    subscript(columnName: String) -> DatabaseValue?
 }

0.63.0

Released May 17, 2016

Fixed

  • Restored support for iOS before 8.2 and macOS before 10.10. Fixes #51.

Breaking Changes

  • Support for advanced migrations is not available until iOS 8.2 and macOS 10.10:

     struct DatabaseMigrator {
-    mutating func registerMigration(identifier: String, withDisabledForeignKeyChecks disabledForeignKeyChecks: Bool = false, migrate: (Database) throws -> Void)
+    mutating func registerMigration(identifier: String, migrate: (Database) throws -> Void)
+    @available(iOS 8.2, OSX 10.10, *)
+    mutating func registerMigrationWithDisabledForeignKeyChecks(identifier: String, migrate: (Database) throws -> Void)

0.62.0

Released May 12, 2016

Breaking Changes

  • FetchedRecordsController has been refactored (documentation):

    • delegate has been replaced by callbacks
    • features that target UITableView are now iOS only.
     final class FetchedRecordsController<Record: RowConvertible> {
-    weak var delegate: FetchedRecordsControllerDelegate?
-    func recordAtIndexPath(indexPath: NSIndexPath) -> Record
-    func indexPathForRecord(record: Record) -> NSIndexPath?
-    var sections: [FetchedRecordsSectionInfo<Record>]
+    #if os(iOS)
+        typealias WillChangeCallback = FetchedRecordsController<Record> -> ()
+        typealias DidChangeCallback = FetchedRecordsController<Record> -> ()
+        typealias TableViewEventCallback = (controller: FetchedRecordsController<Record>, record: Record, event: TableViewEvent) -> ()
+        func trackChanges(
+            recordsWillChange willChangeCallback: WillChangeCallback? = nil,
+            tableViewEvent tableViewEventCallback: TableViewEventCallback? = nil,
+            recordsDidChange didChangeCallback: DidChangeCallback? = nil)
+        func recordAtIndexPath(indexPath: NSIndexPath) -> Record
+        func indexPathForRecord(record: Record) -> NSIndexPath?
+        var sections: [FetchedRecordsSectionInfo<Record>]
+    #else
+        typealias WillChangeCallback = FetchedRecordsController<Record> -> ()
+        typealias DidChangeCallback = FetchedRecordsController<Record> -> ()
+        func trackChanges(
+            recordsWillChange willChangeCallback: WillChangeCallback? = nil,
+            recordsDidChange didChangeCallback: DidChangeCallback? = nil)
+    #endif
 }
-protocol FetchedRecordsControllerDelegate : class { }

0.61.0

Released May 10, 2016

New

  • FetchedRecordsController is now exposed in macOS CocoaPods framework (documentation)

Fixed

  • Transactions that fail precisely on the COMMIT statement are now rollbacked (they used to remain open).

0.60.1

Released May 7, 2016

Fixed

  • A crash that did happen when DatabasePool would incorrectly share a database statement between several reader connections.
  • A memory leak that did happen when a Database connection was deallocated while some database statements were still alive.

0.60.0

Released May 5, 2016

New

  • DatabaseReader.backup(to destination: DatabaseWriter) backups a database to another (documentation).

0.59.1

Released April 25, 2016

Fixed

  • Carthage support is restored. Fixes #41.

0.59.0

Released April 23, 2016

New

  • Database.isInsideTransaction is true if database is currently inside a transaction.

Fixed

  • FetchRequest.reverse() sorts by reversed RowID when no base ordering has been specified.

0.58.0

Released April 20, 2016

New

  • Database.lastInsertedRowID: The rowID of the most recent successful INSERT.
  • Database.changesCount: The number of rows modified, inserted or deleted by the most recent successful INSERT, UPDATE or DELETE statement.
  • Database.totalChangesCount: The total number of rows modified, inserted or deleted by all successful INSERT, UPDATE or DELETE statements since the database connection was opened.

Breaking Changes

  • Database.execute() and UpdateStatement.execute() now return Void. To get the last inserted rowId, use the Database.lastInsertedRowID property.

0.57.0

Released April 8, 2016

Breaking Changes

  • Direct access to the database through DatabaseQueue and DatabasePool is no longer supported, because it can hide subtle concurrency bugs in your application:

    // No longer supported, because too dangerous:
try dbQueue.execute("INSERT ...")
let person = Person.fetchOne(dbQueue, key: 1)

// Always use an explicit DatabaseQueue or DatabasePool method instead:
try dbQueue.inDatabase { db in
    try db.execute("INSERT ...")
    let person = Person.fetchOne(db, key: 1)
}

// Extract values:
let person = dbQueue.inDatabase { db in
    Person.fetchOne(db, key: 1)
}

    For more information, see database connections.

    If you are interested in the reasons behind a change that may look like a regression, read https://medium.com/@gwendal.roue/four-different-ways-to-handle-sqlite-concurrency-db3bcc74d00e.

  • The following methods have changed their signatures:

    protocol MutablePersistable {
    mutating func insert(db: Database) throws
    func update(db: Database) throws
    mutating func save(db: Database) throws
    func delete(db: Database) throws -> Bool
    func exists(db: Database) -> Bool
}

protocol Persistable {
    func insert(db: Database) throws
    func save(db: Database) throws
}

class Record {
    func insert(db: Database) throws
    func update(db: Database) throws
    func save(db: Database) throws
    func delete(db: Database) throws -> Bool
    func exists(db: Database) -> Bool
}

0.56.2

Released April 5, 2016

Fixed

  • The save() method accepts again DatabaseQueue and DatabasePool arguments.

0.56.1

Released April 5, 2016

Fixed

  • Restored CocoaPods support for iOS 8+ and macOS 10.9+

0.56.0

Released April 5, 2016

New

  • The new framework GRDBCipher embeds SQLCipher and can encrypt databases (documentation)
  • DatabaseQueue.path and DatabasePool.path give the path to the database.

Fixed

  • Restored iOS 7 compatibility

Breaking Changes (reverted in 0.56.2)

  • The save() method now only accepts a database connection, and won't accept a database queue or database pool as an argument. This change makes sure that this method that may execute several SQL statements is called in an isolated fashion.

0.55.0

Released March 31, 2016

New (iOS only)

  • DatabaseQueue.setupMemoryManagement(application:) and DatabasePool.setupMemoryManagement(application:) make sure GRDB manages memory as a good iOS citizen (documentation).

0.54.2

Released March 31, 2016

Fixed

  • Messages of failed preconditions are no longer lost when GRDB is built in Release configuration. Fixes #37.

0.54.1

Released March 29, 2016

This release restores CocoaPods support for iOS 9.0+ and macOS 10.11+. We'll try to bring back CocoaPods support for iOS 8.0+ or macOS 10.9+ in a further release.

0.54.0

Released March 29, 2016

New

  • FetchedRecordsController helps feeding a UITableView with the results returned from a database request (documentation). Many thanks to Pascal Edmond for this grandiose feature.

  • The standard Swift string properties capitalizedString, lowercaseString, uppercaseString, localizedCapitalizedString, localizedLowercaseString, localizedUppercaseString are available for your database requests (documentation).

  • The standard Swift comparison functions caseInsensitiveCompare, localizedCaseInsensitiveCompare, localizedCompare, localizedStandardCompare and unicodeCompare are available for your database requests (documentation).

Fixed

  • The query interface uppercaseString and lowercaseString no longer invoke the non unicode aware UPPER and LOWER SQLite functions. They instead call the standard Swift String properties uppercaseString and lowercaseString.

Breaking Change

  • The following method has changed its signature:

    protocol RowConvertible {
    mutating func awakeFromFetch(row row: Row)
}

0.53.0

Released March 25, 2016

Fixed

  • Row.value() and DatabaseValue.value() now raise a fatal error when they can not convert a non-NULL value to the requested type (documentation), effectively preventing silent data loss.

    Use the new DatabaseValue.failableValue() method if you need the old behavior that returned nil for failed conversions.

New

  • Row.databaseValue(atIndex:) and Row.databaseValue(named:) expose the DatabaseValues of a row.
  • DatabaseValue.failableValue() returns nil when a non-NULL value can not be converted to the requested type.

0.52.1

Released March 24, 2016

Fixed

  • The query interface now generates robust SQL for explicit boolean comparisons.

    // SELECT * FROM "pointOfInterests" WHERE "favorite"
PointOfInterest.filter(favorite == true).fetchAll(db)

    Previous versions used to generate fragile comparisons to 0 and 1 which did badly interpret true values such as 2.

0.52.0

Released March 21, 2016

New

  • Swift 2.2, and Xcode 7.3
  • Row adopts the standard Equatable protocol.

0.51.2

Released March 14, 2016

Fixed

  • A race condition that could prevent Configuration.fileAttributes from being applied to some database files.

0.51.1

Released March 13, 2016

Nothing new, but performance improvements

0.51.0

Released March 13, 2016

New

  • Support for file attributes

    var config = Configuration()
config.fileAttributes = [NSFileProtectionKey: NSFileProtectionComplete]
let dbPool = DatabasePool(path: ".../db.sqlite", configuration: config)

    GRDB will take care of applying them to the database file and all its derivatives (-wal and -shm files created by the WAL mode, as well as temporary files).

0.50.1

Released March 12, 2016

Fixed

  • A database connection won't close as long as there is a database sequence being iterated.

0.50.0

Released March 12, 2016

New

  • Database updates no longer need to be executed in a closure:

    // Before:
try dbQueue.inDatabase { db in
    try db.execute("CREATE TABLE ...")
    let person = Person(...)
    try person.insert(db)
}

// New:
try dbQueue.execute("CREATE TABLE ...")
let person = Person(...)
try person.insert(dbQueue)

  • DatabaseQueue and DatabasePool both adopt the new DatabaseReader and DatabaseWriter protocols.

Breaking Changes

  • The following methods have changed their signatures:

    protocol MutablePersistable {
    mutating func insert(db: DatabaseWriter) throws
    func update(db: DatabaseWriter) throws
    mutating func save(db: DatabaseWriter) throws
    func delete(db: DatabaseWriter) throws -> Bool
    func exists(db: DatabaseReader) -> Bool
}

protocol Persistable {
    func insert(db: DatabaseWriter) throws
    func save(db: DatabaseWriter) throws
}

class Record {
    func insert(db: DatabaseWriter) throws
    func update(db: DatabaseWriter) throws
    func save(db: DatabaseWriter) throws
    func delete(db: DatabaseWriter) throws -> Bool
    func exists(db: DatabaseReader) -> Bool
}

0.49.0

Released March 11, 2016

New

  • Read-only database pools grant you with concurrent reads on a database, without activating the WAL mode.

  • All fetchable types can now be fetched directly from database queues and pools:

    // Before:
let persons = dbQueue.inDatabase { db in
    Person.fetchAll(db)
}

// New:
let persons = Person.fetchAll(dbQueue)

Breaking Changes

  • Transaction observers are no longer added to Database instances, but to DatabaseQueue and DatabasePool.

0.48.0

Released March 10, 2016

New

  • DatabaseQueue.releaseMemory() and DatabasePool.releaseMemory() claim non-essential memory (documentation)

Breaking Changes

  • Custom functions and collations are no longer added to Database instances, but to DatabaseQueue and DatabasePool.

0.47.0

Released March 10, 2016

New

0.46.0

Released March 5, 2016

New

  • Improved counting support in the query interface (documentation)

Breaking Changes

  • Swift enums that behave like other database values now need to declare DatabaseValueConvertible adoption. The DatabaseIntRepresentable, DatabaseInt32Representable, DatabaseInt64Representable and DatabaseStringRepresentable protocols have been removed (documentation)

0.45.1

Released February 11, 2016

Fixed

  • Restored iOS 7 compatibility

0.45.0

Released February 9, 2016

Breaking Change

0.44.0

Released February 9, 2016

Fixed

  • row.value(named:) and row[_] reliably returns the value for the leftmost case-insensitive matching column.
  • A memory leak

New

Support for more SQL expressions in the query interface:

  • IN (subquery)
  • EXISTS (subquery)

0.43.1

Released February 4, 2016

Fixed

  • SQL queries ending with a semicolon followed by whitespace characters no longer throw errors.

0.43.0

Released February 1, 2016

Breaking Changes

  • Static method RowConvertible.fromRow(_:Row) has been replaced by a regular conversion initializer RowConvertible.init(_:Row) (documentation)

0.42.1

Released January 29, 2016

Fixed

0.42.0

Released January 28, 2016

New

  • The query interface lets you write pure Swift instead of SQL (documentation):

    let wines = Wine.filter(origin == "Burgundy").order(price).fetchAll(db)

Breaking Changes

  • DatabasePersistable and MutableDatabasePersistable protocols have been renamed Persistable and MutablePersistable (documentation)
  • DatabaseTableMapping protocol has been renamed TableMapping (documentation)

0.41.0

Released January 17, 2016

New

You can now register several database observers, thanks to @pakko972 (documentation):

  • Database.addTransactionObserver()
  • Database.removeTransactionObserver()

Breaking Changes

  • Configuration.transactionObserver has been removed.

0.40.0

Released January 14, 2016

New

  • Various performance improvements
  • Statement.unsafeSetArguments(_) binds arguments in a prepared statement without checking if arguments fit.

0.39.1

Released January 13, 2016

New

Fixed

  • Fixed the change tracking of Record subclasses that mangle the case of column names.

0.39.0

Released January 11, 2016

Breaking Changes

  • Removed partial update introduced in 0.38.0.

0.38.2

Released January 10, 2016

Fixed

  • Preconditions on invalid statements arguments are restored.

0.38.1

Released January 10, 2016

New

0.38.0

Released January 8, 2016

New

  • Record.update() and DatabasePersistable.update() can execute partial updates:

    try person.update(db)                    // Full update
try person.update(db, columns: ["age"])  // Only updates the age column

Breaking Changes

  • Statement.arguments is no longer optional.

  • Your Record subclasses and DatabasePersistable types that provide custom implementation of update must use the signature below:

    func update(db: Database, columns: [String]? = nil) throws

0.37.1

Released January 7, 2016

Fixed

  • Remove method fromRow() from NSData, NSDate, NSNull, NSNumber, NSString and NSURL, which should have been removed in v0.36.0.

0.37.0

Released January 7, 2016

Fixed

  • A named argument such as :name can now be used several times in a statement.
  • Validation of statement arguments is much more solid (and tested).

New

  • Database.execute() can now execute several statements separated by a semicolon.

  • Statement.validateArguments(_) throws an error if the arguments parameter doesn't match the prepared statement:

    let statement = try db.selectStatement("SELECT * FROM persons WHERE id = ?")
// OK
try statement.validateArguments([1])
// Error: wrong number of statement arguments: 2
try statement.validateArguments([1, 2])

Breaking Changes

  • Database.executeMultiStatement(sql) has been removed. To execute several SQL statements separated by a semicolon, use Database.execute() instead.

0.36.0

Released December 28, 2015

Fixed

  • DatabaseValueConvertible no longer inherits from RowConvertible.
  • Database.execute() now accepts SQL queries that fetch rows (#15).

Breaking Changes

  • Methods that return prepared statements can now throw errors (documentation).
  • Row(dictionary:) has been renamed Row(_:).
  • RowConvertible.awakeFromFetch() now takes a database argument (documentation).

0.35.0

Released December 22, 2015

The Record class has been refactored so that it gets closer from the RowConvertible and DatabasePersistable protocols. It also makes it easier to write subclasses that have non-optional properties.

Methods names that did not match Swift 3 API Design Guidelines have been refactored.

New

  • Float adopts DatabaseValueConvertible, and can be stored and fetched from the database without Double conversion (documentation).

Breaking Changes

Record (documentation):

  • Record.storedDatabaseDictionary has been renamed persistentDictionary.
  • Record.reload() has been removed. You have to provide your own implementation, should you need reloading.
  • Record.init(row: Row) has been renamed Record.init(_ row: Row) (unlabelled row argument).
  • Record.updateFromRow() has been removed. Override init(_ row: Row) instead.
  • Record.didInsertWithRowID(_:forColumn:) should be overridden by Record subclasses that are interested in their row ids.
  • Record.databaseEdited has been renamed hasPersistentChangedValues.
  • Record.databaseChanges has been renamed persistentChangedValues and now returns [String: DatabaseValue?], the dictionary of old values for changed columns.

Row:

  • Row.value(named:) and Row.dataNoCopy(named:) returns nil if no such column exists in the row. It used to crash with a fatal error (documentation).

DatabasePersistable:

  • DatabasePersistable.storedDatabaseDictionary has been renamed persistentDictionary (documentation).

DatabaseValue:

  • DatabaseValue has no public initializers. To create one, use DatabaseValue.Null, or the fact that Int, String, etc. adopt the DatabaseValueConvertible protocol: 1.databaseValue, "foo".databaseValue (documentation).

DatabaseMigrator:

  • DatabaseMigrator.registerMigrationWithoutForeignKeyChecks(_:_:) has been renamed DatabaseMigrator.registerMigration(_:withDisabledForeignKeyChecks:migrate:) (documentation).

0.34.0

Released December 14, 2015

New

  • DatabaseValueConvertible now inherits from RowConvertible.

Breaking Changes

  • RowConvertible no longer requires an init(row:Row) initializer, but a static func fromRow(_:Row) -> Self factory method.
  • RowConvertible dictionary initializers have been removed.

0.33.0

Released December 11, 2015

New

  • The DatabasePersistable and MutableDatabasePersistable protocols grant any adopting type the persistence methods that used to be reserved to subclasses of Record (#12)
  • Database.clearSchemaCache()

Breaking Changes

  • RecordError has been renamed PersistenceError
  • Record.databaseTableName() now returns a non-optional String.

0.32.2

Released December 3, 2015

Fixed

  • Errors thrown by update statements expose the correct statement arguments.

0.32.1

Released December 2, 2015

Fixed

  • DatabaseCollation did incorrectly process strings provided by sqlite.

0.32.0

Released November 23, 2015

New

  • DatabaseCollation let you inject custom string comparison functions into SQLite.
  • DatabaseValue adopts Hashable.
  • DatabaseValue.isNull is true if a database value is NULL.
  • DatabaseValue.storage exposes the underlying SQLite storage (NULL, INTEGER, REAL, TEXT, BLOB).

0.31.0

Released November 19, 2015

New

  • DatabaseFunction lets you define custom SQL functions.

0.30.0

Released November 17, 2015

Fixed

  • Prepared statements won't execute unless their arguments are all set.

0.29.0

Released November 14, 2015

New

  • DatabaseValue.init?(object: AnyObject) initializer.
  • StatementArguments.Default is the preferred sentinel for functions that have an optional arguments parameter.

Breaking Changes

  • Row.init?(dictionary: NSDictionary) is now a failable initializer which returns nil if the NSDictionary contains invalid values.
  • RowConvertible.init?(dictionary: NSDictionary) is now a failable initializer which returns nil if the NSDictionary contains invalid values.
  • StatementArguments.init?(_ array: NSArray) is now a failable initializer which returns nil if the NSArray contains invalid values.
  • StatementArguments.init?(_ dictionary: NSDictionary) is now a failable initializer which returns nil if the NSDictionary contains invalid values.
  • All methods that used to have an StatementArguments? parameter with nil default value now have a non-optional StatementArguments parameter with StatementArguments.Default as a default value. This makes sure failable StatementArguments initializers don't let invalid inputs sneak in your queries.

0.28.0

Released November 13, 2015

Breaking Change

  • The methods of protocol TransactionObserverType are no longer optional.

0.27.0

Released November 4, 2015

New

  • DatabaseCoder reads and stores objects that conform to NSCoding in the database.
  • Database.inTransaction() executes a block inside a database transaction.
  • DatabaseMigrator.registerMigrationWithoutForeignKeyChecks() let you make arbitrary changes to the database schema, as described at https://www.sqlite.org/lang_altertable.html#otheralter.

Breaking Changes

  • Record.delete returns a Bool which tells whether a database row was deleted or not.

0.26.1

Released October 31, 2015

Fixed repository mess introduced by 0.26.0

0.26.0

Released October 31, 2015

Breaking Changes

  • The fetch(:primaryKeys:), fetchAll(:primaryKeys:) and fetchOne(:primaryKey:) methods have been renamed fetch(:keys:), fetchAll(:keys:) and fetchOne(:key:).

0.25.0

Released October 29, 2015

Fixed

  • Record.reload(_) is no longer a final method.
  • GRDB always crashes when you try to convert a database NULL to a non-optional value.

New

  • CGFloat can be stored and read from the database.
  • Person.fetch(_:primaryKeys:) returns a sequence of objects with matching primary keys.
  • Person.fetchAll(_:primaryKeys:) returns an array of objects with matching primary keys.
  • Person.fetch(_:keys:) returns a sequence of objects with matching keys.
  • Person.fetchAll(_:keys:) returns an array of objects with matching keys.

0.24.0

Released October 14, 2015

Fixed

  • Restored iOS 7 compatibility

0.23.0

Released October 13, 2015

New

  • Row() initializes an empty row.

Breaking Changes

  • NSData is now the canonical type for blobs. The former intermediate Blob type has been removed.
  • DatabaseValue.dataNoCopy() has turned useless, and has been removed.

0.22.0

Released October 8, 2015

New

  • Database.sqliteConnection: the raw SQLite connection, suitable for SQLite C API.
  • Statement.sqliteStatement: the raw SQLite statement, suitable for SQLite C API.

0.21.0

Released October 1, 2015

Fixed

  • RowConvertible.awakeFromFetch(_) is declared as mutating.

New

  • Improved value extraction errors.

  • Row.hasColumn(_)

  • RowConvertible and Record get a dictionary initializer for free:

    class Person: Record { ... }
let person = Person(dictionary: ["name": "Arthur", "birthDate": nil])

  • Improved Foundation support:

    Row(dictionary: NSDictionary)
Row.toDictionary() -> NSDictionary

  • Int32 and Int64 enums are supported via DatabaseInt32Representable and DatabaseInt64Representable.

Breaking Changes

  • TraceFunction is now defined as (String) -> ()

0.20.0

Released September 29, 2015

New

  • Support for NSURL

Breaking Changes

  • The improved TransactionObserverType protocol lets adopting types modify the database after a successful commit or rollback, and abort a transaction with an error.

0.19.0

Released September 28, 2015

New

  • The Configuration.transactionObserver lets you observe database changes.

0.18.0

Released September 26, 2015

Fixed

  • It is now mandatory to provide values for all arguments of an SQL statement. GRDB used to assume NULL for missing ones.

New

  • Row.dataNoCopy(atIndex:) and Row.dataNoCopy(named:).
  • Blob.dataNoCopy
  • DatabaseValue.dataNoCopy

Breaking Changes

  • String.fetch... now returns non-optional values. Use Optional<String>.fetch... when values may be NULL.

0.17.0

Released September 24, 2015

New

  • Performance improvements.
  • You can extract non-optional values from Row and DatabaseValue.
  • Types that adopt SQLiteStatementConvertible on top of the DatabaseValueConvertible protocol are granted with faster database access.

Breaking Changes

  • Rows can be reused during a fetch query iteration. Use row.copy() to keep one.
  • Database sequences are now of type DatabaseSequence.
  • Blob and NSData relationships are cleaner.

0.16.0

Released September 14, 2015

New

  • Configuration.busyMode let you specify how concurrent connections should handle database locking.
  • Configuration.transactionType let you specify the default transaction type.

Breaking changes

  • Default transaction type has changed from EXCLUSIVE to IMMEDIATE.

0.15.0

Released September 12, 2015

Fixed

  • Usage assertions used to be disabled. They are activated again.

Breaking changes

  • DatabaseQueue.inDatabase and DatabaseQueue.inTransaction are no longer reentrant.

0.14.0

Released September 12, 2015

Fixed

  • DatabaseQueue.inTransaction() no longer crashes when SQLite returns a SQLITE_BUSY error code.

Breaking changes

  • Database.updateStatement(_:) is no longer a throwing method.
  • DatabaseQueue.inTransaction() is now declared as throws, not rethrows.

0.13.0

Released September 10, 2015

New

  • DatabaseQueue.inDatabase and DatabaseQueue.inTransaction are now reentrant. You can't open a transaction inside another, though.
  • Record.copy() returns a copy of the receiver.
  • Row[columnName] and Row.value(named:) are now case-insensitive.

Breaking changes

  • Requires Xcode 7.0 (because of #2)
  • RowModel has been renamed Record.
  • Record.copyDatabaseValuesFrom has been removed in favor of Record.copy().
  • Record.awakeFromFetch() now takes a row argument.

0.12.0

Released September 6, 2015

New

  • RowConvertible and DatabaseTableMapping protocols grant any type the fetching methods that used to be a privilege of RowModel.
  • Row.columnNames returns the names of columns in the row.
  • Row.databaseValues returns the database values in the row.
  • Blob.init(bytes:length:) is a new initializer.
  • DatabaseValueConvertible can now be adopted by non-final classes.
  • NSData, NSDate, NSNull, NSNumber and NSString adopt DatabaseValueConvertible and can natively be stored and fetched from a database.

Breaking changes

  • DatabaseDate has been removed (replaced by built-in NSDate support).
  • DatabaseValueConvertible: init?(dbValue:) has been replaced by static func fromDatabaseValue(_:) -> Self?
  • Blob.init(_:) has been replaced with Blob.init(data:) and Blob.init(dataNoCopy:).
  • RowModel.edited has been renamed RowModel.databaseEdited.
  • RowModel.databaseTable has been replaced with RowModel.databaseTableName() which returns a String.
  • RowModel.setDatabaseValue(_:forColumn:) has been removed. Use and override RowModel.updateFromRow(_:) instead.
  • RowModel.didFetch() has been renamed RowModel.awakeFromFetch()

0.11.0

Released September 4, 2015

Breaking changes

The fetching methods are now available on the fetched type themselves:

dbQueue.inDatabase { db in
    Row.fetch(db, "SELECT ...", arguments: ...)        // AnySequence<Row>
    Row.fetchAll(db, "SELECT ...", arguments: ...)     // [Row]
    Row.fetchOne(db, "SELECT ...", arguments: ...)     // Row?
    
    String.fetch(db, "SELECT ...", arguments: ...)     // AnySequence<String?>
    String.fetchAll(db, "SELECT ...", arguments: ...)  // [String?]
    String.fetchOne(db, "SELECT ...", arguments: ...)  // String?
    
    Person.fetch(db, "SELECT ...", arguments: ...)     // AnySequence<Person>
    Person.fetchAll(db, "SELECT ...", arguments: ...)  // [Person]
    Person.fetchOne(db, "SELECT ...", arguments: ...)  // Person?
}

0.10.0

Released September 4, 2015

New

  • DatabaseValue adopts DatabaseValueConvertible: a fetched value can be used as an argument of another query, without having to convert the raw database value into a regular Swift type.
  • Row.init(dictionary) lets you create a row from scratch.
  • RowModel.didFetch() is an overridable method that is called after a RowModel has been fetched or reloaded.
  • RowModel.updateFromRow(row) is an overridable method that helps updating compound properties that do not fit in a single column, such as CLLocationCoordinate2D.

0.9.0

Released August 25, 2015

Fixed

  • Reduced iOS Deployment Target to 8.0, and macOS Deployment Target to 10.9.
  • DatabaseQueue.inTransaction() is now declared as rethrows.

Breaking changes

  • Requires Xcode 7 beta 6
  • QueryArguments has been renamed StatementArguments.

0.8.0

Released August 18, 2015

New

  • RowModel.exists(db) returns whether a row model has a matching row in the database.
  • Statement.arguments property gains a public setter.
  • Database.executeMultiStatement(sql) can execute several SQL statements separated by a semi-colon (#6 by peter-ss)

Breaking changes

  • UpdateStatement.Changes has been renamed DatabaseChanges (#6 by peter-ss).

0.7.0

Released July 30, 2015

New

  • RowModel.delete(db) returns whether a database row was deleted or not.

Breaking changes

  • RowModelError.InvalidPrimaryKey has been replaced by a fatal error.

0.6.0

Released July 30, 2015

New

  • DatabaseDate can read dates stored as Julian Day Numbers.
  • Int32 can be stored and fetched.

0.5.0

Released July 22, 2015

New

  • DatabaseDate handles storage of NSDate in the database.
  • DatabaseDateComponents handles storage of NSDateComponents in the database.

Fixed

  • RowModel.save(db) calls RowModel.insert(db) or RowModel.update(db) so that eventual overridden versions of insert or update are invoked.
  • QueryArguments(NSArray) and QueryArguments(NSDictionary) now accept NSData elements.

Breaking changes

  • "Bindings" has been renamed "QueryArguments", and bindings parameters renamed arguments.
  • Reusable statements no longer expose any setter for their arguments property, and no longer accept any arguments in their initializer. To apply arguments, give them to the execute() and fetch() methods.
  • RowModel.isEdited and RowModel.setEdited() have been replaced by the RowModel.edited property.

0.4.0

Released July 12, 2015

Fixed

  • RowModel.save(db) makes its best to store values in the database. In particular, when the row model has a non-nil primary key, it will insert when there is no row to update. It used to throw RowModelNotFound in this case.

v0.3.0

Released July 11, 2015

New

  • Blob.init?(NSData?)

    Creates a Blob from NSData. Returns nil if and only if data is nil or zero-length (SQLite can't store empty blobs).

  • RowModel.isEdited

    A boolean that indicates whether the row model has changes that have not been saved.

    This flag is purely informative: it does not alter the behavior the update() method, which executes an UPDATE statement in every cases.

    But you can prevent UPDATE statements that are known to be pointless, as in the following example:

    let json = ...

// Fetches or create a new person given its ID:
let person = Person.fetchOne(db, primaryKey: json["id"]) ?? Person()

// Apply json payload:
person.updateFromJSON(json)

// Saves the person if it is edited (fetched then modified, or created):
if person.isEdited {
    person.save(db) // inserts or updates
}

  • RowModel.copyDatabaseValuesFrom(_:)

    Updates a row model with values of another one.

  • DatabaseValue adopts Equatable.

Breaking changes

  • RowModelError.UnspecifiedTable and RowModelError.InvalidDatabaseDictionary have been replaced with fatal errors because they are programming errors.

v0.2.0

Released July 9, 2015

Breaking changes

  • Requires Xcode 7 beta 3

New

  • RowModelError.InvalidDatabaseDictionary: new error case that helps you designing a fine RowModel subclass.

v0.1.0

Released July 9, 2015

Initial release