DatabaseQueue

public final class DatabaseQueue : DatabaseWriter

A DatabaseQueue serializes access to an SQLite database.

  • The database configuration

    Declaration

    Swift

    public var configuration: Configuration { get }
  • The path to the database file; it is :memory: for in-memory databases.

    Declaration

    Swift

    public var path: String { get }
  • 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.

  • Free as much memory as possible.

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

    See also setupMemoryManagement(application:)

    Declaration

    Swift

    public func releaseMemory()
  • Listens to UIApplicationDidEnterBackgroundNotification and UIApplicationDidReceiveMemoryWarningNotification in order to release as much memory as possible.

    • param application: The UIApplication that will start a background task to let the database queue release its memory when the application enters background.

    Declaration

    Swift

    public func setupMemoryManagement(in application: UIApplication)
  • 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.

    Starting SQLite 3.8.0 (iOS 8.2+, OSX 10.10+, custom SQLite builds and SQLCipher), attempts to write in the database from this meethod throw a DatabaseError of resultCode SQLITE_READONLY.

    Throws

    The error thrown by the block.

    Declaration

    Swift

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

    Parameters

    block

    A block that accesses the database.

  • This method is deprecated. Use concurrentRead instead.

    Synchronously executes block.

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

    Starting SQLite 3.8.0 (iOS 8.2+, OSX 10.10+, custom SQLite builds and SQLCipher), attempts to write in the database from this meethod throw a DatabaseError of resultCode SQLITE_READONLY.

    Declaration

    Swift

    @available(*, deprecated, message: "Use concurrentRead instead")
    public func readFromCurrentState(_ block: @escaping (Database) -> Void)
  • Declaration

    Swift

    public func concurrentRead<T>(_ block: @escaping (Database) throws -> T) -> Future<T>
  • Synchronously executes a block in a protected dispatch queue, wrapped inside a transaction.

    If the block throws an error, the transaction is rollbacked and the error is rethrown.

    try dbQueue.write { db in
        try Player(...).insert(db)
    }
    

    This method is not reentrant.

    Throws

    An eventual database error, or the error thrown by the block.

    Declaration

    Swift

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

    Parameters

    block

    A block that executes SQL statements.

  • Synchronously executes a block in a protected dispatch queue, wrapped inside a transaction.

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

    try dbQueue.inTransaction { db in
        try Player(...).insert(db)
        return .commit
    }
    

    This method is not reentrant.

    Throws

    The error thrown by the block.

    Declaration

    Swift

    public func inTransaction(_ kind: Database.TransactionKind? = nil, _ block: (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.

    block

    A block that executes SQL statements and return either .commit or .rollback.

  • Synchronously executes a block in a protected dispatch queue, and returns its 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>(_ block: (Database) throws -> T) rethrows -> T

    Parameters

    block

    A block that accesses the database.

  • Synchronously executes a block in a protected dispatch queue, and returns its 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>(_ block: (Database) throws -> T) rethrows -> T
  • Add or redefine an SQL function.

    let fn = DatabaseFunction("succ", argumentCount: 1) { dbValues in
        guard let int = Int.fromDatabaseValue(dbValues[0]) else {
            return nil
        }
        return int + 1
    }
    dbQueue.add(function: fn)
    try dbQueue.read { db in
        try Int.fetchOne(db, "SELECT succ(1)") // 2
    }
    

    Declaration

    Swift

    public func add(function: DatabaseFunction)
  • Remove an SQL function.

    Declaration

    Swift

    public func remove(function: DatabaseFunction)
  • Add or redefine a collation.

    let collation = DatabaseCollation("localized_standard") { (string1, string2) in
        return (string1 as NSString).localizedStandardCompare(string2)
    }
    dbQueue.add(collation: collation)
    try dbQueue.write { db in
        try db.execute("CREATE TABLE file (name TEXT COLLATE LOCALIZED_STANDARD")
    }
    

    Declaration

    Swift

    public func add(collation: DatabaseCollation)
  • Remove a collation.

    Declaration

    Swift

    public func remove(collation: DatabaseCollation)