Merge pull request groue#1299 from groue/dev/find

Record.find() convenience methods

Author: groue

CHANGELOG.md

@@ -102,6 +102,10 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 ---
 
+## Next Release
+
+- **New**: [#1299](https://github.com/groue/GRDB.swift/pull/1299) by [@groue](https://github.com/groue): Record.find() convenience methods
+
 ## 6.4.0
 
 Released November 28, 2022 • [diff](https://github.com/groue/GRDB.swift/compare/v6.3.1...v6.4.0)

GRDB/Documentation.docc/QueryInterface.md

@@ -23,6 +23,11 @@ Record types and the query interface build SQL queries for you.
 - ``QueryInterfaceRequest``
 - ``Table``
 
+### Errors
+
+- ``RecordError``
+- ``PersistenceError``
+
 ### Supporting Types
 
 - ``DerivableRequest``

GRDB/Record/FetchableRecord+TableRecord.swift

@@ -189,6 +189,32 @@ extension FetchableRecord where Self: TableRecord {
         }
         return try filter(key: key).fetchOne(db)
     }
+    
+    /// Returns the record identified by a primary key, or throws an error if
+    /// the record does not exist.
+    ///
+    /// For example:
+    ///
+    /// ```swift
+    /// try dbQueue.read { db in
+    ///     let player = try Player.find(db, key: 123)
+    ///     let country = try Country.find(db, key: "FR")
+    /// }
+    /// ```
+    ///
+    /// - parameters:
+    ///     - db: A database connection.
+    ///     - key: A primary key value.
+    /// - returns: A record.
+    /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or a
+    ///   ``RecordError/recordNotFound(databaseTableName:key:)`` if the record
+    ///   does not exist in the database.
+    public static func find(_ db: Database, key: some DatabaseValueConvertible) throws -> Self {
+        guard let record = try fetchOne(db, key: key) else {
+            throw recordNotFound(db, key: key)
+        }
+        return record
+    }
 }
 
 @available(OSX 10.15, iOS 13.0, tvOS 13.0, watchOS 6, *)
@@ -278,6 +304,29 @@ extension FetchableRecord where Self: TableRecord & Identifiable, ID: DatabaseVa
     public static func fetchOne(_ db: Database, id: ID) throws -> Self? {
         try filter(id: id).fetchOne(db)
     }
+    
+    /// Returns the record identified by a primary key, or throws an error if
+    /// the record does not exist.
+    ///
+    /// For example:
+    ///
+    /// ```swift
+    /// try dbQueue.read { db in
+    ///     let player = try Player.find(db, id: 123)
+    ///     let country = try Country.find(db, id: "FR")
+    /// }
+    /// ```
+    ///
+    /// - parameters:
+    ///     - db: A database connection.
+    ///     - id: A primary key value.
+    /// - returns: A record.
+    /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or a
+    ///   ``RecordError/recordNotFound(databaseTableName:key:)`` if the record
+    ///   does not exist in the database.
+    public static func find(_ db: Database, id: ID) throws -> Self {
+        try find(db, key: id)
+    }
 }
 
 extension FetchableRecord where Self: TableRecord & Hashable {
@@ -431,6 +480,32 @@ extension FetchableRecord where Self: TableRecord {
         }
         return try filter(key: key).fetchOne(db)
     }
+    
+    /// Returns the record identified by a unique key (the primary key or
+    /// any key with a unique index on it), or throws an error if the record
+    /// does not exist.
+    ///
+    /// For example:
+    ///
+    /// ```swift
+    /// try dbQueue.read { db in
+    ///     let player = try Player.find(db, key: ["name": "Arthur"])
+    /// }
+    /// ```
+    ///
+    /// - parameters:
+    ///     - db: A database connection.
+    ///     - key: A key dictionary.
+    /// - returns: A record.
+    /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or a
+    ///   ``RecordError/recordNotFound(databaseTableName:key:)`` if the record
+    ///   does not exist in the database.
+    public static func find(_ db: Database, key: [String: (any DatabaseValueConvertible)?]) throws -> Self {
+        guard let record = try filter(key: key).fetchOne(db) else {
+            throw recordNotFound(key: key)
+        }
+        return record
+    }
 }
 
 extension FetchableRecord where Self: TableRecord & Hashable {

GRDB/Record/FetchableRecord.swift

@@ -75,6 +75,9 @@ import Foundation
 /// - ``fetchAll(_:keys:)-4c8no``
 /// - ``fetchSet(_:keys:)-e6uy``
 /// - ``fetchOne(_:key:)-3f3hc``
+/// - ``find(_:id:)``
+/// - ``find(_:key:)-4kry5``
+/// - ``find(_:key:)-1dfbe``
 ///
 /// ### Fetching Record by Key
 ///

GRDB/Record/MutablePersistableRecord+DAO.swift

@@ -226,12 +226,12 @@ final class DAO<Record: MutablePersistableRecord> {
         return statement
     }
 
-    /// Throws a PersistenceError.recordNotFound error
-    func makeRecordNotFoundError() -> Error {
+    /// Throws a RecordError.recordNotFound error
+    func recordNotFound() throws -> Never {
         let key = Dictionary(uniqueKeysWithValues: primaryKey.columns.map {
             ($0, persistenceContainer[caseInsensitive: $0]?.databaseValue ?? .null)
         })
-        return PersistenceError.recordNotFound(
+        throw RecordError.recordNotFound(
             databaseTableName: databaseTableName,
             key: key)
     }

GRDB/Record/MutablePersistableRecord+Save.swift

@@ -377,7 +377,7 @@ extension MutablePersistableRecord {
                     columns: columns,
                     selection: selection,
                     fetch: fetch)
-            } catch PersistenceError.recordNotFound(databaseTableName: type(of: self).databaseTableName, key: key) {
+            } catch RecordError.recordNotFound(databaseTableName: type(of: self).databaseTableName, key: key) {
                 // No row was updated: fallback on insert.
             }
         }

GRDB/Record/MutablePersistableRecord+Update.swift

@@ -39,7 +39,7 @@ extension MutablePersistableRecord {
     /// - parameter columns: The columns to update.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     public func update<Columns>(
@@ -83,7 +83,7 @@ extension MutablePersistableRecord {
     /// - parameter columns: The columns to update.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     public func update<Columns>(
@@ -115,7 +115,7 @@ extension MutablePersistableRecord {
     ///   is used.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     public func update(
@@ -158,7 +158,7 @@ extension MutablePersistableRecord {
     /// - returns: Whether the record had changes.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     /// - SeeAlso: updateChanges(_:with:)
     @discardableResult
@@ -202,7 +202,7 @@ extension MutablePersistableRecord {
     /// - returns: Whether the record had changes.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @discardableResult
     @inlinable // allow specialization so that empty callbacks are removed
@@ -233,7 +233,7 @@ extension MutablePersistableRecord {
     ///   conflict policy is `IGNORE`.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     public func updateAndFetch(
@@ -257,7 +257,7 @@ extension MutablePersistableRecord {
     ///   the conflict policy is `IGNORE`.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     public func updateAndFetch<T: FetchableRecord & TableRecord>(
@@ -285,7 +285,7 @@ extension MutablePersistableRecord {
     ///   in case of a failed update due to the `IGNORE` conflict policy.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     public mutating func updateChangesAndFetch(
@@ -314,7 +314,7 @@ extension MutablePersistableRecord {
     ///   conflict policy.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     public mutating func updateChangesAndFetch<T: FetchableRecord & TableRecord>(
@@ -358,7 +358,7 @@ extension MutablePersistableRecord {
     /// - returns: The result of the `fetch` function.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     /// - precondition: `selection` is not empty.
     @inlinable // allow specialization so that empty callbacks are removed
@@ -419,7 +419,7 @@ extension MutablePersistableRecord {
     /// - returns: The result of the `fetch` function.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     /// - precondition: `selection` is not empty.
     @inlinable // allow specialization so that empty callbacks are removed
@@ -462,7 +462,7 @@ extension MutablePersistableRecord {
     /// - returns: The result of the `fetch` function.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     /// - precondition: `selection` is not empty.
     @inlinable // allow specialization so that empty callbacks are removed
@@ -497,7 +497,7 @@ extension MutablePersistableRecord {
     /// - returns: The result of the `fetch` function.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     /// - precondition: `selection` is not empty.
     @inlinable // allow specialization so that empty callbacks are removed
@@ -529,7 +529,7 @@ extension MutablePersistableRecord {
     ///   conflict policy is `IGNORE`.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     @available(iOS 15.0, tvOS 15.0, watchOS 8.0, macOS 12.0, *) // SQLite 3.35.0+
@@ -554,7 +554,7 @@ extension MutablePersistableRecord {
     ///   the conflict policy is `IGNORE`.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     @available(iOS 15.0, tvOS 15.0, watchOS 8.0, macOS 12.0, *) // SQLite 3.35.0+
@@ -583,7 +583,7 @@ extension MutablePersistableRecord {
     ///   in case of a failed update due to the `IGNORE` conflict policy.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     @available(iOS 15.0, tvOS 15.0, watchOS 8.0, macOS 12.0, *) // SQLite 3.35.0+
@@ -613,7 +613,7 @@ extension MutablePersistableRecord {
     ///   conflict policy.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     @inlinable // allow specialization so that empty callbacks are removed
     @available(iOS 15.0, tvOS 15.0, watchOS 8.0, macOS 12.0, *) // SQLite 3.35.0+
@@ -658,7 +658,7 @@ extension MutablePersistableRecord {
     /// - returns: The result of the `fetch` function.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     /// - precondition: `selection` is not empty.
     @inlinable // allow specialization so that empty callbacks are removed
@@ -720,7 +720,7 @@ extension MutablePersistableRecord {
     /// - returns: The result of the `fetch` function.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     /// - precondition: `selection` is not empty.
     @inlinable // allow specialization so that empty callbacks are removed
@@ -764,7 +764,7 @@ extension MutablePersistableRecord {
     /// - returns: The result of the `fetch` function.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     /// - precondition: `selection` is not empty.
     @inlinable // allow specialization so that empty callbacks are removed
@@ -800,7 +800,7 @@ extension MutablePersistableRecord {
     /// - returns: The result of the `fetch` function.
     /// - throws: A ``DatabaseError`` whenever an SQLite error occurs, or any
     ///   error thrown by the persistence callbacks defined by the record type,
-    ///   or ``PersistenceError/recordNotFound(databaseTableName:key:)`` if the
+    ///   or ``RecordError/recordNotFound(databaseTableName:key:)`` if the
     ///   primary key does not match any row in the database.
     /// - precondition: `selection` is not empty.
     @inlinable // allow specialization so that empty callbacks are removed
@@ -942,12 +942,12 @@ extension MutablePersistableRecord {
             returning: selection)
         else {
             // Nil primary key
-            throw dao.makeRecordNotFoundError()
+            try dao.recordNotFound()
         }
         let returned = try fetch(statement)
         if db.changesCount == 0 {
             // No row was updated
-            throw dao.makeRecordNotFoundError()
+            try dao.recordNotFound()
         }
         let updated = PersistenceSuccess(persistenceContainer: dao.persistenceContainer)
         return (updated, returned)

GRDB/Record/MutablePersistableRecord.swift

@@ -73,7 +73,6 @@
 /// - ``update(_:onConflict:columns:)-5hxyx``
 /// - ``updateChanges(_:onConflict:from:)``
 /// - ``updateChanges(_:onConflict:modify:)``
-/// - ``PersistenceError``
 ///
 /// ### Updating a Record and Fetching the Updated Row
 ///
@@ -343,28 +342,6 @@ extension MutablePersistableRecord {
     }
 }
 
-/// An error thrown by persistence methods of the
-/// ``MutablePersistableRecord`` protocol.
-public enum PersistenceError: Error {
-    /// Thrown by ``MutablePersistableRecord`` updating methods, when no
-    /// matching row could be found and updated.
-    ///
-    /// - parameters:
-    ///     - databaseTableName: The table of the unfound record.
-    ///     - key: The key of the unfound record (column and values).
-    case recordNotFound(databaseTableName: String, key: [String: DatabaseValue])
-}
-
-extension PersistenceError: CustomStringConvertible {
-    public var description: String {
-        switch self {
-        case let .recordNotFound(databaseTableName: databaseTableName, key: key):
-            let row = Row(key) // For nice output
-            return "Key not found in table \(databaseTableName): \(row.description)"
-        }
-    }
-}
-
 /// The `MutablePersistableRecord` protocol uses this type in order to handle
 /// SQLite conflicts when records are inserted or updated.
 ///