DatabaseQueue

public final class DatabaseQueue : DatabaseWriter

A DatabaseQueue serializes access to an SQLite database.

Configuration

Initializers

  • Opens the SQLite database at path path.

    let dbQueue = try DatabaseQueue(path: "/path/to/database.sqlite")
    

    Database connections get closed when the database queue gets deallocated.

    Throws

    A DatabaseError whenever an SQLite error occurs.

    Declaration

    Swift

    public init(path: String, configuration: Configuration = Configuration()) throws

    Parameters

    path

    The path to the database file.

    configuration

    A configuration.

  • Opens an in-memory SQLite database.

    let dbQueue = DatabaseQueue()
    

    Database memory is released when the database queue gets deallocated.

    Declaration

    Swift

    public init(configuration: Configuration = Configuration())

    Parameters

    configuration

    A configuration.

Memory management

  • Free as much memory as possible.

    This method blocks the current thread until all database accesses are completed.

    Declaration

    Swift

    public func releaseMemory()

Interrupting Database Operations

Reading from Database

  • Synchronously executes a read-only block in a protected dispatch queue, and returns its result.

    let players = try dbQueue.read { db in
        try Player.fetchAll(db)
    }
    

    This method is not reentrant.

    Attempts to write in the database from this method throw a DatabaseError of resultCode SQLITE_READONLY.

    Throws

    The error thrown by the block.

    Declaration

    Swift

    public func read<T>(_ block: (Database) throws -> T) throws -> T

    Parameters

    block

    A block that accesses the database.

  • Asynchronously executes a read-only block in a protected dispatch queue.

    let players = try dbQueue.asyncRead { dbResult in
        do {
            let db = try dbResult.get()
            let count = try Player.fetchCount(db)
        } catch {
            // Handle error
        }
    }
    

    Attempts to write in the database from this method throw a DatabaseError of resultCode SQLITE_READONLY.

    Declaration

    Swift

    public func asyncRead(_ block: @escaping (Result<Database, Error>) -> Void)

    Parameters

    block

    A block that accesses the database.

  • Declaration

    Swift

    public func concurrentRead<T>(_ block: @escaping (Database) throws -> T) -> DatabaseFuture<T>

Writing in Database

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

    If the updates throws an error, the transaction is rollbacked and the error is rethrown. If the updates return .rollback, the transaction is also rollbacked, but no error is thrown.

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

    This method is not reentrant.

    try dbQueue.writeInTransaction { db in
        db.execute(...)
        return .commit
    }
    

    Throws

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

    Declaration

    Swift

    public func inTransaction(
        _ kind: Database.TransactionKind? = nil,
        _ updates: (Database) throws -> Database.TransactionCompletion)
    throws

    Parameters

    kind

    The transaction type (default nil). If nil, the transaction type is configuration.defaultTransactionKind, which itself defaults to .deferred. See https://www.sqlite.org/lang_transaction.html for more information.

    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 accesses are postponed until the updates are completed.

    This method is not reentrant.

    Throws

    The error thrown by the updates.

    Declaration

    Swift

    public func writeWithoutTransaction<T>(_ updates: (Database) throws -> T) rethrows -> 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 accesses are postponed until the updates are completed.

    This method is not reentrant.

    Throws

    The error thrown by the updates.

    Declaration

    Swift

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

    Parameters

    updates

    The updates to the database.

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

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

    Declaration

    Swift

    public func asyncBarrierWriteWithoutTransaction(_ updates: @escaping (Database) -> Void)

    Parameters

    updates

    The updates to the database.

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

    // INSERT INTO player ...
    let players = try dbQueue.inDatabase { db in
        try Player(...).insert(db)
    }
    

    This method is not reentrant.

    Throws

    The error thrown by the block.

    Declaration

    Swift

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

    Parameters

    block

    A block that accesses the database.

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

    // INSERT INTO player ...
    try dbQueue.unsafeReentrantWrite { db in
        try Player(...).insert(db)
    }
    

    This method is reentrant. It is unsafe because it fosters dangerous concurrency practices.

    Declaration

    Swift

    public func unsafeReentrantWrite<T>(_ updates: (Database) throws -> T) rethrows -> T
  • Asynchronously executes database updates in a protected dispatch queue, outside of any transaction.

    Declaration

    Swift

    public func asyncWriteWithoutTransaction(_ updates: @escaping (Database) -> Void)