Database
public final class Database : CustomStringConvertible, CustomDebugStringConvertible
A Database connection.
You don’t create a database directly. Instead, you use a DatabaseQueue, or a DatabasePool:
let dbQueue = DatabaseQueue(...)
// The Database is the `db` in the closure:
try dbQueue.write { db in
try Player(...).insert(db)
}
-
The raw SQLite connection, suitable for the SQLite C API. It is constant, until close() sets it to nil.
Declaration
Swift
public var sqliteConnection: SQLiteConnection?
-
The error logging function.
Quoting https://www.sqlite.org/errlog.html:
SQLite can be configured to invoke a callback function containing an error code and a terse error message whenever anomalies occur. This mechanism is very helpful in tracking obscure problems that occur rarely and in the field. Application developers are encouraged to take advantage of the error logging facility of SQLite in their products, as it is very low CPU and memory cost but can be a huge aid for debugging.
Declaration
Swift
public static var logError: LogErrorFunction? { get set }
-
The database configuration
Declaration
Swift
public let configuration: Configuration
-
Declaration
Swift
public let description: String
-
Declaration
Swift
public var debugDescription: String { get }
-
The rowID of the most recently inserted row.
If no row has ever been inserted using this database connection, returns zero.
For more detailed information, see https://www.sqlite.org/c3ref/last_insert_rowid.html
Declaration
Swift
public var lastInsertedRowID: Int64 { get }
-
The number of rows modified, inserted or deleted by the most recent successful INSERT, UPDATE or DELETE statement.
For more detailed information, see https://www.sqlite.org/c3ref/changes.html
Declaration
Swift
public var changesCount: Int { get }
-
The total number of rows modified, inserted or deleted by all successful INSERT, UPDATE or DELETE statements since the database connection was opened.
For more detailed information, see https://www.sqlite.org/c3ref/total_changes.html
Declaration
Swift
public var totalChangesCount: Int { get }
-
True if the database connection is currently in a transaction.
Declaration
Swift
public var isInsideTransaction: Bool { get }
-
The last error code
Declaration
Swift
public var lastErrorCode: ResultCode { get }
-
The last error message
Declaration
Swift
public var lastErrorMessage: String? { get }
-
The maximum number of arguments accepted by an SQLite statement.
For example, requests such as the one below must make sure the
ids
array does not contain more thanmaximumStatementArgumentCount
elements:let ids: [Int] = ... try dbQueue.write { db in try Player.deleteAll(db, keys: ids) }
See https://www.sqlite.org/limits.html and
SQLITE_LIMIT_VARIABLE_NUMBER
.Declaration
Swift
public var maximumStatementArgumentCount: Int { get }
-
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 } db.add(function: fn) try Int.fetchOne(db, sql: "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) } db.add(collation: collation) try db.execute(sql: "CREATE TABLE files (name TEXT COLLATE localized_standard")
Declaration
Swift
public func add(collation: DatabaseCollation)
-
Remove a collation.
Declaration
Swift
public func remove(collation: DatabaseCollation)
-
Registers a tracing function.
For example:
// Trace all SQL statements executed by the database var configuration = Configuration() configuration.prepareDatabase { db in db.trace(options: .statement) { event in print("SQL: \(event)") } } let dbQueue = try DatabaseQueue(path: "...", configuration: configuration)
Pass an empty options set in order to stop database tracing:
// Stop tracing db.trace(options: [])
See https://www.sqlite.org/c3ref/trace_v2.html for more information.
Declaration
Swift
public func trace(options: TracingOptions = .statement, _ trace: ((TraceEvent) -> Void)? = nil)
Parameters
options
The set of desired event kinds. Defaults to
.statement
, which notifies all executed database statements.trace
the tracing function.
-
Runs a WAL checkpoint.
See https://www.sqlite.org/wal.html and https://www.sqlite.org/c3ref/wal_checkpoint_v2.html for more information.
Declaration
Swift
@discardableResult public func checkpoint(_ kind: Database.CheckpointMode = .passive, on dbName: String? = "main") throws -> (walFrameCount: Int, checkpointedFrameCount: Int)
Parameters
kind
The checkpoint mode (default passive)
dbName
The database name (default “main”)
Return Value
A tuple:
walFrameCount
: the total number of frames in the log filecheckpointedFrameCount
: the total number of checkpointed frames in the log file
-
When this notification is posted, databases which were opened with the
Configuration.observesSuspensionNotifications
flag are suspended.Declaration
Swift
public static let suspendNotification: Notification.Name
-
When this notification is posted, databases which were opened with the
Configuration.observesSuspensionNotifications
flag are resumed.Declaration
Swift
public static let resumeNotification: Notification.Name
-
Executes a block inside a database transaction.
try dbQueue.inDatabase do { try db.inTransaction { try db.execute(sql: "INSERT ...") return .commit } }
If the block throws an error, the transaction is rollbacked and the error is rethrown.
This method is not reentrant: you can’t nest transactions.
Throws
The error thrown by the block.Declaration
Swift
public func inTransaction(_ kind: TransactionKind? = nil, _ block: () throws -> 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.
-
Executes a block inside a savepoint.
try dbQueue.inDatabase do { try db.inSavepoint { try db.execute(sql: "INSERT ...") return .commit } }
If the block throws an error, the savepoint is rollbacked and the error is rethrown.
This method is reentrant: you can nest savepoints.
Throws
The error thrown by the block.Declaration
Swift
public func inSavepoint(_ block: () throws -> TransactionCompletion) throws
Parameters
block
A block that executes SQL statements and return either .commit or .rollback.
-
Begins a database transaction.
Throws
The error thrown by the block.Declaration
Swift
public func beginTransaction(_ kind: TransactionKind? = nil) 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.
-
Rollbacks a database transaction.
Declaration
Swift
public func rollback() throws
-
Commits a database transaction.
Declaration
Swift
public func commit() throws
-
Clears the database schema cache.
You may need to clear the cache manually if the database schema is modified by another connection.
Declaration
Swift
public func clearSchemaCache()
-
Returns whether a table exists in the main or temp schema.
Declaration
Swift
public func tableExists(_ name: String) throws -> Bool
-
Returns whether a table is an internal SQLite table.
Those are tables whose name begins with
sqlite_
andpragma_
.For more information, see https://www.sqlite.org/fileformat2.html
Declaration
Swift
public static func isSQLiteInternalTable(_ tableName: String) -> Bool
-
Returns whether a table is an internal SQLite table.
Those are tables whose name begins with
sqlite_
andpragma_
.For more information, see https://www.sqlite.org/fileformat2.html
Declaration
Swift
@available(*, deprecated, message: "Use Database.isSQLiteInternalTable(_:﹚ static method instead.") public func isSQLiteInternalTable(_ tableName: String) -> Bool
-
Returns whether a table is an internal GRDB table.
Those are tables whose name begins with “grdb_”.
Declaration
Swift
public static func isGRDBInternalTable(_ tableName: String) -> Bool
-
Returns whether a table is an internal GRDB table.
Those are tables whose name begins with “grdb_”.
Declaration
Swift
@available(*, deprecated, message: "Use Database.isGRDBInternalTable(_:﹚ static method instead.") public func isGRDBInternalTable(_ tableName: String) -> Bool
-
Returns whether a view exists in the main or temp schema.
Declaration
Swift
public func viewExists(_ name: String) throws -> Bool
-
Returns whether a trigger exists in the main or temp schema.
Declaration
Swift
public func triggerExists(_ name: String) throws -> Bool
-
The primary key for table named
tableName
.All tables have a primary key, even when it is not explicit. When a table has no explicit primary key, the result is the hidden “rowid” column.
Throws
A DatabaseError if table does not exist.Declaration
Swift
public func primaryKey(_ tableName: String) throws -> PrimaryKeyInfo
-
The indexes on table named
tableName
.Only indexes on columns are returned. Indexes on expressions are not returned.
SQLite does not define any index for INTEGER PRIMARY KEY columns: this method does not return any index that represents the primary key.
If you want to know if a set of columns uniquely identify a row, prefer
table(_:hasUniqueKey:)
instead.Throws
A DatabaseError if table does not exist.Declaration
Swift
public func indexes(on tableName: String) throws -> [IndexInfo]
-
True if a sequence of columns uniquely identifies a row, that is to say if the columns are the primary key, or if there is a unique index on them.
Declaration
Swift
public func table<T: Sequence>( _ tableName: String, hasUniqueKey columns: T) throws -> Bool where T.Iterator.Element == String
-
The foreign keys defined on table named
tableName
.Throws
A DatabaseError if table does not exist.Declaration
Swift
public func foreignKeys(on tableName: String) throws -> [ForeignKeyInfo]
-
Returns a cursor over foreign key violations in the database.
Declaration
Swift
public func foreignKeyViolations() throws -> RecordCursor<ForeignKeyViolation>
-
Returns a cursor over foreign key violations in the table.
Declaration
Swift
public func foreignKeyViolations(in tableName: String) throws -> RecordCursor<ForeignKeyViolation>
-
Throws a DatabaseError of extended code
SQLITE_CONSTRAINT_FOREIGNKEY
if there exists a foreign key violation in the database.Declaration
Swift
public func checkForeignKeys() throws
-
Throws a DatabaseError of extended code
SQLITE_CONSTRAINT_FOREIGNKEY
if there exists a foreign key violation in the table.Declaration
Swift
public func checkForeignKeys(in tableName: String) throws
-
The columns in the table, or view, named
tableName
.Throws
A DatabaseError if table does not exist.Declaration
Swift
public func columns(in tableName: String) throws -> [ColumnInfo]
-
Returns a new prepared statement that can be reused.
let statement = try db.makeStatement(sql: "SELECT * FROM player WHERE id = ?") let player1 = try Player.fetchOne(statement, arguments: [1])! let player2 = try Player.fetchOne(statement, arguments: [2])! let statement = try db.makeStatement(sql: "INSERT INTO player (name) VALUES (?)") try statement.execute(arguments: ["Arthur"]) try statement.execute(arguments: ["Barbara"])
Throws
A DatabaseError whenever SQLite could not parse the sql query.Declaration
Swift
public func makeStatement(sql: String) throws -> Statement
Parameters
sql
An SQL query.
Return Value
A Statement.
-
Returns a new prepared statement that can be reused.
let statement = try db.makeStatement(literal: "SELECT * FROM player WHERE id = ?") let player1 = try Player.fetchOne(statement, arguments: [1])! let player2 = try Player.fetchOne(statement, arguments: [2])! let statement = try db.makeStatement(literal: "INSERT INTO player (name) VALUES (?)") try statement.execute(arguments: ["Arthur"]) try statement.execute(arguments: ["Barbara"])
Throws
A DatabaseError whenever SQLite could not parse the sql query.Precondition
No argument must be set, or all arguments must be set. An error is raised otherwise.
// OK try makeStatement(literal: """ SELECT COUNT(*) FROM player WHERE score > ? """) try makeStatement(literal: """ SELECT COUNT(*) FROM player WHERE score > \(1000) """) // NOT OK try makeStatement(literal: """ SELECT COUNT(*) FROM player WHERE color = ? AND score > \(1000) """)
Parameters
sqlLiteral
An
SQL
literal.Return Value
A Statement.
-
Returns a new prepared statement that can be reused.
let statement = try db.makeSelectStatement(sql: "SELECT * FROM player WHERE id = ?") let player1 = try Player.fetchOne(statement, arguments: [1])! let player2 = try Player.fetchOne(statement, arguments: [2])!
Throws
A DatabaseError whenever SQLite could not parse the sql query.Declaration
Swift
@available(*, deprecated, renamed: "makeStatement(sql:﹚") public func makeSelectStatement(sql: String) throws -> Statement
Parameters
sql
An SQL query.
Return Value
A Statement.
-
Returns a new prepared statement that can be reused.
Throws
A DatabaseError whenever SQLite could not parse the sql query.Precondition
No argument must be set, or all arguments must be set. An error is raised otherwise.
// OK try makeSelectStatement(literal: """ SELECT COUNT(*) FROM player WHERE score > ? """) try makeSelectStatement(literal: """ SELECT COUNT(*) FROM player WHERE score > \(1000) """) // NOT OK try makeSelectStatement(literal: """ SELECT COUNT(*) FROM player WHERE color = ? AND score > \(1000) """)
Declaration
Parameters
sqlLiteral
An
SQL
literal.Return Value
A Statement.
-
Returns a prepared statement that can be reused.
let statement = try db.cachedStatement(sql: "SELECT * FROM player WHERE id = ?") let player1 = try Player.fetchOne(statement, arguments: [1])! let player2 = try Player.fetchOne(statement, arguments: [2])! let statement = try db.cachedStatement(sql: "INSERT INTO player (name) VALUES (?)") try statement.execute(arguments: ["Arthur"]) try statement.execute(arguments: ["Barbara"])
The returned statement may have already been used: it may or may not contain values for its eventual arguments.
Throws
A DatabaseError whenever SQLite could not parse the sql query.Declaration
Swift
public func cachedStatement(sql: String) throws -> Statement
Parameters
sql
An SQL query.
Return Value
A Statement.
-
Returns a prepared statement that can be reused.
let statement = try db.cachedStatement(literal: "SELECT * FROM player WHERE id = ?") let player1 = try Player.fetchOne(statement, arguments: [1])! let player2 = try Player.fetchOne(statement, arguments: [2])! let statement = try db.cachedStatement(literal: "INSERT INTO player (name) VALUES (?)") try statement.execute(arguments: ["Arthur"]) try statement.execute(arguments: ["Barbara"])
Throws
A DatabaseError whenever SQLite could not parse the sql query.Precondition
No argument must be set, or all arguments must be set. An error is raised otherwise.
// OK try cachedStatement(literal: """ SELECT COUNT(*) FROM player WHERE score > ? """) try cachedStatement(literal: """ SELECT COUNT(*) FROM player WHERE score > \(1000) """) // NOT OK try cachedStatement(literal: """ SELECT COUNT(*) FROM player WHERE color = ? AND score > \(1000) """)
Parameters
sqlLiteral
An
SQL
literal.Return Value
A Statement.
-
Returns a prepared statement that can be reused.
let statement = try db.cachedSelectStatement(sql: "SELECT COUNT(*) FROM player WHERE score > ?") let moreThanTwentyCount = try Int.fetchOne(statement, arguments: [20])! let moreThanThirtyCount = try Int.fetchOne(statement, arguments: [30])!
The returned statement may have already been used: it may or may not contain values for its eventual arguments.
Throws
A DatabaseError whenever SQLite could not parse the sql query.Declaration
Swift
@available(*, deprecated, renamed: "cachedStatement(sql:﹚") public func cachedSelectStatement(sql: String) throws -> Statement
Parameters
sql
An SQL query.
Return Value
A Statement.
-
Returns a prepared statement that can be reused.
let statement = try db.cachedSelectStatement(literal: "SELECT COUNT(*) FROM player WHERE score > \(20)") let moreThanTwentyCount = try Int.fetchOne(statement)!
Throws
A DatabaseError whenever SQLite could not parse the sql query.Precondition
No argument must be set, or all arguments must be set. An error is raised otherwise.
// OK try cachedSelectStatement(literal: """ SELECT COUNT(*) FROM player WHERE score > ? """) try cachedSelectStatement(literal: """ SELECT COUNT(*) FROM player WHERE score > \(1000) """) // NOT OK try cachedSelectStatement(literal: """ SELECT COUNT(*) FROM player WHERE color = ? AND score > \(1000) """)
Declaration
Parameters
sqlLiteral
An
SQL
literal.Return Value
A Statement.
-
Returns a new prepared statement that can be reused.
let statement = try db.makeUpdateStatement(sql: "INSERT INTO player (name) VALUES (?)") try statement.execute(arguments: ["Arthur"]) try statement.execute(arguments: ["Barbara"])
Throws
A DatabaseError whenever SQLite could not parse the sql query.Declaration
Swift
@available(*, deprecated, renamed: "makeStatement(sql:﹚") public func makeUpdateStatement(sql: String) throws -> Statement
Parameters
sql
An SQL query.
Return Value
An UpdateStatement.
-
Returns a new prepared statement that can be reused.
Throws
A DatabaseError whenever SQLite could not parse the sql query.Precondition
No argument must be set, or all arguments must be set. An error is raised otherwise.
// OK try makeUpdateStatement(literal: """ UPDATE player SET name = ? """) try makeUpdateStatement(literal: """ UPDATE player SET name = \("O'Brien") """) // NOT OK try makeUpdateStatement(literal: """ UPDATE player SET name = ?, score = \(10) """)
Declaration
Parameters
sqlLiteral
An
SQL
literal.Return Value
A Statement.
-
Returns a prepared statement that can be reused.
let statement = try db.cachedUpdateStatement(sql: "INSERT INTO player (name) VALUES (?)") try statement.execute(arguments: ["Arthur"]) try statement.execute(arguments: ["Barbara"])
The returned statement may have already been used: it may or may not contain values for its eventual arguments.
Throws
A DatabaseError whenever SQLite could not parse the sql query.Declaration
Swift
@available(*, deprecated, renamed: "cachedStatement(sql:﹚") public func cachedUpdateStatement(sql: String) throws -> Statement
Parameters
sql
An SQL query.
Return Value
A Statement.
-
Returns a new prepared statement that can be reused.
Throws
A DatabaseError whenever SQLite could not parse the sql query.Precondition
No argument must be set, or all arguments must be set. An error is raised otherwise.
// OK try cachedUpdateStatement(literal: """ UPDATE player SET name = ? """) try cachedUpdateStatement(literal: """ UPDATE player SET name = \("O'Brien") """) // NOT OK try cachedUpdateStatement(literal: """ UPDATE player SET name = ?, score = \(10) """)
Declaration
Parameters
sqlLiteral
An
SQL
literal.Return Value
A Statement.
-
Returns a cursor of all SQL statements separated by semi-colons.
let statements = try db.allStatements(sql: """ INSERT INTO player (name) VALUES (?); INSERT INTO player (name) VALUES (?); INSERT INTO player (name) VALUES (?); """, arguments: ["Arthur", "Barbara", "O'Brien"]) while let statement = try statements.next() { try statement.execute() }
Throws
A DatabaseError whenever an SQLite error occurs.Precondition
Arguments must be nil, or all arguments must be set. The returned cursor will throw an error otherwise.
// OK try allStatements(sql: """ SELECT COUNT(*) FROM player WHERE score < ?; SELECT COUNT(*) FROM player WHERE score > ?; """) try allStatements(sql: """ SELECT COUNT(*) FROM player WHERE score < ?; SELECT COUNT(*) FROM player WHERE score > ?; """, arguments: [1000, 1000]) // NOT OK try allStatements(sql: """ SELECT COUNT(*) FROM player WHERE score < ?; SELECT COUNT(*) FROM player WHERE score > ?; """, arguments: [1000])
Declaration
Swift
public func allStatements(sql: String, arguments: StatementArguments? = nil) throws -> SQLStatementCursor
Parameters
sql
An SQL query.
arguments
Statement arguments.
Return Value
A cursor of
Statement
-
Returns a cursor of all SQL statements separated by semi-colons.
Literals allow you to safely embed raw values in your SQL, without any risk of syntax errors or SQL injection:
let statements = try db.allStatements(literal: """ INSERT INTO player (name) VALUES (\("Arthur")); INSERT INTO player (name) VALUES (\("Barbara")); INSERT INTO player (name) VALUES (\("O'Brien")); """) while let statement = try statements.next() { try statement.execute() }
Throws
A DatabaseError whenever an SQLite error occurs.Precondition
No argument must be set, or all arguments must be set. The returned cursor will throw an error otherwise.
// OK try allStatements(literal: """ SELECT COUNT(*) FROM player WHERE score < ?; SELECT COUNT(*) FROM player WHERE score > ?; """) try allStatements(literal: """ SELECT COUNT(*) FROM player WHERE score < \(1000); SELECT COUNT(*) FROM player WHERE score > \(1000); """) // NOT OK try allStatements(literal: """ SELECT COUNT(*) FROM player WHERE score < \(1000); SELECT COUNT(*) FROM player WHERE score > ?; """)
Declaration
Swift
public func allStatements(literal sqlLiteral: SQL) throws -> SQLStatementCursor
Parameters
sqlLiteral
An
SQL
literal.Return Value
A cursor of
Statement
-
Executes one or several SQL statements, separated by semi-colons.
try db.execute( sql: "INSERT INTO player (name) VALUES (:name)", arguments: ["name": "Arthur"]) try db.execute(sql: """ INSERT INTO player (name) VALUES (?); INSERT INTO player (name) VALUES (?); INSERT INTO player (name) VALUES (?); """, arguments: ["Arthur", "Barbara", "O'Brien"])
This method may throw a DatabaseError.
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func execute(sql: String, arguments: StatementArguments = StatementArguments()) throws
Parameters
sql
An SQL query.
arguments
Statement arguments.
-
Executes one or several SQL statements, separated by semi-colons.
Literals allow you to safely embed raw values in your SQL, without any risk of syntax errors or SQL injection:
try db.execute(literal: """ INSERT INTO player (name) VALUES (\("Arthur")) """) try db.execute(literal: """ INSERT INTO player (name) VALUES (\("Arthur")); INSERT INTO player (name) VALUES (\("Barbara")); INSERT INTO player (name) VALUES (\("O'Brien")); """)
This method may throw a DatabaseError.
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func execute(literal sqlLiteral: SQL) throws
Parameters
sqlLiteral
An
SQL
literal.
-
See BusyMode and https://www.sqlite.org/c3ref/busy_handler.html
Declaration
Swift
public typealias BusyCallback = (_ numberOfTries: Int) -> Bool
-
When there are several connections to a database, a connection may try to access the database while it is locked by another connection.
The BusyMode enum describes the behavior of GRDB when such a situation occurs:
.immediateError: The SQLITE_BUSY error is immediately returned to the connection that tries to access the locked database.
.timeout: The SQLITE_BUSY error will be returned only if the database remains locked for more than the specified duration.
.callback: Perform your custom lock handling.
To set the busy mode of a database, use Configuration:
// Wait 1 second before failing with SQLITE_BUSY let configuration = Configuration(busyMode: .timeout(1)) let dbQueue = DatabaseQueue(path: "...", configuration: configuration)
Relevant SQLite documentation:
- https://www.sqlite.org/c3ref/busy_timeout.html
- https://www.sqlite.org/c3ref/busy_handler.html
- https://www.sqlite.org/lang_transaction.html
- https://www.sqlite.org/wal.html
Declaration
Swift
public enum BusyMode
-
The available checkpoint modes.
See moreDeclaration
Swift
public enum CheckpointMode : Int32
-
Declaration
Swift
public struct CollationName : RawRepresentable, Hashable
-
An SQL column type.
try db.create(table: "player") { t in t.autoIncrementedPrimaryKey("id") t.column("title", .text) }
See https://www.sqlite.org/datatype3.html
See moreDeclaration
Swift
public struct ColumnType : RawRepresentable, Hashable
-
Declaration
Swift
public enum ConflictResolution : String
-
Declaration
Swift
public enum ForeignKeyAction : String
-
An error log function that takes an error code and message.
Declaration
Swift
public typealias LogErrorFunction = (_ resultCode: ResultCode, _ message: String) -> Void
-
An option for
See moreDatabase.trace(options:_:)
Declaration
Swift
public struct TracingOptions : OptionSet
-
An event reported by
See moreDatabase.trace(options:_:)
Declaration
Swift
public enum TraceEvent : CustomStringConvertible
-
Confirms or cancels the changes performed by a transaction or savepoint.
See moreDeclaration
Swift
@frozen public enum TransactionCompletion
-
An SQLite transaction kind. See https://www.sqlite.org/lang_transaction.html
See moreDeclaration
Swift
public enum TransactionKind : String
-
Add a transaction observer, so that it gets notified of database changes.
Declaration
Swift
public func add( transactionObserver: TransactionObserver, extent: TransactionObservationExtent = .observerLifetime)
Parameters
transactionObserver
A transaction observer.
extent
The duration of the observation. The default is the observer lifetime (observation lasts until observer is deallocated).
-
Remove a transaction observer.
Declaration
Swift
public func remove(transactionObserver: TransactionObserver)
-
Registers a closure to be executed after the next or current transaction completion.
try dbQueue.write { db in db.afterNextTransactionCommit { _ in print("success") } ... } // prints "success"
If the transaction is rollbacked, the closure is not executed.
If the transaction is committed, the closure is executed in a protected dispatch queue, serialized will all database updates.
Declaration
Swift
public func afterNextTransactionCommit(_ closure: @escaping (Database) -> Void)
-
Declaration
Swift
public enum TransactionObservationExtent
-
Deletes the synchronization triggers for a synchronized FTS4 table
Declaration
Swift
public func dropFTS4SynchronizationTriggers(forTable tableName: String) throws
-
Creates a database table.
try db.create(table: "place") { t in t.autoIncrementedPrimaryKey("id") t.column("title", .text) t.column("favorite", .boolean).notNull().default(false) t.column("longitude", .double).notNull() t.column("latitude", .double).notNull() }
See https://www.sqlite.org/lang_createtable.html and https://www.sqlite.org/withoutrowid.html
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func create( table name: String, temporary: Bool = false, ifNotExists: Bool = false, withoutRowID: Bool = false, body: (TableDefinition) -> Void) throws
Parameters
name
The table name.
temporary
If true, creates a temporary table.
ifNotExists
If false (the default), an error is thrown if the table already exists. Otherwise, the table is created unless it already exists.
withoutRowID
If true, uses WITHOUT ROWID optimization.
body
A closure that defines table columns and constraints.
-
Renames a database table.
See https://www.sqlite.org/lang_altertable.html
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func rename(table name: String, to newName: String) throws
-
Modifies a database table.
try db.alter(table: "player") { t in t.add(column: "url", .text) }
See https://www.sqlite.org/lang_altertable.html
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func alter(table name: String, body: (TableAlteration) -> Void) throws
Parameters
name
The table name.
body
A closure that defines table alterations.
-
Deletes a database table.
See https://www.sqlite.org/lang_droptable.html
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func drop(table name: String) throws
-
Creates an index.
try db.create(index: "playerByEmail", on: "player", columns: ["email"])
SQLite can also index expressions (https://www.sqlite.org/expridx.html) and use specific collations. To create such an index, use a raw SQL query.
try db.execute(sql: "CREATE INDEX ...")
Declaration
Swift
public func create( index name: String, on table: String, columns: [String], unique: Bool = false, ifNotExists: Bool = false, condition: SQLExpressible? = nil) throws
Parameters
name
The index name.
table
The name of the indexed table.
columns
The indexed columns.
unique
If true, creates a unique index.
ifNotExists
If true, no error is thrown if index already exists.
condition
If not nil, creates a partial index (see https://www.sqlite.org/partialindex.html).
-
Deletes a database index.
See https://www.sqlite.org/lang_dropindex.html
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func drop(index name: String) throws
-
Delete and recreate from scratch all indices that use this collation.
This method is useful when the definition of a collation sequence has changed.
See https://www.sqlite.org/lang_reindex.html
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func reindex(collation: Database.CollationName) throws
-
Delete and recreate from scratch all indices that use this collation.
This method is useful when the definition of a collation sequence has changed.
See https://www.sqlite.org/lang_reindex.html
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func reindex(collation: DatabaseCollation) throws
-
Creates a virtual database table.
try db.create(virtualTable: "vocabulary", using: "spellfix1")
See https://www.sqlite.org/lang_createtable.html
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func create(virtualTable name: String, ifNotExists: Bool = false, using module: String) throws
Parameters
name
The table name.
ifNotExists
If false (the default), an error is thrown if the table already exists. Otherwise, the table is created unless it already exists.
module
The name of an SQLite virtual table module.
-
Creates a virtual database table.
let module = ... try db.create(virtualTable: "book", using: module) { t in ... }
The type of the closure argument
t
depends on the type of the module argument: refer to this module’s documentation.Use this method to create full-text tables using the FTS3, FTS4, or FTS5 modules:
try db.create(virtualTable: "book", using: FTS4()) { t in t.column("title") t.column("author") t.column("body") }
See https://www.sqlite.org/lang_createtable.html
Throws
A DatabaseError whenever an SQLite error occurs.Declaration
Swift
public func create<Module: VirtualTableModule>( virtualTable tableName: String, ifNotExists: Bool = false, using module: Module, _ body: ((Module.TableDefinition) -> Void)? = nil) throws
Parameters
name
The table name.
ifNotExists
If false (the default), an error is thrown if the table already exists. Otherwise, the table is created unless it already exists.
module
a VirtualTableModule
body
An optional closure that defines the virtual table.