Merge branch 'development'

Author: groue

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 
 GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception: APIs flagged [**:fire: EXPERIMENTAL**](README.md#what-are-experimental-features). Those are unstable, and may break between any two minor releases of the library.
 
+#### 6.x Releases
+
+- `6.0.0` Betas - [6.0.0-beta](#600-beta)
+
 #### 5.x Releases
 
 - `5.26.x` Releases - [5.26.0](#5260)
@@ -93,6 +97,61 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 ---
 
+## 6.0.0-beta
+
+Released August 21, 2022 • [diff](https://github.com/groue/GRDB.swift/compare/v5.26.0...v6.0.0-beta)
+
+### New
+
+Upgrading your app can bring improvements: check [Migrating From GRDB 5 to GRDB 6](Documentation/GRDB6MigrationGuide.md) for some suggestions.
+
+- :star: Support for [`UPSERT`](https://www.sqlite.org/lang_UPSERT.html): `player.upsert(db)`, etc. See [Persistence Methods](README.md#persistence-methods).
+
+- :star: Support for the [`RETURNING` clause](https://www.sqlite.org/lang_returning.html): `player.insertAndFetch(db)`, `Player.deleteAndFetchAll(db)`, etc. See [Persistence Methods and the `RETURNING` clause](README.md#persistence-methods-and-the-returning-clause).
+
+- :star: [Persistence Callbacks](README.md#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](https://github.com/apple/swift-evolution/blob/main/proposals/0346-light-weight-same-type-syntax.md).
+
+- 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
+
+- :star: **[Migrating From GRDB 5 to GRDB 6](Documentation/GRDB6MigrationGuide.md)**: suggestions for improving your applications, and guidance for handling the breaking changes.
+- The [Persistence Methods](README.md#persistence-methods) chapter introduces the `upsert` method.
+- The [Persistence Methods and the `RETURNING` clause](README.md#persistence-methods-and-the-returning-clause) chapter introduces persistence methods that fetch inserted, updated and deleted values.
+- The [Persistence Callbacks](README.md#persistence-callbacks) chapter introduces the callback invoked from persistence methods, such as `didInsert`, `willSave`, etc.
+- The [DatabaseRegionObservation](README.md#databaseregionobservation) chapter was updated for the new `DatabaseRegionObservation.start` method.
+- The [Transaction Hook](README.md#transaction-hook) chapter describes the new `Database.afterNextTransaction(onCommit:onRollback:)` method.
+- The [Value Queries](README.md#value-queries) chapter explains how to distinguish a request that returns no value from a request that fetches a NULL value.
+
+### 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](README.md#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.0
 
 Released July 9, 2022 • [diff](https://github.com/groue/GRDB.swift/compare/v5.25.0...v5.26.0)

Documentation/AssociationsBasics.md

@@ -712,9 +712,9 @@ struct Author: TableRecord {
 }
 ```
 
-> :point_up: **Note**: Generally speaking, all foreign keys are supported, including composite keys that span several columns.
+> **Note**: Generally speaking, all foreign keys are supported, including composite keys that span several columns.
 >
-> :warning: **Warning**: SQLite voids foreign key constraints when one or more of a foreign key column is NULL (see [SQLite Foreign Key Support](https://www.sqlite.org/foreignkeys.html)). GRDB does not match foreign keys that involve a NULL value either.
+> **Warning**: SQLite voids foreign key constraints when one or more of a foreign key column is NULL (see [SQLite Foreign Key Support](https://www.sqlite.org/foreignkeys.html)). GRDB does not match foreign keys that involve a NULL value either.
 
 Sometimes the database schema does not define any foreign key. And sometimes, there are *several* foreign keys from a table to another.
 
@@ -1210,7 +1210,7 @@ In the description of the [joining methods] above, we have seen that you need to
 
 In this chapter, we take the reversed perspective. We list various shapes of decoded record types. When you find the type you want, you'll know the joining method you need.
 
-> :point_up: **Note**: If you don't find the type you want, chances are that you are fighting the framework, and should reconsider your position. Your escape hatch is the low-level apis described in [Decoding a Joined Request with FetchableRecord].
+> **Note**: If you don't find the type you want, chances are that you are fighting the framework, and should reconsider your position. Your escape hatch is the low-level apis described in [Decoding a Joined Request with FetchableRecord].
 
 - [`including(required:)`]
 
@@ -1435,7 +1435,7 @@ struct BookInfo: FetchableRecord, Decodable {
 let bookInfos: [BookInfo] = try BookInfo.fetchAll(db, request)
 ```
 
-> :warning: **Warning**: you can not currently chain a required association behind an optional association:
+> **Warning**: you can not currently chain a required association behind an optional association:
 >
 > ```swift
 > // Not implemented
@@ -1751,7 +1751,7 @@ Associations support more refinements:
         .fetchAll(db)
     ```
 
-> :warning: **Warning**: associations refined with `limit`, `distinct`, `group`, `having`, or association aggregates can only be used with `including(all:)`. You will get a fatal error if you use them with other joining methods: `including(required:)`, etc.
+> **Warning**: associations refined with `limit`, `distinct`, `group`, `having`, or association aggregates can only be used with `including(all:)`. You will get a fatal error if you use them with other joining methods: `including(required:)`, etc.
 
 
 ## Table Aliases
@@ -1823,7 +1823,7 @@ let request = Book.aliased(bookAlias)
     .filter(sql: "b.publishDate >= a.deathDate")
 ```
 
-> :point_up: **Note**: avoid reusing table aliases between several tables or requests, because you will get a fatal error:
+> **Note**: avoid reusing table aliases between several tables or requests, because you will get a fatal error:
 >
 > ```swift
 > // Fatal error: A TableAlias most not be used to refer to multiple tables
@@ -1832,7 +1832,7 @@ let request = Book.aliased(bookAlias)
 > let people = Person.aliased(alias)...
 > ```
 >
-> :point_up: **Note**: you can't use the `including(all:)` method and use table aliases to filter the associated records on other records:
+> **Note**: you can't use the `including(all:)` method and use table aliases to filter the associated records on other records:
 > 
 > ```swift
 > // NOT IMPLEMENTED: loading all authors along with their posthumous books
@@ -1899,15 +1899,15 @@ For example, we can start by defining base requests as extensions to the [Deriva
 
 ```swift
 // Author requests
-extension DerivableRequest where RowDecoder == Author {
+extension DerivableRequest<Author> {
     /// Filters authors by country
     func filter(country: String) -> Self {
         filter(Column("country") == country)
     }
 }
 
 // Book requests
-extension DerivableRequest where RowDecoder == Book {
+extension DerivableRequest<Book> {
     /// Filters books by author country
     func filter(authorCountry: String) -> Self {
         joining(required: Book.author.filter(country: country))
@@ -2165,8 +2165,8 @@ struct BookInfo: FetchableRecord {
     var country: Country?
     var coverImage: CoverImage?
 
-    init(row: Row) {
-        book = Book(row: row)
+    init(row: Row) throws {
+        book = try Book(row: row)
         author = row["author"]
         country = row["country"]
         coverImage = row["coverImage"]
@@ -2200,8 +2200,8 @@ struct AuthorInfo: FetchableRecord {
     var author: Author
     var books: [Book]
 
-    init(row: Row) {
-        author = Author(row: row)
+    init(row: Row) throws {
+        author = try Author(row: row)
         books = row["books"]
     }
 }
@@ -2843,7 +2843,7 @@ let request = Book.all().filter(country: "ES")
 Those methods are defined on extensions to the `DerivableRequest` protocol:
 
 ```swift
-extension DerivableRequest where RowDecoder == Author {
+extension DerivableRequest<Author> {
     func filter(country: String) -> Self {
         filter(Column("country") == country)
     }
@@ -2853,7 +2853,7 @@ extension DerivableRequest where RowDecoder == Author {
     }
 }
 
-extension DerivableRequest where RowDecoder == Book {
+extension DerivableRequest<Book> {
     func filter(country: String) -> Self {
         joining(required: Book.author.filter(country: country))
     }

Documentation/CommonTableExpressions.md

@@ -16,7 +16,7 @@ In this guide, you will learn how to:
 - [Fetch Values From Common Table Expressions]
 - Join CTEs with [Associations to Common Table Expressions]
 
-> :point_up: **Note**: most code examples will be trivial, and not very "useful". This is because the goal of this guide is to stay focused on the GRDB support for CTEs. Rich setup would just be distracting. So bring your own good ideas with you!
+> **Note**: most code examples will be trivial, and not very "useful". This is because the goal of this guide is to stay focused on the GRDB support for CTEs. Rich setup would just be distracting. So bring your own good ideas with you!
 
 
 ## Define Common Table Expressions
@@ -82,7 +82,7 @@ let counterCTE = CommonTableExpression(
         """)
 ```
 
-> :point_up: **Note**: many recursive CTEs use the `UNION ALL` SQL operator. The query interface does not provide any Swift support for it, so you'll generally have to write SQL in your definitions of recursive CTEs.
+> **Note**: many recursive CTEs use the `UNION ALL` SQL operator. The query interface does not provide any Swift support for it, so you'll generally have to write SQL in your definitions of recursive CTEs.
 
 
 ## Embed Common Table Expressions in Requests
@@ -126,13 +126,13 @@ let request = Player
     .filter(Column("name") == playerNameCTE.all())
 ```
 
-> :point_up: **Note**: the `with(_:)` method can be called as many times as a there are common table expressions in your request.
+> **Note**: the `with(_:)` method can be called as many times as a there are common table expressions in your request.
 >
-> :point_up: **Note**: the `with(_:)` method can be called at any time, as all request methods: `Player.with(...).filter(...).with(...)`.
+> **Note**: the `with(_:)` method can be called at any time, as all request methods: `Player.with(...).filter(...).with(...)`.
 >
-> :point_up: **Note**: the `with(_:)` method replaces any previously embedded CTE that has the same table name. This allows you to embed the same CTE several times if you feel like it.
+> **Note**: the `with(_:)` method replaces any previously embedded CTE that has the same table name. This allows you to embed the same CTE several times if you feel like it.
 >
-> :point_up: **Note**: the `CommonTableExpression.all()` method builds a regular [query interface request] for the content of the CTE (like `SELECT * FROM <cte name>`, not to be mismatched with the request that was used to define the CTE). You can filter this request, sort it, etc, like all query interface requests:
+> **Note**: the `CommonTableExpression.all()` method builds a regular [query interface request] for the content of the CTE (like `SELECT * FROM <cte name>`, not to be mismatched with the request that was used to define the CTE). You can filter this request, sort it, etc, like all query interface requests:
 >
 > ```swift
 > cte.all().select(...).filter(...).group(...).order(...)
@@ -234,7 +234,7 @@ Parent.including(optional: childAssociation)
 Parent.including(required: childAssociation)
 ```
 
-> :point_up: **Note**: common table expressions currently only define "to-one" associations, so the `including(all:)` joining method is unavailable.
+> **Note**: common table expressions currently only define "to-one" associations, so the `including(all:)` joining method is unavailable.
 
 CTE associations are generally built with the `association(to:on:)` method, which needs:
 

Documentation/Concurrency.md

@@ -506,7 +506,7 @@ try snapshot2.read { db in
 }
 ```
 
-> :point_up: **Note**: snapshots currently serialize all database accesses. In the future, snapshots may allow concurrent reads.
+> **Note**: snapshots currently serialize all database accesses. In the future, snapshots may allow concurrent reads.
 
 [^1]: This immutable view of the database is called [snapshot isolation](https://www.sqlite.org/isolation.html).