mirror of
https://github.com/groue/GRDB.swift
synced 2026-11-22 04:00:39 +00:00
235 lines
8.6 KiB
Swift
235 lines
8.6 KiB
Swift
import Foundation
|
|
import Dispatch
|
|
|
|
/// Configuration for a DatabaseQueue or DatabasePool.
|
|
public struct Configuration {
|
|
|
|
// MARK: - Misc options
|
|
|
|
/// If true, foreign key constraints are checked.
|
|
///
|
|
/// Default: true
|
|
public var foreignKeysEnabled: Bool = true
|
|
|
|
/// If true, database modifications are disallowed.
|
|
///
|
|
/// Default: false
|
|
public var readonly: Bool = false
|
|
|
|
/// The configuration 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 configuration label is also used to name Database connections (the
|
|
/// `Database.description` property), and the various dispatch queues
|
|
/// created by GRDB, visible in debugging sessions and crash logs.
|
|
///
|
|
/// Those connection names and dispatch queue labels are intended for
|
|
/// debugging only. Their format may change between GRDB releases.
|
|
/// Applications should not depend on connection names and dispatch
|
|
/// queue labels.
|
|
///
|
|
/// If the configuration label is nil, the current GRDB implementation uses
|
|
/// the following names:
|
|
///
|
|
/// - `GRDB.DatabaseQueue`: the (unique) connection of a DatabaseQueue
|
|
/// - `GRDB.DatabasePool.writer`: the (unique) writer connection of
|
|
/// a DatabasePool
|
|
/// - `GRDB.DatabasePool.reader.N`, where N is 1, 2, ...: one of the reader
|
|
/// connection(s) of a DatabasePool. N 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 connection of a DatabaseSnapshot.
|
|
/// N grows with the number of snapshots.
|
|
///
|
|
/// If the configuration label is not nil, for example "MyDatabase", the
|
|
/// current GRDB implementation uses the following names:
|
|
///
|
|
/// - `MyDatabase`: the (unique) connection of a DatabaseQueue
|
|
/// - `MyDatabase.writer`: the (unique) writer connection of a DatabasePool
|
|
/// - `MyDatabase.reader.N`, where N is 1, 2, ...: one of the reader
|
|
/// connection(s) of a DatabasePool. N may get bigger than the maximum
|
|
/// number of concurrent readers, as SQLite connections get closed and new
|
|
/// ones are opened.
|
|
/// - `MyDatabase.snapshot.N`: the connection of a DatabaseSnapshot. N grows
|
|
/// with the number of snapshots.
|
|
///
|
|
/// The default configuration label is nil.
|
|
public var label: String? = nil
|
|
|
|
/// If false, SQLite from version 3.29.0 will not interpret a double-quoted
|
|
/// string as a string literal if it does not match any valid identifier.
|
|
///
|
|
/// For example:
|
|
///
|
|
/// // Error: no such column: foo
|
|
/// let name = try String.fetchOne(db, sql: """
|
|
/// SELECT "foo" FROM "player"
|
|
/// """)
|
|
///
|
|
/// When true, or before version 3.29.0, such strings are interpreted as
|
|
/// string literals, as in the example below. This is a well known SQLite
|
|
/// [misfeature](https://sqlite.org/quirks.html#dblquote).
|
|
///
|
|
/// // Success: "foo"
|
|
/// let name = try String.fetchOne(db, sql: """
|
|
/// SELECT "foo" FROM "player"
|
|
/// """)
|
|
///
|
|
/// - Recommended value: false
|
|
/// - Default value: false
|
|
public var acceptsDoubleQuotedStringLiterals = false
|
|
|
|
/// When true, the `Database.suspendNotification` and
|
|
/// `Database.resumeNotification` suspend and resume the database. Database
|
|
/// suspension helps avoiding the [`0xdead10cc`
|
|
/// exception](https://developer.apple.com/library/archive/technotes/tn2151/_index.html).
|
|
///
|
|
/// During suspension, all database accesses but reads in WAL mode may throw
|
|
/// a DatabaseError of code `SQLITE_INTERRUPT`, or `SQLITE_ABORT`. You can
|
|
/// check for those error codes with the
|
|
/// `DatabaseError.isInterruptionError` property.
|
|
///
|
|
/// [**Experimental**](http://github.com/groue/GRDB.swift#what-are-experimental-features)
|
|
public var observesSuspensionNotifications = false
|
|
|
|
// MARK: - Managing SQLite Connections
|
|
|
|
private var setups: [(Database) throws -> Void] = []
|
|
|
|
/// The function argument 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")
|
|
/// }
|
|
///
|
|
/// This method can be called several times. The setup functions are run in
|
|
/// the same order.
|
|
public mutating func prepareDatabase(_ setup: @escaping (Database) throws -> Void) {
|
|
setups.append(setup)
|
|
}
|
|
|
|
// MARK: - Transactions
|
|
|
|
/// The default kind of transaction.
|
|
///
|
|
/// Default: deferred
|
|
public var defaultTransactionKind: Database.TransactionKind = .deferred
|
|
|
|
/// 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
|
|
public var allowsUnsafeTransactions: Bool = false
|
|
|
|
// MARK: - Concurrency
|
|
|
|
/// The behavior in case of SQLITE_BUSY error. See https://www.sqlite.org/rescode.html#busy
|
|
///
|
|
/// Default: immediateError
|
|
public var busyMode: Database.BusyMode = .immediateError
|
|
|
|
/// The behavior in case of SQLITE_BUSY error, for read-only connections.
|
|
/// If nil, GRDB picks a default one.
|
|
var readonlyBusyMode: Database.BusyMode? = nil
|
|
|
|
/// The maximum number of concurrent readers (applies to database
|
|
/// pools only).
|
|
///
|
|
/// Default: 5
|
|
public var maximumReaderCount: Int = 5
|
|
|
|
/// 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
|
|
public var qos: DispatchQoS = .default
|
|
|
|
/// 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
|
|
public var targetQueue: DispatchQueue? = nil
|
|
|
|
// MARK: - Factory Configuration
|
|
|
|
/// Creates a factory configuration
|
|
public init() { }
|
|
|
|
// MARK: - Not Public
|
|
|
|
var threadingMode: Database.ThreadingMode = .`default`
|
|
var SQLiteConnectionDidOpen: (() -> Void)?
|
|
var SQLiteConnectionWillClose: ((SQLiteConnection) -> Void)?
|
|
var SQLiteConnectionDidClose: (() -> Void)?
|
|
var SQLiteOpenFlags: Int32 {
|
|
let readWriteFlags = readonly ? SQLITE_OPEN_READONLY : (SQLITE_OPEN_CREATE | SQLITE_OPEN_READWRITE)
|
|
return threadingMode.SQLiteOpenFlags | readWriteFlags
|
|
}
|
|
|
|
func setUp(_ db: Database) throws {
|
|
for f in setups {
|
|
try f(db)
|
|
}
|
|
}
|
|
|
|
func identifier(defaultLabel: String, purpose: String? = nil) -> String {
|
|
(self.label ?? defaultLabel) + (purpose.map { "." + $0 } ?? "")
|
|
}
|
|
|
|
func makeDispatchQueue(label: String) -> DispatchQueue {
|
|
if let targetQueue = targetQueue {
|
|
return DispatchQueue(label: label, target: targetQueue)
|
|
} else {
|
|
return DispatchQueue(label: label, qos: qos)
|
|
}
|
|
}
|
|
}
|