DatabaseWriter

DatabaseWriter is the protocol for all types that can write into an SQLite 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.

Writing in Database

  • 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.

    It is a programmer error to call this method from another database access method:

    try writer.write { db in
    // Raises a fatal error
    try writer.write { ... )
}

    Throws

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

    Default Implementation

  • 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.

    It is a programmer error to call this method from another database access method:

    try writer.write { db in
    // Raises a fatal error
    try writer.writeWithoutTransaction { ... )
}

    Throws

    The error thrown by the updates.

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

    Updates are guaranteed an exclusive access to the database. They wait until all pending writes and reads are completed. They postpone all other writes and reads until they are completed.

    It is a programmer error to call this method from another database access method:

    try writer.write { db in
    // Raises a fatal error
    try writer.barrierWriteWithoutTransaction { ... )
}

    Throws

    The error thrown by the updates.

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

    Updates are guaranteed an exclusive access to the database. They wait until all pending writes and reads are completed. They postpone all other writes and reads until they are completed.

  • 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.

  • 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.

  • 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.

Reading from Database

  • 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()
}

Transaction Observers

Erasing the content of the database

  • erase() Extension method

    Erases the content of the database.

Claiming Disk Space