Configuration

Overview

You create a Configuration before opening a database connection:

var config = Configuration()
config.readonly = true
config.maximumReaderCount = 2  // (DatabasePool only) The default is 5

let dbQueue = try DatabaseQueue( // or DatabasePool
    path: "/path/to/database.sqlite",
    configuration: config)

See Database Connections.

Frequent Use Cases

Tracing SQL Statements

You can setup a tracing function that prints out all executed SQL requests with prepareDatabase(_:) and trace(options:_:):

var config = Configuration()
config.prepareDatabase { db in
    db.trace { print("SQL> \($0)") }
}

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

// Prints "SQL> SELECT COUNT(*) FROM player"
let playerCount = dbQueue.read { db in
    try Player.fetchCount(db)
}

Public Statement Arguments

Debugging is easier when database errors and tracing functions expose the values sent to the database. Since those values may contain sensitive information, verbose logging is disabled by default. You turn it on with publicStatementArguments:

var config = Configuration()
#if DEBUG
// Protect sensitive information by enabling
// verbose debugging in DEBUG builds only.
config.publicStatementArguments = true
#endif

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

do {
    try dbQueue.write { db in
        user.name = ...
        user.location = ...
        user.address = ...
        user.phoneNumber = ...
        try user.save(db)
    }
} catch {
    // Prints sensitive information in debug builds only
    print(error)
}

Creating a Configuration

• init()

  Creates a factory configuration.

Configuring SQLite Connections

• var acceptsDoubleQuotedStringLiterals: Bool

  A boolean value indicating whether SQLite 3.29+ interprets double-quoted strings as string literals when they does not match any valid identifier.

• var busyMode: Database.BusyMode

  Defines the how SQLITE_BUSY errors are handled.

• var foreignKeysEnabled: Bool

  A boolean value indicating whether foreign key support is enabled.

• var journalMode: Configuration.JournalModeConfiguration

  Defines how the journal mode is configured when the database connection is opened.

• var readonly: Bool

  A boolean value indicating whether an SQLite connection is read-only.

• enum JournalModeConfiguration

  Defines how the journal mode is configured when the database connection is opened.

Configuring GRDB Connections

• var allowsUnsafeTransactions: Bool

  A boolean value indicating whether it is valid to leave a transaction opened at the end of a database access method.

• var label: String?

  A label that describes a database connection.

• var maximumReaderCount: Int

  The maximum number of concurrent reader connections.

• var observesSuspensionNotifications: Bool

  A boolean value indicating whether the database connection listens to the suspendNotification and resumeNotification notifications.

• var persistentReadOnlyConnections: Bool

  A boolean value indicating whether read-only connections should be kept open.

• func prepareDatabase(@escaping (Database) throws -> Void)

  Defines a function to run whenever an SQLite connection is opened.

• var publicStatementArguments: Bool

  A boolean value indicating whether statement arguments are visible in the description of database errors and trace events.

• var transactionClock: any TransactionClock

  The clock that feeds transactionDate.

• protocol TransactionClock

  A type that provides the moment of a transaction.

Configuring the Quality of Service

• var qos: DispatchQoS

  The quality of service of database accesses.

• var readQoS: DispatchQoS

  The effective quality of service of read-only database accesses.

• var writeQoS: DispatchQoS

  The effective quality of service of write database accesses.

• var targetQueue: DispatchQueue?

  The target dispatch queue for database accesses.

• var writeTargetQueue: DispatchQueue?

  The target dispatch queue for write database accesses.