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]	fileName	Name of the database file that should be attached.
[in]	schemaName	Name 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]	fileName	Name of the database file that should be attached.
[in]	schemaName	Name of the schema that should be used for the attached database.
[in]	cipher	Cipher to be used for database encryption.
[in]	key	Pass 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]	fileName	Name of the database file that should be attached.
[in]	schemaName	Name of the schema that should be used for the attached database.
[in]	key	Pass 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

frameCount frame 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]	targetFileName	Name of the target database file.
[in]	key	Binary database encryption key for the target database.
[in]	sourceDatabaseName	Optional 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]	targetFileName	Name of the target database file.
[in]	key	Optional database encryption key for the target database.
[in]	sourceDatabaseName	Optional 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] transactionType type 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

sql	query 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

sql	query 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

sql	query 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

optionName name 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

mode	the 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

mode	the 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

funcName	name of the aggregate function
argCount	number of arguments the aggregate function takes. If this argument is -1 then the aggregate function may take any number of arguments.
function	instance of an aggregate function
flags	specifies 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

funcName	name of the scalar function
argCount	number of arguments the scalar function takes. If this argument is -1 then the scalar function may take any number of arguments.
function	instance of an scalar function
flags	specifies 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

funcName	name of the aggregate window function
argCount	number of arguments the aggregate window function takes. If this argument is -1 then the aggregate function may take any number of arguments.
function	instance of an aggregate window function
flags	specifies 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

collectionName name 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

collectionName name 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

enable Flag 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

sql	query 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

sql	query string

Returns: result set instance

◆ ExecuteQuery() [3/3]

wxSQLite3ResultSet wxSQLite3Database::ExecuteQuery ( const wxString & sql )

Execute a SQL query statement given as a wxString.

Parameters

sql	query 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

sql	query 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

sql	query 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

sql	query 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

sql	query string
saveRC	flag 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

sql	query 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

sql	query 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

optionIndex Index 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

databaseName contains 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

databaseNames contains 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

databaseNames	contains on return the list of the database names
databaseFiles	contains on return the list of the database file names

◆ GetJournalMode()

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

Get the active SQLite journal mode.

Parameters

database the 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

schemaName The 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

id	The 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

dbName	is 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.
tableName	name of the database table
columnName	name of the database column
dataType	declared data type of the column. Pass NULL if information not needed.
collation	name of the collation sequence. Pass NULL if information is not needed.
notNull	output flag whether the column has a not null constraint. Pass NULL if information not needed.
primaryKey	output flag whether the column is part of the primary key. Pass NULL if information not needed.
autoIncrement	output 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

sql	query 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

sql	query 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

sql	query 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

userList array 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] databaseName Name 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

type	The 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

fileName	Name of the shared library containing extension.
entryPoint	Name 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]	fileName	Name of the database file.
[in]	key	Database encryption key.
[in]	flags	Control 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]	vfs	Name 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]	fileName	Name of the database file.
[in]	cipher	Cipher to be used for database encryption.
[in]	key	Database encryption key.
[in]	flags	Control 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]	vfs	Name 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]	fileName	Name of the database file.
[in]	cipher	Cipher to be used for database encryption.
[in]	key	Database encryption key.
[in]	flags	Control 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]	vfs	Name 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]	fileName	Name of the database file.
[in]	key	Database encryption key.
[in]	flags	Control 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]	vfs	Name 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

sql	query 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

sql	query 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

sql	query 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

sql	query 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

sql	query 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

sql	query 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] schemaName Name 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

n	The amount of random bytes to be created
random	A 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

newKey The 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

newKey The 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]	sourceFileName	Name of the source database file.
[in]	key	Optional binary database encryption key for the source database.
[in]	targetDatabaseName	Optional 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]	sourceFileName	Name of the source database file.
[in]	key	Optional database encryption key for the source database.
[in]	targetDatabaseName	Optional 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

savepointName optional 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

authorizer instance 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] pageCount number 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

milliSeconds timeout 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

name	name of a user-defined collation sequence
collation	address 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

commitHook address of an instance of a commit callback function

◆ SetJournalMode()

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

Set SQLite journal mode.

Parameters

mode	the journal mode to be set
database	the 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

id	The identifier of the limit to be queried
newValue	The 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

collationName name 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

rollbackHook address 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

updateHook address 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

walHook address 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

tableName	name of the table
databaseName	optional 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

tableName	name of the table
databaseNames	list 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

username	name of the user to be added
password	password
isAdmin	TRUE 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

username	name of the user for which the credentials should be changed
password	modified password
isAdmin	modified 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

username name 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

username name 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

username	name of the user to be authenticated
password	password

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

database	name of a database to be checkpointed
mode	checkpoint mode, allowed values: WXSQLITE_CHECKPOINT_PASSIVE (default), WXSQLITE_CHECKPOINT_FULL, WXSQLITE_CHECKPOINT_RESTART (see http://www.sqlite.org/c3ref/wal_checkpoint_v2.html)
logFrameCount	size of write-ahead log in frames
ckptFrameCount	number 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:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ wxSQLite3Database()

◆ ~wxSQLite3Database()

Member Function Documentation

◆ AttachDatabase() [1/3]

◆ AttachDatabase() [2/3]

◆ AttachDatabase() [3/3]

◆ AutoWriteAheadLogCheckpoint()

◆ Backup() [1/8]

◆ Backup() [2/8]

◆ Backup() [3/8]

◆ Backup() [4/8]

◆ Backup() [5/8]

◆ Backup() [6/8]

◆ Backup() [7/8]

◆ Backup() [8/8]

◆ Begin()

◆ CheckSyntax() [1/3]

◆ CheckSyntax() [2/3]

◆ CheckSyntax() [3/3]

◆ Close()

◆ Commit()

◆ CompileOptionUsed()

◆ ConvertJournalMode() [1/2]

◆ ConvertJournalMode() [2/2]

◆ CreateFunction() [1/3]

◆ CreateFunction() [2/3]

◆ CreateFunction() [3/3]

◆ CreateIntegerCollection()

◆ CreateStringCollection()

◆ DetachDatabase()

◆ EnableForeignKeySupport()

◆ EnableLoadExtension()

◆ ExecCollationNeeded()

◆ ExecComparisonWithCollation()

◆ ExecuteQuery() [1/3]

◆ ExecuteQuery() [2/3]

◆ ExecuteQuery() [3/3]

◆ ExecuteScalar() [1/3]

◆ ExecuteScalar() [2/3]

◆ ExecuteScalar() [3/3]

◆ ExecuteUpdate() [1/3]

◆ ExecuteUpdate() [2/3]

◆ ExecuteUpdate() [3/3]

◆ GetAutoCommit()

◆ GetBlob()

◆ GetCompileOptionName()

◆ GetDatabaseFilename()

◆ GetDatabaseHandle()

◆ GetDatabaseList() [1/2]

◆ GetDatabaseList() [2/2]

◆ GetJournalMode()

◆ GetKeySalt()

◆ GetLastRowId()

◆ GetLimit()

◆ GetMetaData()

◆ GetReadOnlyBlob()

◆ GetSourceId()

◆ GetSystemErrorCode()

◆ GetTable() [1/3]

◆ GetTable() [2/3]

◆ GetTable() [3/3]

◆ GetUserList()

◆ GetVersion()

◆ GetWrapperVersion()

◆ GetWritableBlob()

◆ HasBackupSupport()

◆ HasEncryptionSupport()

◆ HasIncrementalBlobSupport()

◆ HasLoadExtSupport()

◆ HasMetaDataSupport()

◆ HasNamedCollectionSupport()

◆ HasPointerParamsSupport()

◆ HasSavepointSupport()