Instance Methods

The following instance methods are available globally.

  • Set cipher key for a database.
    For an encrypted database, you must call it before all other operation.
    The cipher page size defaults to 4096 in WCDB, but it defaults to 1024 in other databases. So for an existing database created by other database framework, you should set it to 1024. Otherwise, you’d better to use cipher page size with 4096 or simply call setCipherKey: interface to get better performance.

    Declaration

    Swift

    public func setCipher(key optionalKey: Data?, pageSize: Int = 4096)

    Parameters

    optionalKey

    Cipher key. Nil for no cipher.

    pageSize

    Cipher page size.

  • Set config for this database.

    Since WCDB is a multi-handle database, an executing handle will not apply this config immediately.
    Instead, all handles will run this config before its next operation.

    database.setConfig(named: "demo", with: { (handle: Handle) throws in
        try handle.exec(StatementPragma().pragma(.secureDelete, to: true))
    }, orderBy: 1)
    

    Declaration

    Swift

    public func setConfig(named name: String, with callback: @escaping Config, orderBy order: ConfigOrder)

    Parameters

    name

    The Identifier for this config

    callback

    config

    order

    The smaller number is called first

  • This interface is equivalent to database.setConfig(named: name, with: callback, orederBy: Int.max).

    Declaration

    Swift

    public func setConfig(named name: String, with callback: @escaping Config)

    Parameters

    name

    The Identifier for this config

    callback

    config

  • Set Synchronous for this database. It will disable checkpoint opti to avoid performance degradation.
    Synchronous can improve the stability of the database and reduce database damage, but there will be performance degradation.

    Declaration

    Swift

    public func setSynchronous(isFull: Bool)

    Parameters

    isFull

    enable or disable full synchronous

  • You can register a tracer to monitor the performance of all SQLs in this database.
    The database tracer will recover the global tracer for specifiy database.

    Declaration

    Swift

    public func trace(performance performanceTracer: @escaping PerformanceTracer)

    Parameters

    performanceTracer

    trace.

  • This interface is equivalent to database.setTokenizes(tokenizes)

    Declaration

    Swift

    public func setTokenizes(_ tokenizes: Tokenize...)

    Parameters

    tokenizes

    registed tokenizeName. You can use builtin tokenizer named .WCDB or .Apple

  • Setup multiple tokenizers with names for current database.

    Declaration

    Swift

    public func setTokenizes(_ tokenizes: [Tokenize])

    Parameters

    tokenizes

    registed tokenizeName. You can use builtin tokenizer named .WCDB or .Apple

  • Generation a Transaction object to do a transaction.

    Throws

    Error

    Declaration

    Swift

    public func getTransaction() throws -> Transaction

    Return Value

    Transaction

  • Prepare a specific sql.
    Note that you can use this interface to prepare a SQL that is not contained in the WCDB interface layer

    Throws

    Error

    Declaration

    Swift

    public func prepare(_ statement: Statement) throws -> CoreStatement

    Parameters

    statement

    WINQ statement

    Return Value

    CoreStatement

  • Exec a specific sql.
    Note that you can use this interface to execute a SQL that is not contained in the WCDB interface layer.

    Throws

    Error

    Declaration

    Swift

    public func exec(_ statement: Statement) throws

    Parameters

    statement

    WINQ statement

  • Check whether table exists

    Throws

    Error

    Declaration

    Swift

    public func isTableExists(_ table: String) throws -> Bool

    Parameters

    table

    The name of the table to be checked.

    Return Value

    True if table exists. False if table does not exist.

  • Get a wrapper from an existing table.

    Throws

    Error

    Declaration

    Swift

    public func getTable<Root: TableCodable>(

    Parameters

    name

    The name of the table.

    type

    A class conform to TableCodable protocol.

    Return Value

    Nil for a non-existent table.

  • This interface is equivalent begin(.immediate)

    Throws

    Error

    Declaration

    Swift

    public func begin() throws
  • Separate interface of run(transaction:)
    You should call begin, commit, rollback and all other operations in same thread.
    To do a cross-thread transaction, use getTransaction.

    Throws

    Error

    Declaration

    Swift

    public func begin(_ mode: StatementTransaction.Mode) throws
  • Separate interface of run(transaction:)
    You should call begin, commit, rollback and all other operations in same thread. To do a cross-thread transaction, use getTransaction.

    Throws

    Error

    Declaration

    Swift

    public func commit() throws
  • Separate interface of run(transaction:) You should call begin, commit, rollback and all other operations in same thread.
    To do a cross-thread transaction, use getTransaction.

    Throws

    Error

    Declaration

    Swift

    public func rollback() throws
  • Run a transaction in closure

    try database.run(transaction: { () throws -> Void in 
        try database.insert(objects: objects, intoTable: table)
    })
    

    Throws

    Error

    Declaration

    Swift

    public func run(transaction: TransactionClosure) throws

    Parameters

    transaction

    Operation inside transaction

  • Run a controlable transaction in closure

    try database.run(controlableTransaction: { () throws -> Bool in 
        try database.insert(objects: objects, intoTable: table)
        return true // return true to commit transaction and return false to rollback transaction.
    })
    

    Throws

    Error

    Declaration

    Swift

    public func run(controlableTransaction: ControlableTransactionClosure) throws

    Parameters

    controlableTransaction

    Operation inside transaction

  • Run a embedded transaction in closure
    The embedded transaction means that it will run a transaction if it’s not in other transaction, otherwise it will be executed within the existing transaction.

    try database.run(embeddedTransaction: { () throws -> Void in 
        try database.insert(objects: objects, intoTable: table)
    })
    

    Throws

    Error

    Declaration

    Swift

    public func run(embeddedTransaction: TransactionClosure) throws

    Parameters

    embeddedTransaction

    Operation inside transaction

  • Remove all database-related files.
    You should call it on a closed database. Otherwise you will get a warning.

    Throws

    Error

    Declaration

    Swift

    public func removeFiles() throws
  • This interface is equivalent moveFiles(toDirectory:withExtraFiles:)

    Throws

    Error

    Declaration

    Swift

    public func moveFiles(toDirectory directory: String, withExtraFiles extraFiles: String...) throws

    Parameters

    directory

    destination

    extraFiles

    extraFiles

  • Move all database-related files and some extra files to directory safely.
    You should call it on a closed database. Otherwise you will get a warning and you may get a corrupted database.

    Throws

    Error

    Declaration

    Swift

    public func moveFiles(toDirectory directory: String, withExtraFiles extraFiles: [String]) throws

    Parameters

    directory

    destination

    extraFiles

    extraFiles

  • Get the space used by the database files.
    You should call it on a closed database. Otherwise you will get a warning.

    Throws

    Error

    Declaration

    Swift

    public func getFilesSize() throws -> UInt64

    Return Value

    The sum of files size in bytes.

  • Backup metadata to recover.
    Since metadata will be changed while a table or an index is created or dropped, you should call this periodically.

    Throws

    Error

    Declaration

    Swift

    public func backup(withKey key: Data? = nil) throws

    Parameters

    key

    The cipher key for backup. Nil for non-encrypted.

  • Recover data from a corruped db. You’d better to recover a closed database.

    Throws

    Error

    Declaration

    Swift

    public func recover(fromPath source: String,

    Parameters

    source

    The path to the corrupted database

    pageSize

    Page size of the corrupted database. It’s default to 4096 on iOS. Page size never change unless you can call PRAGMA page_size=NewPageSize to set it. Also, you can call PRAGMA page_size to check the current value while database is not corrupted.

    databaseKey

    The cipher key for corrupeted database

    backupKey

    The cipher key for backup