wxSQLite3 4.9.11
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Friends | List of all members
wxSQLite3Database Class Reference

Represents a SQLite3 database object. More...

#include <wxsqlite3.h>

Public Member Functions

 wxSQLite3Database ()
 Default constructor.
 
virtual ~wxSQLite3Database ()
 Destructor.
 
void Open (const wxString &fileName, const wxString &key=wxEmptyString, int flags=WXSQLITE_OPEN_READWRITE|WXSQLITE_OPEN_CREATE, const wxString &vfs=wxEmptyString)
 Open a SQLite3 database.
 
void Open (const wxString &fileName, const wxMemoryBuffer &key, int flags=WXSQLITE_OPEN_READWRITE|WXSQLITE_OPEN_CREATE, const wxString &vfs=wxEmptyString)
 Open a SQLite3 database using a binary key.
 
void Open (const wxString &fileName, const wxSQLite3Cipher &cipher, const wxString &key, int flags=WXSQLITE_OPEN_READWRITE|WXSQLITE_OPEN_CREATE, const wxString &vfs=wxEmptyString)
 Open a SQLite3 database.
 
void Open (const wxString &fileName, const wxSQLite3Cipher &cipher, const wxMemoryBuffer &key, int flags=WXSQLITE_OPEN_READWRITE|WXSQLITE_OPEN_CREATE, const wxString &vfs=wxEmptyString)
 Open a SQLite3 database using a binary key.
 
bool IsOpen () const
 Check whether the database has been opened.
 
bool IsReadOnly (const wxString &databaseName=wxS("main")) const
 Determine whether a database is read-only.
 
void Close ()
 Close a SQLite3 database.
 
void AttachDatabase (const wxString &fileName, const wxString &schemaName)
 Attach SQLite3 database.
 
void AttachDatabase (const wxString &fileName, const wxString &schemaName, const wxString &key)
 Attach SQLite3 database with encryption key.
 
void AttachDatabase (const wxString &fileName, const wxString &schemaName, const wxSQLite3Cipher &cipher, const wxString &key)
 Attach SQLite3 database with encryption cipher and key.
 
void DetachDatabase (const wxString &schemaName)
 
void Backup (const wxString &targetFileName, const wxString &key=wxEmptyString, const wxString &sourceDatabaseName=wxS("main"))
 Backup a SQLite3 database.
 
void Backup (wxSQLite3BackupProgress *progressCallback, const wxString &targetFileName, const wxString &key=wxEmptyString, const wxString &sourceDatabaseName=wxS("main"))
 
void Backup (const wxString &targetFileName, const wxSQLite3Cipher &cipher, const wxString &key, const wxString &sourceDatabaseName=wxS("main"))
 
void Backup (wxSQLite3BackupProgress *progressCallback, const wxString &targetFileName, const wxSQLite3Cipher &cipher, const wxString &key, const wxString &sourceDatabaseName=wxS("main"))
 
void Backup (const wxString &targetFileName, const wxMemoryBuffer &key, const wxString &sourceDatabaseName=wxS("main"))
 Backup a SQLite3 database.
 
void Backup (wxSQLite3BackupProgress *progressCallback, const wxString &targetFileName, const wxMemoryBuffer &key, const wxString &sourceDatabaseName=wxS("main"))
 
void Backup (const wxString &targetFileName, const wxSQLite3Cipher &cipher, const wxMemoryBuffer &key, const wxString &sourceDatabaseName=wxS("main"))
 
void Backup (wxSQLite3BackupProgress *progressCallback, const wxString &targetFileName, const wxSQLite3Cipher &cipher, const wxMemoryBuffer &key, const wxString &sourceDatabaseName=wxS("main"))
 
void Restore (const wxString &sourceFileName, const wxString &key=wxEmptyString, const wxString &targetDatabaseName=wxS("main"))
 Restore a SQLite3 database.
 
void Restore (wxSQLite3BackupProgress *progressCallback, const wxString &sourceFileName, const wxString &key=wxEmptyString, const wxString &targetDatabaseName=wxS("main"))
 
void Restore (const wxString &sourceFileName, const wxSQLite3Cipher &cipher, const wxString &key, const wxString &targetDatabaseName=wxS("main"))
 
void Restore (wxSQLite3BackupProgress *progressCallback, const wxString &sourceFileName, const wxSQLite3Cipher &cipher, const wxString &key, const wxString &targetDatabaseName=wxS("main"))
 
void Restore (const wxString &sourceFileName, const wxMemoryBuffer &key, const wxString &targetDatabaseName=wxS("main"))
 Restore a SQLite3 database.
 
void Restore (wxSQLite3BackupProgress *progressCallback, const wxString &sourceFileName, const wxMemoryBuffer &key, const wxString &targetDatabaseName=wxS("main"))
 
void Restore (const wxString &sourceFileName, const wxSQLite3Cipher &cipher, const wxMemoryBuffer &key, const wxString &targetDatabaseName=wxS("main"))
 
void Restore (wxSQLite3BackupProgress *progressCallback, const wxString &sourceFileName, const wxSQLite3Cipher &cipher, const wxMemoryBuffer &key, const wxString &targetDatabaseName=wxS("main"))
 
void SetBackupRestorePageCount (int pageCount)
 Set the page count for backup or restore operations.
 
void Vacuum ()
 Vacuum.
 
void Begin (wxSQLite3TransactionType transactionType=WXSQLITE_TRANSACTION_DEFAULT)
 Begin transaction.
 
void Commit ()
 Commit transaction.
 
void Rollback (const wxString &savepointName=wxEmptyString)
 Rollback transaction.
 
bool GetAutoCommit () const
 Get the auto commit state.
 
int QueryRollbackState () const
 Query the return code of the last rollback.
 
wxSQLite3TransactionState QueryTransactionState (const wxString &schemaName=wxEmptyString) const
 Query the transaction state of a database.
 
void Savepoint (const wxString &savepointName)
 Set savepoint.
 
void ReleaseSavepoint (const wxString &savepointName)
 Release savepoint.
 
bool TableExists (const wxString &tableName, const wxString &databaseName=wxEmptyString)
 Check whether a table with the given name exists.
 
bool TableExists (const wxString &tableName, wxArrayString &databaseNames)
 Check whether a table with the given name exists in the main database or any attached database.
 
void GetDatabaseList (wxArrayString &databaseNames)
 Get a list containing the names of all attached databases including the main database.
 
void GetDatabaseList (wxArrayString &databaseNames, wxArrayString &databaseFiles)
 Get a list containing the names of all attached databases including the main database.
 
wxString GetDatabaseFilename (const wxString &databaseName)
 Return the filename for a database connection.
 
bool EnableForeignKeySupport (bool enable)
 Enable or disable foreign key support.
 
bool IsForeignKeySupportEnabled ()
 Check whether foreign key support is enabled for this database.
 
wxSQLite3JournalMode SetJournalMode (wxSQLite3JournalMode mode, const wxString &database=wxEmptyString)
 Set SQLite journal mode.
 
wxSQLite3JournalMode GetJournalMode (const wxString &database=wxEmptyString)
 Get the active SQLite journal mode.
 
bool CheckSyntax (const wxString &sql) const
 Check the syntax of an SQL statement given as a wxString.
 
bool CheckSyntax (const wxSQLite3StatementBuffer &sql) const
 Check the syntax of an SQL statement given as a statement buffer.
 
bool CheckSyntax (const char *sql) const
 Check the syntax of an SQL statement given as a utf-8 character string.
 
int ExecuteUpdate (const wxString &sql)
 Execute a data defining or manipulating SQL statement given as a wxString.
 
int ExecuteUpdate (const wxSQLite3StatementBuffer &sql)
 Execute a data defining or manipulating SQL statement given as a statement buffer.
 
int ExecuteUpdate (const char *sql, bool saveRC=false)
 Execute a data defining or manipulating SQL statement given as a utf-8 character string.
 
wxSQLite3ResultSet ExecuteQuery (const wxString &sql)
 Execute a SQL query statement given as a wxString.
 
wxSQLite3ResultSet ExecuteQuery (const wxSQLite3StatementBuffer &sql)
 Execute a SQL query statement given as a statement buffer.
 
wxSQLite3ResultSet ExecuteQuery (const char *sql)
 Execute a SQL query statement given as a utf-8 character string.
 
int ExecuteScalar (const wxString &sql)
 Execute a scalar SQL query statement given as a wxString.
 
int ExecuteScalar (const wxSQLite3StatementBuffer &sql)
 Execute a scalar SQL query statement given as a statement buffer.
 
int ExecuteScalar (const char *sql)
 Execute a scalar SQL query statement given as a utf-8 character string.
 
wxSQLite3Table GetTable (const wxString &sql)
 Get the result table for a SQL query statement given as a wxString.
 
wxSQLite3Table GetTable (const wxSQLite3StatementBuffer &sql)
 Get the result table for a SQL query statement given as a statement buffer.
 
wxSQLite3Table GetTable (const char *sql)
 Get the result table for a SQL query statement given as a utf-8 character string.
 
wxSQLite3Statement PrepareStatement (const wxString &sql)
 Prepare a SQL query statement given as a wxString for parameter binding.
 
wxSQLite3Statement PrepareStatement (const wxSQLite3StatementBuffer &sql)
 Prepare a SQL query statement given as a statement buffer for parameter binding.
 
wxSQLite3Statement PrepareStatement (const char *sql)
 Prepare a SQL query statement given as a utf-8 character string for parameter binding.
 
wxSQLite3Statement PreparePersistentStatement (const wxString &sql)
 Prepare a (long-lasting) SQL query statement given as a wxString for parameter binding.
 
wxSQLite3Statement PreparePersistentStatement (const wxSQLite3StatementBuffer &sql)
 Prepare a (long-lasting) SQL query statement given as a statement buffer for parameter binding.
 
wxSQLite3Statement PreparePersistentStatement (const char *sql)
 Prepare a (long-lasting) SQL query statement given as a utf-8 character string for parameter binding.
 
wxLongLong GetLastRowId () const
 Get the row id of last inserted row.
 
wxSQLite3Blob GetReadOnlyBlob (wxLongLong rowId, const wxString &columnName, const wxString &tableName, const wxString &dbName=wxEmptyString)
 Get handle to a read only BLOB.
 
wxSQLite3Blob GetWritableBlob (wxLongLong rowId, const wxString &columnName, const wxString &tableName, const wxString &dbName=wxEmptyString)
 Get handle to a writable BLOB.
 
wxSQLite3Blob GetBlob (wxLongLong rowId, const wxString &columnName, const wxString &tableName, const wxString &dbName=wxEmptyString, bool writable=true)
 Get handle to a BLOB.
 
wxSQLite3IntegerCollection CreateIntegerCollection (const wxString &collectionName)
 Create a named integer value collection.
 
wxSQLite3StringCollection CreateStringCollection (const wxString &collectionName)
 Create a named string value collection.
 
void Interrupt ()
 Interrupt a long running query.
 
bool IsInterrupted ()
 Determine whether or not an interrupt is currently in effect.
 
void SetBusyTimeout (int milliSeconds)
 Set the busy timeout.
 
bool CreateFunction (const wxString &funcName, int argCount, wxSQLite3ScalarFunction &function, int flags=0)
 Create a user-defined scalar function.
 
bool CreateFunction (const wxString &funcName, int argCount, wxSQLite3AggregateFunction &function, int flags=0)
 Create a user-defined aggregate function.
 
bool CreateFunction (const wxString &funcName, int argCount, wxSQLite3WindowFunction &function, int flags=0)
 Create a user-defined aggregate window function.
 
bool SetAuthorizer (wxSQLite3Authorizer &authorizer)
 Create a user-defined authorizer function.
 
bool RemoveAuthorizer ()
 Remove a user-defined authorizer function.
 
void SetCommitHook (wxSQLite3Hook *commitHook)
 Create a user-defined commit callback function.
 
void SetRollbackHook (wxSQLite3Hook *rollbackHook)
 Create a user-defined rollback callback function.
 
void SetUpdateHook (wxSQLite3Hook *updateHook)
 Create a user-defined update callback function.
 
void SetWriteAheadLogHook (wxSQLite3Hook *walHook)
 Create a user-defined Write Ahead Log callback function.
 
void WriteAheadLogCheckpoint (const wxString &database, int mode=WXSQLITE_CHECKPOINT_PASSIVE, int *logFrameCount=NULL, int *ckptFrameCount=NULL)
 Checkpoint database in write-ahead log mode.
 
void AutoWriteAheadLogCheckpoint (int frameCount)
 Automatically checkpoint database in write-ahead log mode.
 
void SetCollation (const wxString &name, wxSQLite3Collation *collation)
 Create a user-defined collation sequence.
 
void GetMetaData (const wxString &dbName, const wxString &tableName, const wxString &columnName, wxString *dataType=NULL, wxString *collation=NULL, bool *notNull=NULL, bool *primaryKey=NULL, bool *autoIncrement=NULL)
 Return meta information about a specific column of a specific database table.
 
void LoadExtension (const wxString &fileName, const wxString &entryPoint=wxS("sqlite3_extension_init"))
 Load a database extension.
 
void EnableLoadExtension (bool enable)
 Enable or disable loading of database extensions.
 
void ReKey (const wxString &newKey)
 Change the encryption key of the database.
 
void ReKey (const wxSQLite3Cipher &cipher, const wxString &newKey)
 
void ReKey (const wxMemoryBuffer &newKey)
 Change the encryption key of the database.
 
void ReKey (const wxSQLite3Cipher &cipher, const wxMemoryBuffer &newKey)
 
bool IsEncrypted () const
 Check whether the database is encrypted.
 
wxString GetKeySalt (const wxString &schemaName=wxEmptyString) const
 Get the key salt of an encrypted database.
 
bool UserLogin (const wxString &username, const wxString &password)
 Authenticate the user on a database with user authentication.
 
bool UserAdd (const wxString &username, const wxString &password, bool isAdmin=false)
 Add a user to a database with user authentication.
 
bool UserChange (const wxString &username, const wxString &password, bool isAdmin)
 Change password and/or privileges of a user on a database with user authentication.
 
bool UserDelete (const wxString &username)
 Delete a user from a database with user authentication.
 
bool UserIsPrivileged (const wxString &username)
 Check whether a user of a database with user authentication is privileged.
 
void GetUserList (wxArrayString &userList)
 Get a list of users for a database with user authentication.
 
int GetLimit (wxSQLite3LimitType id) const
 Query the value of a database limit.
 
int SetLimit (wxSQLite3LimitType id, int newValue)
 Change a database limit to a new value.
 
void ReleaseMemory ()
 Free memory used by a database connection.
 
int GetSystemErrorCode () const
 Get system error code.
 

Static Public Member Functions

static wxString LimitTypeToString (wxSQLite3LimitType type)
 Convert database limit type to string.
 
static void InitializeSQLite ()
 Initialize the SQLite library.
 
static void InitializeSQLite (const wxSQLite3Logger &logger)
 
static void ShutdownSQLite ()
 Shutdown the SQLite library.
 
static bool SetTemporaryDirectory (const wxString &tempDirectory)
 Set temporary directory where SQLite stores temporary files (Windows only)
 
static bool Randomness (int n, wxMemoryBuffer &random)
 Get random bytes.
 
static void SetSharedCache (bool enable)
 Enable or disable SQLite shared cache.
 
static bool IsSharedCacheEnabled ()
 Check whether SQLite shared cache is enabled.
 
static wxString GetWrapperVersion ()
 Get the version of the wxSQLite3 wrapper.
 
static wxString GetVersion ()
 Get the version of the underlying SQLite3 library.
 
static wxString GetSourceId ()
 Get the source id of the underlying SQLite3 library.
 
static bool CompileOptionUsed (const wxString &optionName)
 Check SQLite compile option.
 
static wxString GetCompileOptionName (int optionIndex)
 Get SQLite compile option name.
 
static wxString ConvertJournalMode (wxSQLite3JournalMode mode)
 Convert journal mode to/from string.
 
static wxSQLite3JournalMode ConvertJournalMode (const wxString &mode)
 Convert journal mode to/from string.
 
static bool HasEncryptionSupport ()
 Check whether wxSQLite3 has been compiled with encryption support.
 
static bool HasMetaDataSupport ()
 Check whether wxSQLite3 has been compiled with meta data support.
 
static bool HasUserAuthenticationSupport ()
 Check whether wxSQLite3 has been compiled with user authentication support.
 
static bool HasLoadExtSupport ()
 Check whether wxSQLite3 has been compiled with loadable extension support.
 
static bool HasNamedCollectionSupport ()
 Check whether wxSQLite3 has been compiled with support for named collections.
 
static bool HasIncrementalBlobSupport ()
 Check whether wxSQLite3 has support for incremental BLOBs.
 
static bool HasSavepointSupport ()
 Check whether wxSQLite3 has support for SQLite savepoints.
 
static bool HasBackupSupport ()
 Check whether wxSQLite3 has support for SQLite backup/restore.
 
static bool HasWriteAheadLogSupport ()
 Check whether wxSQLite3 has support for SQLite write-ahead log.
 
static bool HasPointerParamsSupport ()
 Check whether wxSQLite3 has support for SQLite pointer parameters.
 

Protected Member Functions

void * GetDatabaseHandle () const
 Access SQLite's internal database handle.
 
void SetCollationNeededCallback ()
 Activate the callback for needed collations for this database.
 
virtual void SetNeededCollation (const wxString &WXUNUSED(collationName))
 Request the instantiation of a user defined collation sequence.
 

Static Protected Member Functions

static int ExecComparisonWithCollation (void *collation, int len1, const void *txt1, int len2, const void *txt2)
 Execute a comparison using a user-defined collation.
 
static void ExecCollationNeeded (void *db, void *internalDb, int eTextRep, const char *name)
 Execute callback for needed collation sequences.
 

Friends

class wxSQLite3Cipher
 

Detailed Description

Represents a SQLite3 database object.

Constructor & Destructor Documentation

◆ wxSQLite3Database()

wxSQLite3Database::wxSQLite3Database ( )

Default constructor.

Initializes a SQLite database object. The SQLite database object can only be used in the same thread in which it was created.

◆ ~wxSQLite3Database()

wxSQLite3Database::~wxSQLite3Database ( )
virtual

Destructor.

Destructs a SQLite database object. The database will be closed implicitly if it is still open.

Member Function Documentation

◆ AttachDatabase() [1/3]

void wxSQLite3Database::AttachDatabase ( const wxString & fileName,
const wxString & schemaName )

Attach SQLite3 database.

This method allows to attach a SQLite3 database to the current database connection.

NOTE: If the main database is encrypted, the same encryption method and key will be used.

Parameters
[in]fileNameName of the database file that should be attached.
[in]schemaNameName of the schema that should be used for the attached database.

◆ AttachDatabase() [2/3]

void wxSQLite3Database::AttachDatabase ( const wxString & fileName,
const wxString & schemaName,
const wxSQLite3Cipher & cipher,
const wxString & key )

Attach SQLite3 database with encryption cipher and key.

This method allows to attach a SQLite3 database to the current database connection using the given encryption scheme and key.

NOTE: If the main database is encrypted, the default encryption cipher will be used. The given key will be used as the pass phrase. Use an empty key to attach a plain (unencrypted) database file.

Parameters
[in]fileNameName of the database file that should be attached.
[in]schemaNameName of the schema that should be used for the attached database.
[in]cipherCipher to be used for database encryption.
[in]keyPass phrase for the attached database.

◆ AttachDatabase() [3/3]

void wxSQLite3Database::AttachDatabase ( const wxString & fileName,
const wxString & schemaName,
const wxString & key )

Attach SQLite3 database with encryption key.

This method allows to attach a SQLite3 database to the current database connection using the given encryption key and the default encryption cipher.

NOTE: The default encryption cipher will be used, and the given key will be used as the pass phrase. Use an empty key to attach a plain (unencrypted) database file to an encrypted main database.

Parameters
[in]fileNameName of the database file that should be attached.
[in]schemaNameName of the schema that should be used for the attached database.
[in]keyPass phrase for the attached database.

◆ AutoWriteAheadLogCheckpoint()

void wxSQLite3Database::AutoWriteAheadLogCheckpoint ( int frameCount)

Automatically checkpoint database in write-ahead log mode.

Causes any database associated with this database instance to automatically checkpoint after committing a transaction if there are N or more frames in the write-ahead log file. Passing zero or a negative value as the nFrame parameter disables automatic checkpoints entirely.

Parameters
frameCountframe threshold

◆ Backup() [1/8]

void wxSQLite3Database::Backup ( const wxString & targetFileName,
const wxMemoryBuffer & key,
const wxString & sourceDatabaseName = wxS("main") )

Backup a SQLite3 database.

This method is used to overwrite the contents of a database with the contents of this database. This is useful either for creating backups of the database or for copying an in-memory database to persistent files.

NOTE: Exclusive access is required to the target database for the duration of the operation. However the source database is only read-locked while it is actually being read, it is not locked continuously for the entire operation. Thus, the backup may be performed on a live database without preventing other users from writing to the database for an extended period of time.

NOTE: If the target database file already exists it must be a valid SQLite database, in case of an encrypted database the key used for backup must be the same as the key used for creation. If this does not hold true, the file should be deleted prior to performing the backup.

Parameters
[in]targetFileNameName of the target database file.
[in]keyBinary database encryption key for the target database.
[in]sourceDatabaseNameOptional name of the source database (default: 'main').

◆ Backup() [2/8]

void wxSQLite3Database::Backup ( const wxString & targetFileName,
const wxSQLite3Cipher & cipher,
const wxMemoryBuffer & key,
const wxString & sourceDatabaseName = wxS("main") )

◆ Backup() [3/8]

void wxSQLite3Database::Backup ( const wxString & targetFileName,
const wxSQLite3Cipher & cipher,
const wxString & key,
const wxString & sourceDatabaseName = wxS("main") )

◆ Backup() [4/8]

void wxSQLite3Database::Backup ( const wxString & targetFileName,
const wxString & key = wxEmptyString,
const wxString & sourceDatabaseName = wxS("main") )

Backup a SQLite3 database.

This method is used to overwrite the contents of a database with the contents of this database. This is useful either for creating backups of the database or for copying an in-memory database to persistent files.

NOTE: Exclusive access is required to the target database for the duration of the operation. However the source database is only read-locked while it is actually being read, it is not locked continuously for the entire operation. Thus, the backup may be performed on a live database without preventing other users from writing to the database for an extended period of time.

NOTE: If the target database file already exists it must be a valid SQLite database, in case of an encrypted database the key used for backup must be the same as the key used for creation. If this does not hold true, the file should be deleted prior to performing the backup.

Parameters
[in]targetFileNameName of the target database file.
[in]keyOptional database encryption key for the target database.
[in]sourceDatabaseNameOptional name of the source database (default: 'main').

◆ Backup() [5/8]

void wxSQLite3Database::Backup ( wxSQLite3BackupProgress * progressCallback,
const wxString & targetFileName,
const wxMemoryBuffer & key,
const wxString & sourceDatabaseName = wxS("main") )

◆ Backup() [6/8]

void wxSQLite3Database::Backup ( wxSQLite3BackupProgress * progressCallback,
const wxString & targetFileName,
const wxSQLite3Cipher & cipher,
const wxMemoryBuffer & key,
const wxString & sourceDatabaseName = wxS("main") )

◆ Backup() [7/8]

void wxSQLite3Database::Backup ( wxSQLite3BackupProgress * progressCallback,
const wxString & targetFileName,
const wxSQLite3Cipher & cipher,
const wxString & key,
const wxString & sourceDatabaseName = wxS("main") )

◆ Backup() [8/8]

void wxSQLite3Database::Backup ( wxSQLite3BackupProgress * progressCallback,
const wxString & targetFileName,
const wxString & key = wxEmptyString,
const wxString & sourceDatabaseName = wxS("main") )

◆ Begin()

void wxSQLite3Database::Begin ( wxSQLite3TransactionType transactionType = WXSQLITE_TRANSACTION_DEFAULT)

Begin transaction.

In SQLite transactions can be deferred, immediate, or exclusive. Deferred means that no locks are acquired on the database until the database is first accessed. Thus with a deferred transaction, the BEGIN statement itself does nothing. Locks are not acquired until the first read or write operation. The first read operation against a database creates a SHARED lock and the first write operation creates a RESERVED lock. Because the acquisition of locks is deferred until they are needed, it is possible that another thread or process could create a separate transaction and write to the database after the BEGIN on the current thread has executed. If the transaction is immediate, then RESERVED locks are acquired on all databases as soon as the BEGIN command is executed, without waiting for the database to be used. After a BEGIN IMMEDIATE, it is guaranteed that no other thread or process will be able to write to the database or do a BEGIN IMMEDIATE or BEGIN EXCLUSIVE. Other processes can continue to read from the database, however. An exclusive transaction causes EXCLUSIVE locks to be acquired on all databases. After a BEGIN EXCLUSIVE, it is guaranteed that no other thread or process will be able to read or write the database until the transaction is complete.

Parameters
[in]transactionTypetype of transaction (default: DEFERRED).

◆ CheckSyntax() [1/3]

bool wxSQLite3Database::CheckSyntax ( const char * sql) const

Check the syntax of an SQL statement given as a utf-8 character string.

Parameters
sqlquery string
Returns
TRUE if the syntax is correct, FALSE otherwise

◆ CheckSyntax() [2/3]

bool wxSQLite3Database::CheckSyntax ( const wxSQLite3StatementBuffer & sql) const

Check the syntax of an SQL statement given as a statement buffer.

Parameters
sqlquery string
Returns
TRUE if the syntax is correct, FALSE otherwise

◆ CheckSyntax() [3/3]

bool wxSQLite3Database::CheckSyntax ( const wxString & sql) const

Check the syntax of an SQL statement given as a wxString.

Parameters
sqlquery string
Returns
TRUE if the syntax is correct, FALSE otherwise

◆ Close()

void wxSQLite3Database::Close ( )

Close a SQLite3 database.

Take care that all prepared statements have been finalized!

NOTE: Starting with version 3.6.0 SQLite has support to finalize all not-finalized prepared statements. Unfortunately this feature can't be used due to a possible crash if the RTree module is active.

NOTE: Finalizing all wxSQLite3Blob instances before closing a database is required!

◆ Commit()

void wxSQLite3Database::Commit ( )

Commit transaction.

◆ CompileOptionUsed()

bool wxSQLite3Database::CompileOptionUsed ( const wxString & optionName)
static

Check SQLite compile option.

Check whether the compile option with a given name has been used on building SQLite. The SQLITE_ prefix may be omitted from the option name passed to this method.

Parameters
optionNamename of the compile option to be queried
Returns
TRUE if the compile option was in use, FALSE otherwise
Note
If the option name is unknown or if the SQLite version is lower than 3.6.23 this method returns FALSE.

◆ ConvertJournalMode() [1/2]

wxSQLite3JournalMode wxSQLite3Database::ConvertJournalMode ( const wxString & mode)
static

Convert journal mode to/from string.

Parameters
modethe string representation of the desired journal mode.
Returns
the enum representation of the journal mode

◆ ConvertJournalMode() [2/2]

wxString wxSQLite3Database::ConvertJournalMode ( wxSQLite3JournalMode mode)
static

Convert journal mode to/from string.

Parameters
modethe wxSQLite3JournalMode enum value signifying the desired journal mode.
Returns
the string representation of the journal mode

◆ CreateFunction() [1/3]

bool wxSQLite3Database::CreateFunction ( const wxString & funcName,
int argCount,
wxSQLite3AggregateFunction & function,
int flags = 0 )

Create a user-defined aggregate function.

Registers a SQL aggregate function with the database.

Parameters
funcNamename of the aggregate function
argCountnumber of arguments the aggregate function takes. If this argument is -1 then the aggregate function may take any number of arguments.
functioninstance of an aggregate function
flagsspecifies a combination of function flags (WXSQLITE_DETERMINISTIC, WXSQLITE_DIRECTONLY, WXSQLITE_SUBTYPE, WXSQLITE_INNOCUOUS). (Default: none) (see https://www.sqlite.org/c3ref/c_deterministic.html for detailed explanations
Returns
TRUE on successful registration, FALSE otherwise

◆ CreateFunction() [2/3]

bool wxSQLite3Database::CreateFunction ( const wxString & funcName,
int argCount,
wxSQLite3ScalarFunction & function,
int flags = 0 )

Create a user-defined scalar function.

Registers a SQL scalar function with the database.

Parameters
funcNamename of the scalar function
argCountnumber of arguments the scalar function takes. If this argument is -1 then the scalar function may take any number of arguments.
functioninstance of an scalar function
flagsspecifies a combination of function flags (WXSQLITE_DETERMINISTIC, WXSQLITE_DIRECTONLY, WXSQLITE_SUBTYPE, WXSQLITE_INNOCUOUS). (Default: none) (see https://www.sqlite.org/c3ref/c_deterministic.html for detailed explanations
Returns
TRUE on successful registration, FALSE otherwise

◆ CreateFunction() [3/3]

bool wxSQLite3Database::CreateFunction ( const wxString & funcName,
int argCount,
wxSQLite3WindowFunction & function,
int flags = 0 )

Create a user-defined aggregate window function.

Registers a SQL aggregate window function with the database.

Parameters
funcNamename of the aggregate window function
argCountnumber of arguments the aggregate window function takes. If this argument is -1 then the aggregate function may take any number of arguments.
functioninstance of an aggregate window function
flagsspecifies a combination of function flags (WXSQLITE_DETERMINISTIC, WXSQLITE_DIRECTONLY, WXSQLITE_SUBTYPE, WXSQLITE_INNOCUOUS). (Default: none) (see https://www.sqlite.org/c3ref/c_deterministic.html for detailed explanations
Returns
TRUE on successful registration, FALSE otherwise

◆ CreateIntegerCollection()

wxSQLite3IntegerCollection wxSQLite3Database::CreateIntegerCollection ( const wxString & collectionName)

Create a named integer value collection.

Invoke this method to create a specific instance of an integer collection object. Initially the created collection is empty. Use it's Bind method to actually bind an array of values to the collection.

Parameters
collectionNamename of the collection
Returns
the new integer collection object.

Each integer value collection object corresponds to a virtual table in the TEMP table with a name of collectionName.

The virtual table will be dropped implicitly when the database connection is closed.

◆ CreateStringCollection()

wxSQLite3StringCollection wxSQLite3Database::CreateStringCollection ( const wxString & collectionName)

Create a named string value collection.

Invoke this method to create a specific instance of a string collection object. Initially the created collection is empty. Use it's Bind method to actually bind an array of values to the collection.

Parameters
collectionNamename of the collection
Returns
the new string collection object.

Each integer value collection object corresponds to a virtual table in the TEMP table with a name of collectionName.

The virtual table will be dropped implicitly when the database connection is closed.

◆ DetachDatabase()

void wxSQLite3Database::DetachDatabase ( const wxString & schemaName)

◆ EnableForeignKeySupport()

bool wxSQLite3Database::EnableForeignKeySupport ( bool enable)

Enable or disable foreign key support.

Starting with SQLite version 3.6.19 foreign key constraints can be enforced. Foreign key constraints are disabled by default (for backwards compatibility), so they must be enabled separately for each database connection.

Note
Future releases of SQLite might change so that foreign key constraints are enabled by default. No assumptions should be made about whether or not foreign keys are enabled by default
Returns
TRUE if the requested action succeeded, FALSE otherwise

◆ EnableLoadExtension()

void wxSQLite3Database::EnableLoadExtension ( bool enable)

Enable or disable loading of database extensions.

Parameters
enableFlag whether to enable (TRUE) or disable (FALSE) loadable extensions

◆ ExecCollationNeeded()

void wxSQLite3Database::ExecCollationNeeded ( void * db,
void * internalDb,
int eTextRep,
const char * name )
staticprotected

Execute callback for needed collation sequences.

◆ ExecComparisonWithCollation()

int wxSQLite3Database::ExecComparisonWithCollation ( void * collation,
int len1,
const void * txt1,
int len2,
const void * txt2 )
staticprotected

Execute a comparison using a user-defined collation.

◆ ExecuteQuery() [1/3]

wxSQLite3ResultSet wxSQLite3Database::ExecuteQuery ( const char * sql)

Execute a SQL query statement given as a utf-8 character string.

Parameters
sqlquery string
Returns
result set instance

◆ ExecuteQuery() [2/3]

wxSQLite3ResultSet wxSQLite3Database::ExecuteQuery ( const wxSQLite3StatementBuffer & sql)

Execute a SQL query statement given as a statement buffer.

Parameters
sqlquery string
Returns
result set instance

◆ ExecuteQuery() [3/3]

wxSQLite3ResultSet wxSQLite3Database::ExecuteQuery ( const wxString & sql)

Execute a SQL query statement given as a wxString.

Parameters
sqlquery string
Returns
result set instance

◆ ExecuteScalar() [1/3]

int wxSQLite3Database::ExecuteScalar ( const char * sql)

Execute a scalar SQL query statement given as a utf-8 character string.

Allows to easily retrieve the result of queries returning a single integer result like SELECT COUNT(*) FROM table WHERE condition.

Parameters
sqlquery string
Returns
first column of first row as an int

◆ ExecuteScalar() [2/3]

int wxSQLite3Database::ExecuteScalar ( const wxSQLite3StatementBuffer & sql)

Execute a scalar SQL query statement given as a statement buffer.

Allows to easily retrieve the result of queries returning a single integer result like SELECT COUNT(*) FROM table WHERE condition.

Parameters
sqlquery string
Returns
first column of first row as an int

◆ ExecuteScalar() [3/3]

int wxSQLite3Database::ExecuteScalar ( const wxString & sql)

Execute a scalar SQL query statement given as a wxString.

Allows to easily retrieve the result of queries returning a single integer result like SELECT COUNT(*) FROM table WHERE condition.

Parameters
sqlquery string
Returns
first column of first row as an int

◆ ExecuteUpdate() [1/3]

int wxSQLite3Database::ExecuteUpdate ( const char * sql,
bool saveRC = false )

Execute a data defining or manipulating SQL statement given as a utf-8 character string.

Execute a data defining or manipulating SQL statement given as a utf-8 character string, i.e. create, alter, drop, insert, update, delete and so on

Parameters
sqlquery string
saveRCflag whether to save the SQLite return code in case of a rollback
Returns
the number of database rows that were changed (or inserted or deleted)

◆ ExecuteUpdate() [2/3]

int wxSQLite3Database::ExecuteUpdate ( const wxSQLite3StatementBuffer & sql)

Execute a data defining or manipulating SQL statement given as a statement buffer.

Execute a data defining or manipulating SQL statement given as a statement buffer, i.e. create, alter, drop, insert, update, delete and so on

Parameters
sqlquery string
Returns
the number of database rows that were changed (or inserted or deleted)

◆ ExecuteUpdate() [3/3]

int wxSQLite3Database::ExecuteUpdate ( const wxString & sql)

Execute a data defining or manipulating SQL statement given as a wxString.

Execute a data defining or manipulating SQL statement given as a wxString, i.e. create, alter, drop, insert, update, delete and so on

Parameters
sqlquery string
Returns
the number of database rows that were changed (or inserted or deleted)

◆ GetAutoCommit()

bool wxSQLite3Database::GetAutoCommit ( ) const

Get the auto commit state.

Test to see whether or not the database connection is in autocommit mode.

Returns
TRUE if it is and FALSE if not. Autocommit mode is on by default. Autocommit is disabled by a BEGIN statement and reenabled by the next COMMIT or ROLLBACK.

◆ GetBlob()

wxSQLite3Blob wxSQLite3Database::GetBlob ( wxLongLong rowId,
const wxString & columnName,
const wxString & tableName,
const wxString & dbName = wxEmptyString,
bool writable = true )

Get handle to a BLOB.

Parameters
rowId
columnName
tableName
dbName
writable

◆ GetCompileOptionName()

wxString wxSQLite3Database::GetCompileOptionName ( int optionIndex)
static

Get SQLite compile option name.

Get the name of a SQLite compile option at a given index. This method allows interating over the list of options that were defined at compile time. If the option index is out of range, an empty string is returned. The SQLITE_ prefix is omitted from any strings returned by this method.

Parameters
optionIndexIndex of the compile option
Returns
a string containing the name of the n-th

◆ GetDatabaseFilename()

wxString wxSQLite3Database::GetDatabaseFilename ( const wxString & databaseName)

Return the filename for a database connection.

Parameters
databaseNamecontains on return the list of the database names

◆ GetDatabaseHandle()

void * wxSQLite3Database::GetDatabaseHandle ( ) const
protected

Access SQLite's internal database handle.

◆ GetDatabaseList() [1/2]

void wxSQLite3Database::GetDatabaseList ( wxArrayString & databaseNames)

Get a list containing the names of all attached databases including the main database.

Parameters
databaseNamescontains on return the list of the database names

◆ GetDatabaseList() [2/2]

void wxSQLite3Database::GetDatabaseList ( wxArrayString & databaseNames,
wxArrayString & databaseFiles )

Get a list containing the names of all attached databases including the main database.

Parameters
databaseNamescontains on return the list of the database names
databaseFilescontains on return the list of the database file names

◆ GetJournalMode()

wxSQLite3JournalMode wxSQLite3Database::GetJournalMode ( const wxString & database = wxEmptyString)

Get the active SQLite journal mode.

Parameters
databasethe attached database for which the journal mode should be queried (default: main)
Returns
active journal mode

◆ GetKeySalt()

wxString wxSQLite3Database::GetKeySalt ( const wxString & schemaName = wxEmptyString) const

Get the key salt of an encrypted database.

If the database is encrypted and if the encryption scheme uses key salt, this method allows to get the key salt as a hexadecimal encoded string.

In case of database header corruption it is essential to know the key salt of the encryption schemes ChaCha20 or SQLCipher. Without the correct key salt recovering such a corrupted database is almost impossible.

Parameters
schemaNameThe name of the schema (attached database), default: "main"
Returns
the key salt as a hexadecimal encoded string, empty if database not opened, or if no key salt is in use

◆ GetLastRowId()

wxLongLong wxSQLite3Database::GetLastRowId ( ) const

Get the row id of last inserted row.

Each entry in an SQLite table has a unique integer key. (The key is the value of the INTEGER PRIMARY KEY column if there is such a column, otherwise the key is generated at random. The unique key is always available as the ROWID, OID, or ROWID column.)

Returns
the integer key of the most recent insert in the database.

◆ GetLimit()

int wxSQLite3Database::GetLimit ( wxSQLite3LimitType id) const

Query the value of a database limit.

This method allows to query several database limits. Consult the SQLite documentation for further explanation.

Parameters
idThe identifier of the limit to be queried
Returns
the current value of the queried limit

◆ GetMetaData()

void wxSQLite3Database::GetMetaData ( const wxString & dbName,
const wxString & tableName,
const wxString & columnName,
wxString * dataType = NULL,
wxString * collation = NULL,
bool * notNull = NULL,
bool * primaryKey = NULL,
bool * autoIncrement = NULL )

Return meta information about a specific column of a specific database table.

Parameters
dbNameis either the name of the database (i.e. "main", "temp" or an attached database) or an empty string. If it is an empty string all attached databases are searched for the table.
tableNamename of the database table
columnNamename of the database column
dataTypedeclared data type of the column. Pass NULL if information not needed.
collationname of the collation sequence. Pass NULL if information is not needed.
notNulloutput flag whether the column has a not null constraint. Pass NULL if information not needed.
primaryKeyoutput flag whether the column is part of the primary key. Pass NULL if information not needed.
autoIncrementoutput flag whether the column is an auto increment column. Pass NULL if information not needed.

This method is only available if SQLite has been compiled with SQLITE_ENABLE_COLUMN_METADATA defined.

◆ GetReadOnlyBlob()

wxSQLite3Blob wxSQLite3Database::GetReadOnlyBlob ( wxLongLong rowId,
const wxString & columnName,
const wxString & tableName,
const wxString & dbName = wxEmptyString )

Get handle to a read only BLOB.

Parameters
rowId
columnName
tableName
dbName

◆ GetSourceId()

wxString wxSQLite3Database::GetSourceId ( )
static

Get the source id of the underlying SQLite3 library.

Returns
a string which contains the source id of the library

◆ GetSystemErrorCode()

int wxSQLite3Database::GetSystemErrorCode ( ) const

Get system error code.

Get the underlying system error code after a SQLite function has failed, i.e. a file couldn't be opened

◆ GetTable() [1/3]

wxSQLite3Table wxSQLite3Database::GetTable ( const char * sql)

Get the result table for a SQL query statement given as a utf-8 character string.

Returns all resulting rows of the query for later processing.

Parameters
sqlquery string
Returns
table instance

◆ GetTable() [2/3]

wxSQLite3Table wxSQLite3Database::GetTable ( const wxSQLite3StatementBuffer & sql)

Get the result table for a SQL query statement given as a statement buffer.

Returns all resulting rows of the query for later processing.

Parameters
sqlquery string
Returns
table instance

◆ GetTable() [3/3]

wxSQLite3Table wxSQLite3Database::GetTable ( const wxString & sql)

Get the result table for a SQL query statement given as a wxString.

Returns all resulting rows of the query for later processing.

Parameters
sqlquery string
Returns
table instance

◆ GetUserList()

void wxSQLite3Database::GetUserList ( wxArrayString & userList)

Get a list of users for a database with user authentication.

A privileged user can list the users registered in the database. For a non-privileged user this method will throw an exception.

Parameters
userListarray of user names

◆ GetVersion()

wxString wxSQLite3Database::GetVersion ( )
static

Get the version of the underlying SQLite3 library.

Returns
a string which contains the version number of the library

◆ GetWrapperVersion()

wxString wxSQLite3Database::GetWrapperVersion ( )
static

Get the version of the wxSQLite3 wrapper.

Returns
a string which contains the name and version number of the wxSQLite3 wrapper

◆ GetWritableBlob()

wxSQLite3Blob wxSQLite3Database::GetWritableBlob ( wxLongLong rowId,
const wxString & columnName,
const wxString & tableName,
const wxString & dbName = wxEmptyString )

Get handle to a writable BLOB.

Parameters
rowId
columnName
tableName
dbName

◆ HasBackupSupport()

bool wxSQLite3Database::HasBackupSupport ( )
static

Check whether wxSQLite3 has support for SQLite backup/restore.

Returns
TRUE if SQLite backup/restore is supported, FALSE otherwise

◆ HasEncryptionSupport()

bool wxSQLite3Database::HasEncryptionSupport ( )
static

Check whether wxSQLite3 has been compiled with encryption support.

Returns
TRUE if encryption support is enabled, FALSE otherwise

◆ HasIncrementalBlobSupport()

bool wxSQLite3Database::HasIncrementalBlobSupport ( )
static

Check whether wxSQLite3 has support for incremental BLOBs.

Returns
TRUE if incremental BLOB support is available, FALSE otherwise

◆ HasLoadExtSupport()

bool wxSQLite3Database::HasLoadExtSupport ( )
static

Check whether wxSQLite3 has been compiled with loadable extension support.

Returns
TRUE if loadable extension support is enabled, FALSE otherwise

◆ HasMetaDataSupport()

bool wxSQLite3Database::HasMetaDataSupport ( )
static

Check whether wxSQLite3 has been compiled with meta data support.

Returns
TRUE if meta data support is enabled, FALSE otherwise

◆ HasNamedCollectionSupport()

bool wxSQLite3Database::HasNamedCollectionSupport ( )
static

Check whether wxSQLite3 has been compiled with support for named collections.

Returns
TRUE if named collection support is enabled, FALSE otherwise

◆ HasPointerParamsSupport()

bool wxSQLite3Database::HasPointerParamsSupport ( )
static

Check whether wxSQLite3 has support for SQLite pointer parameters.

Returns
TRUE if SQLite pointer parameters are supported, FALSE otherwise

◆ HasSavepointSupport()

bool wxSQLite3Database::HasSavepointSupport ( )
static

Check whether wxSQLite3 has support for SQLite savepoints.

Returns
TRUE if SQLite savepoints are supported, FALSE otherwise

◆ HasUserAuthenticationSupport()

bool wxSQLite3Database::HasUserAuthenticationSupport ( )
static

Check whether wxSQLite3 has been compiled with user authentication support.

Returns
TRUE if user authentication support is enabled, FALSE otherwise

◆ HasWriteAheadLogSupport()

bool wxSQLite3Database::HasWriteAheadLogSupport ( )
static

Check whether wxSQLite3 has support for SQLite write-ahead log.

Returns
TRUE if SQLite write-ahead log is supported, FALSE otherwise

◆ InitializeSQLite() [1/2]

void wxSQLite3Database::InitializeSQLite ( )
static

Initialize the SQLite library.

Starting with SQLite version 3.6.0 there is a new method to initialize the SQLite library. Currently an explicit call to this method is not required, but this behaviour might change in the future of SQLite. Therefore it is recommended to call this method once before accessing any SQLite databases.

◆ InitializeSQLite() [2/2]

void wxSQLite3Database::InitializeSQLite ( const wxSQLite3Logger & logger)
static

◆ Interrupt()

void wxSQLite3Database::Interrupt ( )

Interrupt a long running query.

Causes any pending database operation to abort and return at its earliest opportunity. This method is typically called in response to a user action such as pressing "Cancel" or Ctrl-C where the user wants a long query operation to halt immediately.

◆ IsEncrypted()

bool wxSQLite3Database::IsEncrypted ( ) const
inline

Check whether the database is encrypted.

Check whether the database has been opened using an encryption key.

Returns
TRUE if database is encrypted, FALSE otherwise

◆ IsForeignKeySupportEnabled()

bool wxSQLite3Database::IsForeignKeySupportEnabled ( )

Check whether foreign key support is enabled for this database.

Returns
TRUE if foreign key support is enabled, FALSE otherwise

◆ IsInterrupted()

bool wxSQLite3Database::IsInterrupted ( )

Determine whether or not an interrupt is currently in effect.

Returns
TRUE if an interrupt is in effect, FALSE otherwise.

◆ IsOpen()

bool wxSQLite3Database::IsOpen ( ) const

Check whether the database has been opened.

Returns
TRUE if database has been opened, FALSE otherwise

◆ IsReadOnly()

bool wxSQLite3Database::IsReadOnly ( const wxString & databaseName = wxS("main")) const

Determine whether a database is read-only.

Parameters
[in]databaseNameName of the database (default "main").
Returns
TRUE if the database is read-only, FALSE otherwise
Since
SQLite3 version 3.7.11
Note
For SQLite3 version before version 3.7.11 this method returns always FALSE.

◆ IsSharedCacheEnabled()

static bool wxSQLite3Database::IsSharedCacheEnabled ( )
inlinestatic

Check whether SQLite shared cache is enabled.

Returns
TRUE if the SQLite shared cache is enabled, FALSE otherwise

◆ LimitTypeToString()

wxString wxSQLite3Database::LimitTypeToString ( wxSQLite3LimitType type)
static

Convert database limit type to string.

Parameters
typeThe database limit type to be converted to string representation.

◆ LoadExtension()

void wxSQLite3Database::LoadExtension ( const wxString & fileName,
const wxString & entryPoint = wxS("sqlite3_extension_init") )

Load a database extension.

Parameters
fileNameName of the shared library containing extension.
entryPointName of the entry point.

◆ Open() [1/4]

void wxSQLite3Database::Open ( const wxString & fileName,
const wxMemoryBuffer & key,
int flags = WXSQLITE_OPEN_READWRITE | WXSQLITE_OPEN_CREATE,
const wxString & vfs = wxEmptyString )

Open a SQLite3 database using a binary key.

Opens the SQLite database file "filename". The "filename" is UTF-8 encoded. If the database could not be opened (or created) successfully, then an exception is thrown. If the database file does not exist, then a new database will be created as needed.

Parameters
[in]fileNameName of the database file.
[in]keyDatabase encryption key.
[in]flagsControl over the database connection (see http://www.sqlite.org/c3ref/open.html for further information). Flag values are prefixed by WX to distinguish them from the original SQLite flag values.
[in]vfsName of VFS to be used. Use the VFS name prefix "multipleciphers-" to enable encryption support. An empty VFS name refers to the default VFS.

◆ Open() [2/4]

void wxSQLite3Database::Open ( const wxString & fileName,
const wxSQLite3Cipher & cipher,
const wxMemoryBuffer & key,
int flags = WXSQLITE_OPEN_READWRITE | WXSQLITE_OPEN_CREATE,
const wxString & vfs = wxEmptyString )

Open a SQLite3 database using a binary key.

Opens the SQLite database file "filename". The "filename" is UTF-8 encoded. If the database could not be opened (or created) successfully, then an exception is thrown. If the database file does not exist, then a new database will be created as needed.

Parameters
[in]fileNameName of the database file.
[in]cipherCipher to be used for database encryption.
[in]keyDatabase encryption key.
[in]flagsControl over the database connection (see http://www.sqlite.org/c3ref/open.html for further information). Flag values are prefixed by WX to distinguish them from the original SQLite flag values.
[in]vfsName of VFS to be used. Use the VFS name prefix "multipleciphers-" to enable encryption support. An empty VFS name refers to the default VFS.

◆ Open() [3/4]

void wxSQLite3Database::Open ( const wxString & fileName,
const wxSQLite3Cipher & cipher,
const wxString & key,
int flags = WXSQLITE_OPEN_READWRITE | WXSQLITE_OPEN_CREATE,
const wxString & vfs = wxEmptyString )

Open a SQLite3 database.

Opens the SQLite database file "filename". The "filename" is UTF-8 encoded. If the database could not be opened (or created) successfully, then an exception is thrown. If the database file does not exist, then a new database will be created as needed.

Parameters
[in]fileNameName of the database file.
[in]cipherCipher to be used for database encryption.
[in]keyDatabase encryption key.
[in]flagsControl over the database connection (see http://www.sqlite.org/c3ref/open.html for further information). Flag values are prefixed by WX to distinguish them from the original SQLite flag values.
[in]vfsName of VFS to be used. Use the VFS name prefix "multipleciphers-" to enable encryption support. An empty VFS name refers to the default VFS.

◆ Open() [4/4]

void wxSQLite3Database::Open ( const wxString & fileName,
const wxString & key = wxEmptyString,
int flags = WXSQLITE_OPEN_READWRITE | WXSQLITE_OPEN_CREATE,
const wxString & vfs = wxEmptyString )

Open a SQLite3 database.

Opens the SQLite database file "filename". The "filename" is UTF-8 encoded. If the database could not be opened (or created) successfully, then an exception is thrown. If the database file does not exist, then a new database will be created as needed.

Parameters
[in]fileNameName of the database file.
[in]keyDatabase encryption key.
[in]flagsControl over the database connection (see http://www.sqlite.org/c3ref/open.html for further information). Flag values are prefixed by WX to distinguish them from the original SQLite flag values.
[in]vfsName of VFS to be used. Use the VFS name prefix "multipleciphers-" to enable encryption support. An empty VFS name refers to the default VFS.

◆ PreparePersistentStatement() [1/3]

wxSQLite3Statement wxSQLite3Database::PreparePersistentStatement ( const char * sql)

Prepare a (long-lasting) SQL query statement given as a utf-8 character string for parameter binding.

Parameters
sqlquery string
Returns
statement instance

SQLite3 assumes that this prepared statement will be retained for a long time and probably reused many times.

◆ PreparePersistentStatement() [2/3]

wxSQLite3Statement wxSQLite3Database::PreparePersistentStatement ( const wxSQLite3StatementBuffer & sql)

Prepare a (long-lasting) SQL query statement given as a statement buffer for parameter binding.

Parameters
sqlquery string
Returns
statement instance

SQLite3 assumes that this prepared statement will be retained for a long time and probably reused many times.

◆ PreparePersistentStatement() [3/3]

wxSQLite3Statement wxSQLite3Database::PreparePersistentStatement ( const wxString & sql)

Prepare a (long-lasting) SQL query statement given as a wxString for parameter binding.

Parameters
sqlquery string
Returns
statement instance

SQLite3 assumes that this prepared statement will be retained for a long time and probably reused many times.

◆ PrepareStatement() [1/3]

wxSQLite3Statement wxSQLite3Database::PrepareStatement ( const char * sql)

Prepare a SQL query statement given as a utf-8 character string for parameter binding.

Parameters
sqlquery string
Returns
statement instance

◆ PrepareStatement() [2/3]

wxSQLite3Statement wxSQLite3Database::PrepareStatement ( const wxSQLite3StatementBuffer & sql)

Prepare a SQL query statement given as a statement buffer for parameter binding.

Parameters
sqlquery string
Returns
statement instance

◆ PrepareStatement() [3/3]

wxSQLite3Statement wxSQLite3Database::PrepareStatement ( const wxString & sql)

Prepare a SQL query statement given as a wxString for parameter binding.

Parameters
sqlquery string
Returns
statement instance

◆ QueryRollbackState()

int wxSQLite3Database::QueryRollbackState ( ) const

Query the return code of the last rollback.

When using the class wxSQLite3Transaction there is the possibility that the automatic rollback which is executed in case of an exception fails. This method allows to query the return code of that operation to check whether the automatic rollback succeeded or not.

Returns
the return code of the last rollback.
Note
In case of a successful rollback the value 0 is returned.

◆ QueryTransactionState()

wxSQLite3TransactionState wxSQLite3Database::QueryTransactionState ( const wxString & schemaName = wxEmptyString) const

Query the transaction state of a database.

Describes the transaction state of the given schema in the database connection. If no schema is given, then the highest transaction state of any schema on the database connection is returned. The transaction state can be one of the following:

  • WXSQLITE_TRANSACTION_NONE : No transaction is currently pending.
  • WXSQLITE_TRANSACTION_READ : The database is currently in a read transaction. Content has been read from the database file but nothing in the database file has changed. The transaction state will advanced to WXSQLITE_TRANSACTION_WRITE if any changes occur and there are no other conflicting concurrent write transactions. The transaction state will revert to WXSQLITE_TRANSACTION_NONE following a ROLLBACK or COMMIT.
  • WXSQLITE_TRANSACTION_WRITE : The database is currently in a write transaction. Content has been written to the database file but has not yet committed. The transaction state will change to to WXSQLITE_TRANSACTION_NONE at the next ROLLBACK or COMMIT.
    Parameters
    [in]schemaNameName of the schema (optional)
    Returns
    the return code of the last rollback.
    Note
    In case of a successful rollback the value 0 is returned.

◆ Randomness()

bool wxSQLite3Database::Randomness ( int n,
wxMemoryBuffer & random )
static

Get random bytes.

SQLite contains a high-quality pseudo-random number generator. This method allows to access it for application specific purposes.

Parameters
nThe amount of random bytes to be created
randomA memory buffer containing the random bytes on return

◆ ReKey() [1/4]

void wxSQLite3Database::ReKey ( const wxMemoryBuffer & newKey)

Change the encryption key of the database.

If the database is currently not encrypted, this method will encrypt it. If an empty key (with key length == 0) is given, the database is decrypted.

Parameters
newKeyThe new encryption key

◆ ReKey() [2/4]

void wxSQLite3Database::ReKey ( const wxSQLite3Cipher & cipher,
const wxMemoryBuffer & newKey )

◆ ReKey() [3/4]

void wxSQLite3Database::ReKey ( const wxSQLite3Cipher & cipher,
const wxString & newKey )

◆ ReKey() [4/4]

void wxSQLite3Database::ReKey ( const wxString & newKey)

Change the encryption key of the database.

If the database is currently not encrypted, this method will encrypt it. If an empty key (with key length == 0) is given, the database is decrypted.

Parameters
newKeyThe new encryption key (will be converted to UTF-8)

◆ ReleaseMemory()

void wxSQLite3Database::ReleaseMemory ( )

Free memory used by a database connection.

This method attempts to free as much heap memory as possible from database connection. Consult the SQLite documentation for further explanation.

◆ ReleaseSavepoint()

void wxSQLite3Database::ReleaseSavepoint ( const wxString & savepointName)

Release savepoint.

◆ RemoveAuthorizer()

bool wxSQLite3Database::RemoveAuthorizer ( )

Remove a user-defined authorizer function.

Removes a previously registered authorizer object.

Returns
TRUE on successful removal, FALSE otherwise

◆ Restore() [1/8]

void wxSQLite3Database::Restore ( const wxString & sourceFileName,
const wxMemoryBuffer & key,
const wxString & targetDatabaseName = wxS("main") )

Restore a SQLite3 database.

This method is used to restore the contents of this database with the contents of another database. This is useful either for restoring a backup of the database or for copying a persistent file to an in-memory database.

NOTE: Exclusive access is required to the target database for the duration of the operation. However the source database is only read-locked while it is actually being read, it is not locked continuously for the entire operation. Thus, the backup may be performed on a live database without preventing other users from writing to the database for an extended period of time.

Parameters
[in]sourceFileNameName of the source database file.
[in]keyOptional binary database encryption key for the source database.
[in]targetDatabaseNameOptional name of the target database (default: 'main').

◆ Restore() [2/8]

void wxSQLite3Database::Restore ( const wxString & sourceFileName,
const wxSQLite3Cipher & cipher,
const wxMemoryBuffer & key,
const wxString & targetDatabaseName = wxS("main") )

◆ Restore() [3/8]

void wxSQLite3Database::Restore ( const wxString & sourceFileName,
const wxSQLite3Cipher & cipher,
const wxString & key,
const wxString & targetDatabaseName = wxS("main") )

◆ Restore() [4/8]

void wxSQLite3Database::Restore ( const wxString & sourceFileName,
const wxString & key = wxEmptyString,
const wxString & targetDatabaseName = wxS("main") )

Restore a SQLite3 database.

This method is used to restore the contents of this database with the contents of another database. This is useful either for restoring a backup of the database or for copying a persistent file to an in-memory database.

NOTE: Exclusive access is required to the target database for the duration of the operation. However the source database is only read-locked while it is actually being read, it is not locked continuously for the entire operation. Thus, the backup may be performed on a live database without preventing other users from writing to the database for an extended period of time.

Parameters
[in]sourceFileNameName of the source database file.
[in]keyOptional database encryption key for the source database.
[in]targetDatabaseNameOptional name of the target database (default: 'main').

◆ Restore() [5/8]

void wxSQLite3Database::Restore ( wxSQLite3BackupProgress * progressCallback,
const wxString & sourceFileName,
const wxMemoryBuffer & key,
const wxString & targetDatabaseName = wxS("main") )

◆ Restore() [6/8]

void wxSQLite3Database::Restore ( wxSQLite3BackupProgress * progressCallback,
const wxString & sourceFileName,
const wxSQLite3Cipher & cipher,
const wxMemoryBuffer & key,
const wxString & targetDatabaseName = wxS("main") )

◆ Restore() [7/8]

void wxSQLite3Database::Restore ( wxSQLite3BackupProgress * progressCallback,
const wxString & sourceFileName,
const wxSQLite3Cipher & cipher,
const wxString & key,
const wxString & targetDatabaseName = wxS("main") )

◆ Restore() [8/8]

void wxSQLite3Database::Restore ( wxSQLite3BackupProgress * progressCallback,
const wxString & sourceFileName,
const wxString & key = wxEmptyString,
const wxString & targetDatabaseName = wxS("main") )

◆ Rollback()

void wxSQLite3Database::Rollback ( const wxString & savepointName = wxEmptyString)

Rollback transaction.

Rolls back a transaction or optionally to a previously set savepoint

Parameters
savepointNameoptional name of a previously set savepoint

◆ Savepoint()

void wxSQLite3Database::Savepoint ( const wxString & savepointName)

Set savepoint.

◆ SetAuthorizer()

bool wxSQLite3Database::SetAuthorizer ( wxSQLite3Authorizer & authorizer)

Create a user-defined authorizer function.

Registers an authorizer object with the SQLite library. The authorizer is invoked (at compile-time, not at run-time) for each attempt to access a column of a table in the database. The authorizer should return SQLITE_OK if access is allowed, SQLITE_DENY if the entire SQL statement should be aborted with an error and SQLITE_IGNORE if the column should be treated as a NULL value.

Parameters
authorizerinstance of an authorizer function
Returns
TRUE on successful registration, FALSE otherwise

◆ SetBackupRestorePageCount()

void wxSQLite3Database::SetBackupRestorePageCount ( int pageCount)

Set the page count for backup or restore operations.

Backup and restore operations perform in slices of a given number of pages. This method allows to set the size of a slice. The default size is 10 pages.

Parameters
[in]pageCountnumber of pages to be copied in one slice.

◆ SetBusyTimeout()

void wxSQLite3Database::SetBusyTimeout ( int milliSeconds)

Set the busy timeout.

This method sets a busy handler that sleeps for a while when a table is locked. The handler will sleep multiple times until at least "ms" milliseconds of sleeping have been done. Calling this routine with an argument less than or equal to zero turns off all busy handlers.

Parameters
milliSecondstimeout in milliseconds

◆ SetCollation()

void wxSQLite3Database::SetCollation ( const wxString & name,
wxSQLite3Collation * collation )

Create a user-defined collation sequence.

Registers a callback function object to be invoked whenever this collation is needed in comparing strings. Registering a NULL function object disables the specified collation sequence.

Parameters
namename of a user-defined collation sequence
collationaddress of an instance of a user-defined collation sequence

◆ SetCollationNeededCallback()

void wxSQLite3Database::SetCollationNeededCallback ( )
protected

Activate the callback for needed collations for this database.

To avoid having to register all collation sequences before a database can be used, a single callback function may be registered with the database handle to be called whenever an undefined collation sequence is required.

◆ SetCommitHook()

void wxSQLite3Database::SetCommitHook ( wxSQLite3Hook * commitHook)

Create a user-defined commit callback function.

Registers a callback function object to be invoked whenever a new transaction is committed. If the callback function returns non-zero, then the commit is converted into a rollback. Registering a NULL function object disables the callback. Only a single commit hook callback can be registered at a time.

Parameters
commitHookaddress of an instance of a commit callback function

◆ SetJournalMode()

wxSQLite3JournalMode wxSQLite3Database::SetJournalMode ( wxSQLite3JournalMode mode,
const wxString & database = wxEmptyString )

Set SQLite journal mode.

Parameters
modethe journal mode to be set
databasethe attached database for which the journal mode should be set. If not given then the journal mode of all attached databases is set.
Returns
the active journal mode
Note
The journal mode for an in-memory database is either MEMORY or OFF and can not be changed to a different value. An attempt to change the journal mode of an in-memory database to any setting other than MEMORY or OFF is ignored. Note also that the journal mode cannot be changed while a transaction is active. The WAL journaling mode uses a write-ahead log instead of a rollback journal to implement transactions. The WAL journaling mode is persistent; after being set it stays in effect across multiple database connections and after closing and reopening the database. A database in WAL journaling mode can only be accessed by SQLite version 3.7.0 or later.

◆ SetLimit()

int wxSQLite3Database::SetLimit ( wxSQLite3LimitType id,
int newValue )

Change a database limit to a new value.

This method allows to change several database limits. Consult the SQLite documentation for further explanation.

Parameters
idThe identifier of the limit to be queried
newValueThe new value of the limit to be set
Returns
the previous value of the specified limit

◆ SetNeededCollation()

virtual void wxSQLite3Database::SetNeededCollation ( const wxString & WXUNUSEDcollationName)
inlineprotectedvirtual

Request the instantiation of a user defined collation sequence.

This method is called for every undefined collation sequence. In a derived database class this method should call SetCollation registering an appropriate collation class instance.

Parameters
collationNamename of the collation which is needed for string comparison

◆ SetRollbackHook()

void wxSQLite3Database::SetRollbackHook ( wxSQLite3Hook * rollbackHook)

Create a user-defined rollback callback function.

Registers a callback function object to be invoked whenever a transaction is rolled back. Registering a NULL function object disables the callback. Only a single rollback hook callback can be registered at a time.

For the purposes of this API, a transaction is said to have been rolled back if an explicit "ROLLBACK" statement is executed, or an error or constraint causes an implicit rollback to occur. The callback is not invoked if a transaction is automatically rolled back because the database connection is closed.

Parameters
rollbackHookaddress of an instance of a rollback callback function

◆ SetSharedCache()

void wxSQLite3Database::SetSharedCache ( bool enable)
static

Enable or disable SQLite shared cache.

The cache sharing mode set effects all subsequent database connections. Existing database connections continue use the sharing mode that was in effect at the time they were opened.

Virtual tables cannot be used with a shared cache.

◆ SetTemporaryDirectory()

bool wxSQLite3Database::SetTemporaryDirectory ( const wxString & tempDirectory)
static

Set temporary directory where SQLite stores temporary files (Windows only)

On Windows platforms it is recommended to set the temporary directory before using any SQLite databases. This method should not be called if you have currently open database connections.

Returns
TRUE if the temporary directory could be set successfully, FALSE otherwise
Note
This method is supported only for Windows platforms and SQLite versions 3.7.14 or above. For all other platforms FALSE is returned.

◆ SetUpdateHook()

void wxSQLite3Database::SetUpdateHook ( wxSQLite3Hook * updateHook)

Create a user-defined update callback function.

Registers a callback function object to be invoked whenever a row is updated, inserted or deleted. Registering a NULL function object disables the callback. Only a single commit hook callback can be registered at a time. The update hook is not invoked when internal system tables are modified (i.e. sqlite_master and sqlite_sequence).

Parameters
updateHookaddress of an instance of an update callback function

◆ SetWriteAheadLogHook()

void wxSQLite3Database::SetWriteAheadLogHook ( wxSQLite3Hook * walHook)

Create a user-defined Write Ahead Log callback function.

Registers a callback function object to be invoked whenever a commit has taken place in WAL journal mode. Registering a NULL function object disables the callback. Only a single Write Ahead Log hook callback can be registered at a time.

Parameters
walHookaddress of an instance of a Write Ahead Log callback function

◆ ShutdownSQLite()

void wxSQLite3Database::ShutdownSQLite ( )
static

Shutdown the SQLite library.

Starting with SQLite version 3.6.0 there is a new method to shutdown the SQLite library. Currently an explicit call to this method is not required, but this behaviour might change in the future of SQLite. Therefore it is recommended to call this method once when no further access to any SQLite databases is required.

◆ TableExists() [1/2]

bool wxSQLite3Database::TableExists ( const wxString & tableName,
const wxString & databaseName = wxEmptyString )

Check whether a table with the given name exists.

Checks the main database or a specific attached database for existence of a table with a given name.

Parameters
tableNamename of the table
databaseNameoptional name of an attached database
Returns
TRUE if the table exists, FALSE otherwise

◆ TableExists() [2/2]

bool wxSQLite3Database::TableExists ( const wxString & tableName,
wxArrayString & databaseNames )

Check whether a table with the given name exists in the main database or any attached database.

Parameters
tableNamename of the table
databaseNameslist of the names of those databases in which the table exists
Returns
TRUE if the table exists at least in one database, FALSE otherwise

◆ UserAdd()

bool wxSQLite3Database::UserAdd ( const wxString & username,
const wxString & password,
bool isAdmin = false )

Add a user to a database with user authentication.

Parameters
usernamename of the user to be added
passwordpassword
isAdminTRUE to give the new user admin privileges (default: FALSE)
Returns
TRUE if the authentication succeeded, FALSE otherwise

◆ UserChange()

bool wxSQLite3Database::UserChange ( const wxString & username,
const wxString & password,
bool isAdmin )

Change password and/or privileges of a user on a database with user authentication.

Parameters
usernamename of the user for which the credentials should be changed
passwordmodified password
isAdminmodified admin privilege
Returns
TRUE if the credentials could be changed, FALSE otherwise

◆ UserDelete()

bool wxSQLite3Database::UserDelete ( const wxString & username)

Delete a user from a database with user authentication.

Parameters
usernamename of the user to be removed
Returns
TRUE if the user could be deleted, FALSE otherwise

◆ UserIsPrivileged()

bool wxSQLite3Database::UserIsPrivileged ( const wxString & username)

Check whether a user of a database with user authentication is privileged.

Parameters
usernamename of the user to be checked
Returns
TRUE if the user exists and is privileged, FALSE otherwise

◆ UserLogin()

bool wxSQLite3Database::UserLogin ( const wxString & username,
const wxString & password )

Authenticate the user on a database with user authentication.

Parameters
usernamename of the user to be authenticated
passwordpassword
Returns
TRUE if the authentication succeeded, FALSE otherwise

◆ Vacuum()

void wxSQLite3Database::Vacuum ( )

Vacuum.

Performs a VACUUM operation on the database.

◆ WriteAheadLogCheckpoint()

void wxSQLite3Database::WriteAheadLogCheckpoint ( const wxString & database,
int mode = WXSQLITE_CHECKPOINT_PASSIVE,
int * logFrameCount = NULL,
int * ckptFrameCount = NULL )

Checkpoint database in write-ahead log mode.

Causes an optionally named database to be checkpointed. If no database name is given, then a checkpoint is run on all databases associated with this database instance. If the database instance is not in write-ahead log mode then this method is a harmless no-op.

Parameters
databasename of a database to be checkpointed
modecheckpoint mode, allowed values: WXSQLITE_CHECKPOINT_PASSIVE (default), WXSQLITE_CHECKPOINT_FULL, WXSQLITE_CHECKPOINT_RESTART (see http://www.sqlite.org/c3ref/wal_checkpoint_v2.html)
logFrameCountsize of write-ahead log in frames
ckptFrameCountnumber of frames actually checkpointed
Note
The frame counts are set to zero if the SQLite version is below 3.7.6.

Friends And Related Symbol Documentation

◆ wxSQLite3Cipher

friend class wxSQLite3Cipher
friend

The documentation for this class was generated from the following files: