Configuration

public struct Configuration

Configuration for a DatabaseQueue or DatabasePool.

  • If true, foreign key constraints are checked.

    Default: true

    Declaration

    Swift

    public var foreignKeysEnabled: Bool
  • If true, database modifications are disallowed.

    Default: false

    Declaration

    Swift

    public var readonly: Bool
  • The database label.

    You can query this label at runtime:

    var configuration = Configuration()
    configuration.label = "MyDatabase"
    let dbQueue = try DatabaseQueue(path: ..., configuration: configuration)
    
    try dbQueue.read { db in
        print(db.configuration.label) // Prints "MyDatabase"
    }
    

    The database label is also used to name the various dispatch queues created by GRDB, visible in debugging sessions and crash logs. However those dispatch queue labels are intended for debugging only. Their format may change between GRDB releases. Applications should not depend on the GRDB dispatch queue labels.

    If the database label is nil, the current GRDB implementation uses the following dispatch queue labels:

    • GRDB.DatabaseQueue: the (unique) dispatch queue of a DatabaseQueue
    • GRDB.DatabasePool.writer: the (unique) writer dispatch queue of a DatabasePool
    • GRDB.DatabasePool.reader.N, where N is 1, 2, …: one of the reader dispatch queue(s) of a DatabasePool. N grows with the number of SQLite connections: it may get bigger than the maximum number of concurrent readers, as SQLite connections get closed and new ones are opened.
    • GRDB.DatabasePool.snapshot.N: the dispatch queue of a DatabaseSnapshot. N grows with the number of snapshots.

    If the database label is not nil, for example MyDatabase, the current GRDB implementation uses the following dispatch queue labels:

    • MyDatabase: the (unique) dispatch queue of a DatabaseQueue
    • MyDatabase.writer: the (unique) writer dispatch queue of a DatabasePool
    • MyDatabase.reader.N, where N is 1, 2, …: one of the reader dispatch queue(s) of a DatabasePool. N grows with the number of SQLite connections: it may get bigger than the maximum number of concurrent readers, as SQLite connections get closed and new ones are opened.
    • MyDatabase.snapshot.N: the dispatch queue of a DatabaseSnapshot. N grows with the number of snapshots.

    The default label is nil.

    Declaration

    Swift

    public var label: String?
  • A function that is called on every statement executed by the database.

    Default: nil

    Declaration

    Swift

    public var trace: TraceFunction?
  • A function that is run when an SQLite connection is opened, before the connection is made available for database access methods.

    For example:

    var config = Configuration()
    config.prepareDatabase = { db in
        try db.execute(sql: "PRAGMA kdf_iter = 10000")
    }
    

    Declaration

    Swift

    public var prepareDatabase: ((Database) throws -> Void)?
  • The default kind of transaction.

    Default: deferred

    Declaration

    Swift

    public var defaultTransactionKind: Database.TransactionKind
  • If false, it is a programmer error to leave a transaction opened at the end of a database access block.

    For example:

    let dbQueue = DatabaseQueue()
    
    // fatal error: A transaction has been left opened at the end of a database access
    try dbQueue.inDatabase { db in
        try db.beginTransaction()
    }
    

    If true, one can leave opened transaction at the end of database access blocks:

    var config = Configuration()
    config.allowsUnsafeTransactions = true
    let dbQueue = DatabaseQueue(configuration: config)
    
    try dbQueue.inDatabase { db in
        try db.beginTransaction()
    }
    
    try dbQueue.inDatabase { db in
        try db.commit()
    }
    

    This configuration flag has no effect on DatabasePool readers: those never allow leaving a transaction opened at the end of a read access.

    Default: false

    Declaration

    Swift

    public var allowsUnsafeTransactions: Bool
  • The behavior in case of SQLITE_BUSY error. See https://www.sqlite.org/rescode.html#busy

    Default: immediateError

    Declaration

    Swift

    public var busyMode: Database.BusyMode
  • The maximum number of concurrent readers (applies to database pools only).

    Default: 5

    Declaration

    Swift

    public var maximumReaderCount: Int
  • qos

    The quality of service class for the work performed by the database.

    The quality of service is ignored if you supply a target queue.

    Default: .default (.unspecified on macOS < 10.10)

    Declaration

    Swift

    public var qos: DispatchQoS
  • The target queue for all database accesses.

    When you use a database pool, make sure the queue is concurrent. If it is serial, no concurrent database access can happen, and you may experience deadlocks.

    If the queue is nil, all database accesses happen in unspecified dispatch queues whose quality of service and label are determined by the qos and label Configuration properties.

    Default: nil

    Declaration

    Swift

    public var targetQueue: DispatchQueue?