MutablePersistableRecord

public protocol MutablePersistableRecord : EncodableRecord, TableRecord

Types that adopt MutablePersistableRecord can be inserted, updated, and deleted.

  • persistenceConflictPolicy Default implementation

    The policy that handles SQLite conflicts when records are inserted or updated.

    This property is optional: its default value uses the ABORT policy for both insertions and updates, and has GRDB generate regular INSERT and UPDATE queries.

    If insertions are resolved with .ignore policy, the didInsert(with:for:) method is not called upon successful insertion, even if a row was actually inserted without any conflict.

    See https://www.sqlite.org/lang_conflict.html

    Default Implementation

    Describes the conflict policy for insertions and updates.

    The default value specifies ABORT policy for both insertions and updates, which has GRDB generate regular INSERT and UPDATE queries.

    Declaration

    Swift

    static var persistenceConflictPolicy: PersistenceConflictPolicy { get }
  • didInsert(with:for:) Default implementation

    Notifies the record that it was successfully inserted.

    Do not call this method directly: it is called for you, in a protected dispatch queue, with the inserted RowID and the eventual INTEGER PRIMARY KEY column name.

    This method is optional: the default implementation does nothing.

    struct Player : MutablePersistableRecord {
        var id: Int64?
        var name: String?
    
        mutating func didInsert(with rowID: Int64, for column: String?) {
            self.id = rowID
        }
    }
    

    Default Implementation

    Notifies the record that it was successfully inserted.

    The default implementation does nothing.

    Declaration

    Swift

    mutating func didInsert(with rowID: Int64, for column: String?)

    Parameters

    rowID

    The inserted rowID.

    column

    The name of the eventual INTEGER PRIMARY KEY column.

CRUD

  • insert(_:) Default implementation

    Executes an INSERT statement.

    This method is guaranteed to have inserted a row in the database if it returns without error.

    Upon successful insertion, the didInsert(with:for:) method is called with the inserted RowID and the eventual INTEGER PRIMARY KEY column name.

    This method has a default implementation, so your adopting types don’t have to implement it. Yet your types can provide their own implementation of insert(). In their implementation, it is recommended that they invoke the performInsert() method.

    Throws

    A DatabaseError whenever an SQLite error occurs.

    Default Implementation

    Executes an INSERT statement.

    The default implementation for insert() invokes performInsert().

    Declaration

    Swift

    mutating func insert(_ db: Database) throws

    Parameters

    db

    A database connection.

  • update(_:columns:) Default implementation

    Executes an UPDATE statement.

    This method is guaranteed to have updated a row in the database if it returns without error.

    This method has a default implementation, so your adopting types don’t have to implement it. Yet your types can provide their own implementation of update(). In their implementation, it is recommended that they invoke the performUpdate() method.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs. PersistenceError.recordNotFound is thrown if the primary key does not match any row in the database.

    Default Implementation

    Executes an UPDATE statement.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs. PersistenceError.recordNotFound is thrown if the primary key does not match any row in the database.

    Declaration

    Swift

    func update(_ db: Database, columns: Set<String>) throws

    Parameters

    db

    A database connection.

    columns

    The columns to update.

  • save(_:) Default implementation

    Executes an INSERT or an UPDATE statement so that self is saved in the database.

    If the receiver has a non-nil primary key and a matching row in the database, this method performs an update.

    Otherwise, performs an insert.

    This method is guaranteed to have inserted or updated a row in the database if it returns without error.

    This method has a default implementation, so your adopting types don’t have to implement it. Yet your types can provide their own implementation of save(). In their implementation, it is recommended that they invoke the performSave() method.

    Throws

    A DatabaseError whenever an SQLite error occurs, or errors thrown by update().

    Default Implementation

    Executes an INSERT or an UPDATE statement so that self is saved in the database.

    The default implementation for save() invokes performSave().

    Declaration

    Swift

    mutating func save(_ db: Database) throws

    Parameters

    db

    A database connection.

  • delete(_:) Default implementation

    Executes a DELETE statement.

    This method has a default implementation, so your adopting types don’t have to implement it. Yet your types can provide their own implementation of delete(). In their implementation, it is recommended that they invoke the performDelete() method.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Default Implementation

    Executes a DELETE statement.

    The default implementation for delete() invokes performDelete().

    Declaration

    Swift

    @discardableResult
    func delete(_ db: Database) throws -> Bool

    Parameters

    db

    A database connection.

    Return Value

    Whether a database row was deleted.

  • exists(_:) Default implementation

    Returns true if and only if the primary key matches a row in the database.

    This method has a default implementation, so your adopting types don’t have to implement it. Yet your types can provide their own implementation of exists(). In their implementation, it is recommended that they invoke the performExists() method.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Default Implementation

    Returns true if and only if the primary key matches a row in the database.

    The default implementation for exists() invokes performExists().

    Declaration

    Swift

    func exists(_ db: Database) throws -> Bool

    Parameters

    db

    A database connection.

    Return Value

    Whether the primary key matches a row in the database.

  • inserted(_:) Extension method

    Executes an INSERT statement so that self is saved in the database, and return the inserted record.

    Usage:

    let player = Player(id: nil, name: "Arthur")
    let insertedPlayer = try dbQueue.write { db in
        try player.inserted(db)
    }
    print(player.id)         // nil
    print(insertedPlayer.id) // some id
    

    Declaration

    Swift

    public func inserted(_ db: Database) throws -> Self
  • update(_:) Extension method

    Executes an UPDATE statement that updates all table columns.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs. PersistenceError.recordNotFound is thrown if the primary key does not match any row in the database.

    Declaration

    Swift

    public func update(_ db: Database) throws

    Parameters

    db

    A database connection.

  • updateChanges(_:from:) Extension method

    If the record has any difference from the other record, executes an UPDATE statement so that those differences and only those difference are saved in the database.

    This method is guaranteed to have saved the eventual differences in the database if it returns without error.

    For example:

    if let oldPlayer = try Player.fetchOne(db, key: 42) {
        var newPlayer = oldPlayer
        newPlayer.score += 10
        newPlayer.hasAward = true
        try newPlayer.updateChanges(db, from: oldRecord)
    }
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs. PersistenceError.recordNotFound is thrown if the primary key does not match any row in the database and record could not be updated.

    See also

    updateChanges(_:with:)

    Declaration

    Swift

    @discardableResult
    public func updateChanges<Record>(_ db: Database, from record: Record) throws -> Bool where Record : MutablePersistableRecord

    Parameters

    db

    A database connection.

    record

    The comparison record.

    Return Value

    Whether the record had changes.

  • updateChanges(_:with:) Extension method

    Mutates the record according to the provided closure, and then, if the record has any difference from its previous version, executes an UPDATE statement so that those differences and only those difference are saved in the database.

    This method is guaranteed to have saved the eventual differences in the database if it returns without error.

    For example:

    if var player = try Player.fetchOne(db, key: 42) {
        try player.updateChanges(db) {
            $0.score += 10
            $0.hasAward = true
        }
    }
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs. PersistenceError.recordNotFound is thrown if the primary key does not match any row in the database and record could not be updated.

    Declaration

    Swift

    @discardableResult
    public mutating func updateChanges(_ db: Database, with change: (inout Self) throws -> Void) throws -> Bool

    Parameters

    db

    A database connection.

    change

    A closure that modifies the record.

    Return Value

    Whether the record had changes.

  • saved(_:) Extension method

    Executes an INSERT or an UPDATE statement so that self is saved in the database, and return the saved record.

    Usage:

    let player = Player(id: nil, name: "Arthur")
    let savedPlayer = try dbQueue.write { db in
        try player.saved(db)
    }
    print(player.id)      // nil
    print(savedPlayer.id) // some id
    

    Declaration

    Swift

    public func saved(_ db: Database) throws -> Self

CRUD Internals

  • performInsert(_:) Extension method

    Don’t invoke this method directly: it is an internal method for types that adopt MutablePersistableRecord.

    performInsert() provides the default implementation for insert(). Types that adopt MutablePersistableRecord can invoke performInsert() in their implementation of insert(). They should not provide their own implementation of performInsert().

    Declaration

    Swift

    public mutating func performInsert(_ db: Database) throws
  • performUpdate(_:columns:) Extension method

    Don’t invoke this method directly: it is an internal method for types that adopt MutablePersistableRecord.

    performUpdate() provides the default implementation for update(). Types that adopt MutablePersistableRecord can invoke performUpdate() in their implementation of update(). They should not provide their own implementation of performUpdate().

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs. PersistenceError.recordNotFound is thrown if the primary key does not match any row in the database.

    Declaration

    Swift

    public func performUpdate(_ db: Database, columns: Set<String>) throws

    Parameters

    db

    A database connection.

    columns

    The columns to update.

  • performSave(_:) Extension method

    Don’t invoke this method directly: it is an internal method for types that adopt MutablePersistableRecord.

    performSave() provides the default implementation for save(). Types that adopt MutablePersistableRecord can invoke performSave() in their implementation of save(). They should not provide their own implementation of performSave().

    This default implementation forwards the job to update or insert.

    Declaration

    Swift

    public mutating func performSave(_ db: Database) throws
  • performDelete(_:) Extension method

    Don’t invoke this method directly: it is an internal method for types that adopt MutablePersistableRecord.

    performDelete() provides the default implementation for delete(). Types that adopt MutablePersistableRecord can invoke performDelete() in their implementation of delete(). They should not provide their own implementation of performDelete().

    Declaration

    Swift

    public func performDelete(_ db: Database) throws -> Bool
  • performExists(_:) Extension method

    Don’t invoke this method directly: it is an internal method for types that adopt MutablePersistableRecord.

    performExists() provides the default implementation for exists(). Types that adopt MutablePersistableRecord can invoke performExists() in their implementation of exists(). They should not provide their own implementation of performExists().

    Declaration

    Swift

    public func performExists(_ db: Database) throws -> Bool

Record Comparison

  • updateChanges(_:with:) Extension method

    Mutates the record according to the provided closure, and then, if the record has any difference from its previous version, executes an UPDATE statement so that those differences and only those difference are saved in the database.

    This method is guaranteed to have saved the eventual differences in the database if it returns without error.

    For example:

    if let player = try Player.fetchOne(db, key: 42) {
        try player.updateChanges(db) {
            $0.score += 10
            $0.hasAward = true
        }
    }
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs. PersistenceError.recordNotFound is thrown if the primary key does not match any row in the database and record could not be updated.

    Declaration

    Swift

    @discardableResult
    public func updateChanges(_ db: Database, with change: (Self) throws -> Void) throws -> Bool

    Parameters

    db

    A database connection.

    change

    A closure that modifies the record.

    Return Value

    Whether the record had changes.