DatabaseWriter

public protocol DatabaseWriter : DatabaseReader

The protocol for all types that can update a database.

It is adopted by DatabaseQueue and DatabasePool.

The protocol comes with isolation guarantees that describe the behavior of adopting types in a multithreaded application.

Types that adopt the protocol can in practice provide stronger guarantees. For example, DatabaseQueue provides a stronger isolation level than DatabasePool.

Warning: Isolation guarantees stand as long as there is no external connection to the database. Should you have to cope with external connections, protect yourself with transactions, and be ready to setup a busy handler.

  • write(_:) Default implementation

    Synchronously executes database updates in a protected dispatch queue, wrapped inside a transaction, and returns the result.

    If the updates throw an error, the transaction is rollbacked and the error is rethrown.

    Eventual concurrent database updates are postponed until the transaction has completed.

    Eventual concurrent reads are guaranteed to not see any partial updates of the database until the transaction has completed.

    This method is not reentrant.

    Throws

    The error thrown by the updates, or by the wrapping transaction.

    Default Implementation

    Synchronously executes database updates in a protected dispatch queue, wrapped inside a transaction, and returns the result.

    If the updates throw an error, the transaction is rollbacked and the error is rethrown.

    Eventual concurrent database updates are postponed until the transaction has completed.

    Eventual concurrent reads are guaranteed to not see any partial updates of the database until the transaction has completed.

    This method is not reentrant.

    Throws

    The error thrown by the updates, or by the wrapping transaction.

    Declaration

    Swift

    func write<T>(_ updates: (Database) throws -> T) throws -> T

    Parameters

    updates

    The updates to the database.

  • Synchronously executes database updates in a protected dispatch queue, outside of any transaction, and returns the result.

    Eventual concurrent database updates are postponed until the updates are completed.

    Eventual concurrent reads may see partial updates unless you wrap them in a transaction.

    This method is not reentrant.

    Throws

    The error thrown by the updates.

    Declaration

    Swift

    func writeWithoutTransaction<T>(_ updates: (Database) throws -> T) rethrows -> T

    Parameters

    updates

    The updates to the database.

  • asyncWrite(_:completion:) Default implementation

    Asynchronously executes database updates in a protected dispatch queue, wrapped inside a transaction.

    If the updates throw an error, the transaction is rollbacked.

    The completion closure is always called with the result of the database updates. Its arguments are a database connection and the result of the transaction. This result is a failure if the transaction could not be committed.

    Eventual concurrent database updates are postponed until the transaction and the completion closure have completed.

    Eventual concurrent reads are guaranteed to not see any partial updates of the database until the transaction has completed.

    This method is not reentrant.

    Throws

    The error thrown by the updates, or by the wrapping transaction.

    Default Implementation

    Asynchronously executes database updates in a protected dispatch queue, wrapped inside a transaction.

    If the updates throw an error, the transaction is rollbacked.

    The completion closure is always called with the result of the database updates. Its arguments are a database connection and the result of the transaction. This result is a failure if the transaction could not be committed. The completion closure is executed in a protected dispatch queue, outside of any transaction.

    Eventual concurrent database updates are postponed until the transaction and the completion closure have completed.

    Eventual concurrent reads are guaranteed to not see any partial updates of the database until the transaction has completed.

    This method is not reentrant.

    Throws

    The error thrown by the updates, or by the wrapping transaction.

    Declaration

    Swift

    func asyncWrite<T>(_ updates: @escaping (Database) throws -> T, completion: @escaping (Database, Result<T, Error>) -> Void)

    Parameters

    updates

    The updates to the database.

    completion

    A closure that is called with the eventual transaction error.

  • Asynchronously executes database updates in a protected dispatch queue, outside of any transaction.

    Eventual concurrent reads may see partial updates unless you wrap them in a transaction.

    Declaration

    Swift

    func asyncWriteWithoutTransaction(_ updates: @escaping (Database) -> Void)
  • Synchronously executes database updates in a protected dispatch queue, outside of any transaction, and returns the result.

    Eventual concurrent database updates are postponed until the updates are completed.

    Eventual concurrent reads may see partial updates unless you wrap them in a transaction.

    This method is reentrant. It should be avoided because it fosters dangerous concurrency practices.

    Declaration

    Swift

    func unsafeReentrantWrite<T>(_ updates: (Database) throws -> T) rethrows -> T
  • Concurrently executes a read-only block in a protected dispatch queue.

    This method must be called from a writing dispatch queue, outside of any transaction. You’ll get a fatal error otherwise.

    The block argument is guaranteed to see the database in the last committed state at the moment this method is called. Eventual concurrent database updates are not visible inside the block.

    To access the fetched results, you call the wait() method of the returned future, on any dispatch queue.

    In the example below, the number of players is fetched concurrently with the player insertion. Yet the future is guaranteed to return zero:

    try writer.writeWithoutTransaction { db in
        // Delete all players
        try Player.deleteAll()
    
        // Count players concurrently
        let future = writer.concurrentRead { db in
            return try Player.fetchCount()
        }
    
        // Insert a player
        try Player(...).insert(db)
    
        // Guaranteed to be zero
        let count = try future.wait()
    }
    

    Declaration

    Swift

    func concurrentRead<T>(_ block: @escaping (Database) throws -> T) -> DatabaseFuture<T>
  • erase() Extension method

    Erases the content of the database.

    Precondition

    database is not accessed concurrently during the execution of this method.

    Declaration

    Swift

    public func erase() throws