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 layerThrows
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 callbegin
,commit
,rollback
and all other operations in same thread.
To do a cross-thread transaction, usegetTransaction
.Throws
Error
Declaration
Swift
public func begin(_ mode: StatementTransaction.Mode) throws
-
Separate interface of
run(transaction:)
You should callbegin
,commit
,rollback
and all other operations in same thread. To do a cross-thread transaction, usegetTransaction
.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, usegetTransaction
.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 callPRAGMA 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