DatabaseReadQueue

public final class DatabaseReadQueue

A queue providing serialized execution of read operations on a database.

Normally read queues are used for concurrent read access to databases using WAL mode.

A database read queue manages the execution of read-only database operations to ensure they occur one at a time in FIFO order. This provides thread-safe database access.

Database read operations may be submitted for synchronous or asynchronous execution.

It is possible to maintain a consistent snapshot of a database using read transactions. Changes committed to a database are not visible within a read transaction until the transaction is updated or restarted.

The interface is similar to DispatchQueue and a dispatch queue is used internally for work item management.

  • The dispatch queue used to serialize access to the underlying database connection

    Declaration

    Swift

    public let queue: DispatchQueue

  • Creates a database read queue for serialized read access to a database from a file.

    Throws

    An error if the database could not be opened

    Declaration

    Swift

    public init(url: URL, label: String, qos: DispatchQoS = .default, target: DispatchQueue? = nil) throws

    Parameters

    url

    The location of the SQLite database
    label

    The label to attach to the queue
    qos

    The quality of service class for the work performed by the database queue
    target

    The target dispatch queue on which to execute blocks

  • Creates a database read queue for serialized read access to an existing database.

    Attention

    The database queue takes ownership of database. The result of further use of database is undefined.

    Declaration

    Swift

    public init(database: Database, label: String, qos: DispatchQoS = .default, target: DispatchQueue? = nil)

    Parameters

    database

    The database to be serialized
    label

    The label to attach to the queue
    qos

    The quality of service class for the work performed by the database queue
    target

    The target dispatch queue on which to execute blocks

  • Begins a long-running read transaction on the database.

    Throws

    An error if the transaction could not be started

    Declaration

    Swift

    public func beginReadTransaction() throws

  • Ends a long-running read transaction on the database.

    Throws

    An error if the transaction could not be rolled back

    Declaration

    Swift

    public func endReadTransaction() throws

  • Updates a long-running read transaction to make the latest database changes visible.

    If there is an active read transaction it is ended before beginning a new read transaction.

    Throws

    An error if the transaction could not be rolled back or started

    Declaration

    Swift

    public func updateReadTransaction() throws

  • Performs a synchronous read operation on the database.

    Throws

    Any error thrown in block

    Declaration

    Swift

    public func sync<T>(block: (_ database: Database) throws -> (T)) rethrows -> T

    Parameters

    block

    A closure performing the database operation
    database

    A Database used for database access within block

    Return Value

    The value returned by block

  • Submits an asynchronous read operation to the database queue.

    Declaration

    Swift

    public func async(group: DispatchGroup? = nil, qos: DispatchQoS = .unspecified, block: @escaping (_ database: Database) -> (Void))

    Parameters

    group

    An optional DispatchGroup with which to associate block
    qos

    The quality of service for block
    block

    A closure performing the database operation
    database

    A Database used for database access within block

  • Creates a database read queue for serialized read access to a database from the file corresponding to the database main on a write queue.

    Note

    The QoS for the database queue is set to the QoS of writeQueue

    Throws

    An error if the database could not be opened

    Declaration

    Swift

    public convenience init(writeQueue: DatabaseQueue, label: String) throws

    Parameters

    writeQueue

    A database queue for the SQLite database
    label

    The label to attach to the queue

  • Creates a database read queue for serialized read access to a database from the file corresponding to the database main on a write queue.

    Throws

    An error if the database could not be opened

    Declaration

    Swift

    public convenience init(writeQueue: DatabaseQueue, label: String, qos: DispatchQoS, target: DispatchQueue? = nil) throws

    Parameters

    writeQueue

    A database queue for the SQLite database
    label

    The label to attach to the queue
    qos

    The quality of service class for the work performed by the database queue
    target

    The target dispatch queue on which to execute blocks