Database

Creates a temporary database.

Creates a read-only database from a file.

Creates a read-write database from a file.

Creates a database from an existing sqlite3 * database connection handle.

true if this database is read only, false otherwise

The rowid of the most recent successful INSERT into a rowid table or virtual table

The number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement

The total number of rows inserted, modified or deleted by all INSERT, UPDATE or DELETE statements

Interrupts a long-running query.

Returns the location of the file associated with database name.

Performs a low-level SQLite database operation.

Use of this function should be avoided whenever possible

A comparator for String objects.

Adds a custom collation function.

try db.addCollation("localizedCompare", { (lhs, rhs) -> ComparisonResult in
    return lhs.localizedCompare(rhs)
})

Removes a custom collation function.

The reasons FTS5 will request tokenization

Adds a custom FTS5 tokenizer.

For example, a word tokenizer using CFStringTokenizer could be implemented as:

class WordTokenizer: FTS5Tokenizer {
    var tokenizer: CFStringTokenizer!
    var text: CFString!

    required init(arguments: [String]) {
        // Arguments not used
    }

    func set(text: String, reason: Database.FTS5TokenizationReason) {
        // Reason not used
        self.text = text as CFString
        tokenizer = CFStringTokenizerCreate(kCFAllocatorDefault, self.text, CFRangeMake(0, CFStringGetLength(self.text)), kCFStringTokenizerUnitWord, nil)
    }

    func advance() -> Bool {
        let nextToken = CFStringTokenizerAdvanceToNextToken(tokenizer)
        guard nextToken != CFStringTokenizerTokenType(rawValue: 0) else {
            return false
        }
        return true
    }

    func currentToken() -> String? {
        let tokenRange = CFStringTokenizerGetCurrentTokenRange(tokenizer)
        guard tokenRange.location != kCFNotFound /*|| tokenRange.length != 0*/ else {
            return nil
        }
        return CFStringCreateWithSubstring(kCFAllocatorDefault, text, tokenRange) as String
    }

    func copyCurrentToken(to buffer: UnsafeMutablePointer<UInt8>, capacity: Int) throws -> Int {
        let tokenRange = CFStringTokenizerGetCurrentTokenRange(tokenizer)
        var bytesConverted = 0
        let charsConverted = CFStringGetBytes(text, tokenRange, CFStringBuiltInEncodings.UTF8.rawValue, 0, false, buffer, capacity, &bytesConverted)
        guard charsConverted > 0 else {
            throw DatabaseError("Insufficient buffer size")
        }
        return bytesConverted
    }
}

A hook called when a database transaction is committed.

Sets the hook called when a database transaction is committed.

Removes the commit hook.

A hook called when a database transaction is rolled back.

Sets the hook called when a database transaction is rolled back.

Removes the rollback hook.

A hook called when a database transaction is committed in write-ahead log mode.

Sets the hook called when a database transaction is committed in write-ahead log mode.

Removes the write-ahead log commit hook.

Possible types of database row changes.

A hook called when a row is inserted, deleted, or updated in a rowid table.

Sets the hook called when a row is inserted, deleted, or updated in a rowid table.

Removes the update hook.

A hook that may be called when an attempt is made to access a locked database table.

Sets a callback that may be invoked when an attempt is made to access a locked database table.

Removes the busy handler.

Sets a busy handler that sleeps when an attempt is made to access a locked database table.

A custom SQL function.

Custom SQL function flags

Adds a custom SQL scalar function.

For example, a localized uppercase scalar function could be implemented as:

try db.addFunction("localizedUppercase", arity: 1) { values in
    let value = values.first.unsafelyUnwrapped
    switch value {
    case .text(let s):
        return .text(s.localizedUppercase())
    default:
        return value
    }
}

Adds a custom SQL aggregate function.

For example, an integer sum aggregate function could be implemented as:

class IntegerSumAggregateFunction: SQLAggregateFunction {
    func step(_ values: [DatabaseValue]) throws {
        let value = values.first.unsafelyUnwrapped
        switch value {
            case .integer(let i):
                sum += i
            default:
                throw DatabaseError("Only integer values supported")
        }
    }

    func final() throws -> DatabaseValue {
        defer {
            sum = 0
        }
        return DatabaseValue(sum)
    }

    var sum: Int64 = 0
}

Adds a custom SQL aggregate window function.

For example, an integer sum aggregate window function could be implemented as:

class IntegerSumAggregateWindowFunction: SQLAggregateWindowFunction {
    func step(_ values: [DatabaseValue]) throws {
        let value = values.first.unsafelyUnwrapped
        switch value {
            case .integer(let i):
                sum += i
            default:
                throw DatabaseError("Only integer values supported")
        }
    }

    func inverse(_ values: [DatabaseValue]) throws {
        let value = values.first.unsafelyUnwrapped
        switch value {
            case .integer(let i):
                sum -= i
            default:
                throw DatabaseError("Only integer values supported")
        }
    }

    func value() throws -> DatabaseValue {
        return DatabaseValue(sum)
    }

    func final() throws -> DatabaseValue {
        defer {
            sum = 0
        }
        return DatabaseValue(sum)
    }

    var sum: Int64 = 0
}

Removes a custom SQL scalar, aggregate, or window function.

Virtual table module options

Adds a virtual table module to the database.

Adds an eponymous virtual table module to the database.

An eponymous virtual table module presents a virtual table with the same name as the module and does not require a CREATE VIRTUAL TABLE statement to be available.

For example, an eponymous virtual table module returning the natural numbers could be implemented as:

class NaturalNumbersModule: EponymousVirtualTableModule {
    class Cursor: VirtualTableCursor {
        var _rowid: Int64 = 0

        func column(_ index: Int32) -> DatabaseValue  {
            .integer(_rowid)
        }

        func next() {
            _rowid += 1
        }

        func rowid() -> Int64 {
            _rowid
        }

        func filter(_ arguments: [DatabaseValue], indexNumber: Int32, indexName: String?) {
            _rowid = 1
        }

        var eof: Bool {
            _rowid > 2147483647
        }
    }

    required init(database: Database, arguments: [String]) {
        // database and arguments not used
    }

    var declaration: String {
        "CREATE TABLE x(value)"
    }

    var options: Database.VirtualTableModuleOptions {
        [.innocuous]
    }

    func bestIndex(_ indexInfo: inout sqlite3_index_info) -> VirtualTableModuleBestIndexResult {
        .ok
    }

    func openCursor() -> VirtualTableCursor {
        Cursor()
    }
}

Returns a compiled SQL statement.

Executes an SQL statement.

This is a shortcut for prepare(sql: sql).execute().

Executes an SQL statement and applies block to each result row.

This is a shortcut for prepare(sql: sql).results(block).

Executes one or more SQL statements and optionally applies block to each result row.

Multiple SQL statements are separated with a semicolon (;)

Possible database transaction types.

Begins a database transaction.

Rolls back the active database transaction.

Commits the active database transaction.

true if this database is in autocommit mode, false otherwise

Possible ways to complete a transaction

A series of database actions grouped into a transaction

Performs a transaction on the database.

Begins a database savepoint transaction.

Rolls back a database savepoint transaction.

Releases (commits) a database savepoint transaction.

Possible ways to complete a savepoint

A series of database actions grouped into a savepoint transaction

Performs a savepoint transaction on the database.

Possible write-ahead log (WAL) checkpoint types.

Perform a write-ahead log checkpoint on the database.

Compiles and stores an SQL statement for later use.

Returns the compiled SQL statement for key.

Stores a compiled SQL statement for later use.

Removes a compiled SQL statement.

Executes the compiled SQL statement for key and after execution resets the statement.

This method does not clear bound host parameters.

Returns or stores the compiled SQL statement for key.

A callback for reporting the progress of a database backup.

Backs up the database to the specified URL.

Available database status parameters.

Returns status information on the current and highwater values of a database parameter.

Not all parameters support both current and highwater values.

Begins a long-running read transaction on the database.

This is equivalent to the SQL BEGIN DEFERRED TRANSACTION;

Ends a long-running read transaction on the database.

This is equivalent to the SQL ROLLBACK;

Updates a long-running read transaction to make the latest database changes visible.

If there is an active read transaction it is ended before beginning a new read transaction.

Executes sql with the n parameters in values bound to the first n SQL parameters of sql and applies block to each result row.

Executes sql with value bound to SQL parameter name for each (name, value) in parameters and applies block to each result row.

Executes sql with the n parameters in values bound to the first n SQL parameters of sql and applies block to each result row.

Executes sql with value bound to SQL parameter name for each (name, value) in parameters and applies block to each result row.

Records a snapshot of the current state of a database schema.

Starts or upgrades a read transaction for a database schema to a specific snapshot.