Administration of the database and all concerning settings. More...

#include <KompexSQLiteDatabase.h>

Public Types
enum	UtfEncoding { UTF8, UTF16 }
	Provided encodings for MoveDatabaseToMemory(). More...

Public Member Functions
	SQLiteDatabase ()

	SQLiteDatabase (const char filename, int flags, const char zVfs)

	SQLiteDatabase (const std::string &filename, int flags, const char *zVfs)

	SQLiteDatabase (const wchar_t *filename)

virtual	~SQLiteDatabase ()
	Destructor. More...

void	Open (const char filename, int flags, const char zVfs)

void	Open (const std::string &filename, int flags, const char *zVfs)

void	Open (const wchar_t *filename)

void	Close ()
	Closes a connection to a SQLite database file. More...

sqlite3 *	GetDatabaseHandle () const
	Returns the SQLite db handle. More...

int	GetLibVersionNumber () const
	Returns the version number of sqlite. More...

int	GetDatabaseChanges () const

int	GetTotalDatabaseChanges () const

void	InterruptDatabaseOperation () const

int	GetAutoCommit () const

void	ActivateTracing () const

void	ActivateProfiling () const

void	SetSoftHeapLimit (int heapLimit) const

int	ReleaseMemory (int bytesOfMemory) const

long long	GetMemoryUsage () const
	GetMemoryUsed() returns the number of bytes of memory currently outstanding (malloced but not freed). More...

long long	GetMemoryHighwaterMark (bool resetFlag=false) const

void	MoveDatabaseToMemory (UtfEncoding encoding=UTF8)

void	SaveDatabaseFromMemoryToFile (const std::string &filename="")

void	SaveDatabaseFromMemoryToFile (const wchar_t *filename)

long long	GetLastInsertRowId () const

bool	IsDatabaseReadOnly ()

void	ReleaseMemory ()
	This function attempts to free as much heap memory as possible from the database connection. More...

void	CreateModule (const std::string &moduleName, const sqlite3_module module, void clientData, void(xDestroy)(void ))

int	GetNumberOfCheckedOutLookasideMemorySlots () const
	Returns the number of lookaside memory slots currently checked out. More...

int	GetHeapMemoryUsedByPagerCaches () const
	Returns the approximate number of bytes of heap memory used by all pager caches. More...

int	GetHeapMemoryUsedToStoreSchemas () const

int	GetHeapAndLookasideMemoryUsedByPreparedStatements () const

int	GetPagerCacheHitCount () const
	Returns the number of pager cache hits that have occurred. More...

int	GetPagerCacheMissCount () const
	Returns the number of pager cache misses that have occurred. More...

int	GetNumberOfDirtyCacheEntries () const

int	GetNumberOfUnresolvedForeignKeys () const
	Returns zero if all foreign key constraints (deferred or immediate) have been resolved. More...

int	GetHighestNumberOfCheckedOutLookasideMemorySlots (bool resetValue=false)

int	GetLookasideMemoryHitCount (bool resetValue=false)

int	GetLookasideMemoryMissCountDueToSmallSlotSize (bool resetValue=false)

int	GetLookasideMemoryMissCountDueToFullMemory (bool resetValue=false)

Protected Member Functions
void	TakeSnapshot (sqlite3 *destinationDatabase)
	Takes and saves a snapshot of the memory database in a file. More...

int	GetRuntimeStatusInformation (int operation, bool highwaterValue=false, bool resetFlag=false) const
	Returns internal runtime status information associated with the current database connection. More...

Static Protected Member Functions
static void	TraceOutput (void ptr, const char sql)
	Callback function for ActivateTracing() [sqlite3_trace]. More...

static void	ProfileOutput (void ptr, const char sql, sqlite3_uint64 time)
	Callback function for ActivateProfiling() [sqlite3_profile]. More...

static int	ProcessDDLRow (void db, int nColumns, char values, char *columns)
	Build and modify the structure of your tables and other objects in the memory database. More...

static int	ProcessDMLRow (void db, int nColumns, char values, char *columns)
	Insert all data from the origin database into the memory database. More...

Private Member Functions
void	CleanUpFailedMemoryDatabase (sqlite3 memoryDatabase, sqlite3 rollbackDatabase, bool isDetachNecessary, bool isRollbackNecessary, sqlite3_stmt *stmt, const std::string &errMsg, int internalSqliteErrCode)
	Clean up routine if something failed in MoveDatabaseToMemory() More...

Private Attributes
struct sqlite3 *	mDatabaseHandle
	SQLite db handle. More...

std::string	mDatabaseFilenameUtf8
	Database filename UTF-8. More...

std::wstring	mDatabaseFilenameUtf16
	Database filename UTF-16. More...

bool	mIsMemoryDatabaseActive
	Is the database currently stored in memory? More...

Detailed Description

Administration of the database and all concerning settings.

Member Enumeration Documentation

enum Kompex::SQLiteDatabase::UtfEncoding

Provided encodings for MoveDatabaseToMemory().

Enumerator
UTF8
UTF16

Constructor & Destructor Documentation

Kompex::SQLiteDatabase::SQLiteDatabase ( )

Default constructor.
Closes automatically the connection to a SQLite database file.

Kompex::SQLiteDatabase::SQLiteDatabase	(	const char *	filename,
		int	flags,
		const char *	zVfs
	)

Overloaded constructor.
Opens a connection to a SQLite database file.

Parameters

filename	Database filename (UTF-8)
flags	Flags SQLITE_OPEN_READONLY The database is opened in read-only mode. If the database does not already exist, an error is returned. SQLITE_OPEN_READWRITE The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned. SQLITE_OPEN_READWRITE \| SQLITE_OPEN_CREATE The database is opened for reading and writing, and is creates it if it does not already exist.
zVfs	Name of VFS module to use NULL for default

Kompex::SQLiteDatabase::SQLiteDatabase	(	const std::string &	filename,
		int	flags,
		const char *	zVfs
	)

Overloaded constructor.
Opens a connection to a SQLite database file.

Parameters

filename	Database filename (UTF-8)
flags	Flags SQLITE_OPEN_READONLY The database is opened in read-only mode. If the database does not already exist, an error is returned. SQLITE_OPEN_READWRITE The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned. SQLITE_OPEN_READWRITE \| SQLITE_OPEN_CREATE The database is opened for reading and writing, and is creates it if it does not already exist.
zVfs	Name of VFS module to use NULL for default

Kompex::SQLiteDatabase::SQLiteDatabase ( const wchar_t * filename )

Overloaded constructor.
Opens a connection to a SQLite database file.

Parameters

filename Database filename (UTF-16)

Kompex::SQLiteDatabase::~SQLiteDatabase ( )

virtual

Destructor.

Member Function Documentation

void Kompex::SQLiteDatabase::ActivateProfiling ( ) const

inline

Profile() is invoked as each SQL statement finishes.
The profile callback contains the original statement text
and an estimate of wall-clock time of how long that statement took to run.
Note: time in ns
Output: std::cout

void Kompex::SQLiteDatabase::ActivateTracing ( ) const

inline

Trace() is invoked at various times when a SQL statement is being run by FetchRow(), SqlStatement() or ExecuteAndFree().
The callback returns a UTF-8 rendering of the SQL statement text as the statement first begins executing.
Output: std::cout

void Kompex::SQLiteDatabase::CleanUpFailedMemoryDatabase	(	sqlite3 *	memoryDatabase,
		sqlite3 *	rollbackDatabase,
		bool	isDetachNecessary,
		bool	isRollbackNecessary,
		sqlite3_stmt *	stmt,
		const std::string &	errMsg,
		int	internalSqliteErrCode
	)

private

Clean up routine if something failed in MoveDatabaseToMemory()

void Kompex::SQLiteDatabase::Close ( )

Closes a connection to a SQLite database file.

void Kompex::SQLiteDatabase::CreateModule	(	const std::string &	moduleName,
		const sqlite3_module *	module,
		void *	clientData,
		void()(void )	xDestroy
	)

This method can be used to register a new virtual table module name. Module names must be
registered before creating a new virtual table using the module and before using a preexisting
virtual table for the module. The module name will be registered with this database handle.

Parameters

moduleName	Name of the module.
module	Pointer to the implementation of the virtual table module.
clientData	Arbitrary client data pointer that is passed through into the xCreate and xConnect methods of the virtual table module when a new virtual table is be being created or reinitialized.
xDestroy	Pointer to a destructor for the clientData. SQLite will invoke the destructor function (if it is not NULL) when SQLite no longer needs the clientData pointer. The destructor will also be invoked if the call to CreateModule() fails.

int Kompex::SQLiteDatabase::GetAutoCommit ( ) const

inline

Returns non-zero or zero if the given database connection is or is not in autocommit mode, respectively.
Autocommit mode is on by default. Autocommit mode is disabled by a BEGIN statement.
Autocommit mode is re-enabled by a COMMIT or ROLLBACK.

int Kompex::SQLiteDatabase::GetDatabaseChanges ( ) const

inline

Returns the number of database rows that were changed, inserted or deleted
by the most recently completed SQL statement.

sqlite3* Kompex::SQLiteDatabase::GetDatabaseHandle ( ) const

inline

Returns the SQLite db handle.

int Kompex::SQLiteDatabase::GetHeapAndLookasideMemoryUsedByPreparedStatements ( ) const

Returns the approximate number of bytes of heap and lookaside memory used by all
prepared statements associated with the database connection.

int Kompex::SQLiteDatabase::GetHeapMemoryUsedByPagerCaches ( ) const

Returns the approximate number of bytes of heap memory used by all pager caches.

int Kompex::SQLiteDatabase::GetHeapMemoryUsedToStoreSchemas ( ) const

Returns the approximate number of bytes of heap memory used to store the schema for
all databases associated with the connection - main, temp, and any ATTACH-ed databases.
The full amount of memory used by the schemas is reported, even if the schema memory is
shared with other database connections due to shared cache mode being enabled.

int Kompex::SQLiteDatabase::GetHighestNumberOfCheckedOutLookasideMemorySlots ( bool resetValue = false )

Returns the highest number of lookaside memory slots that has been checked out.

Parameters

resetValue Allows to reset the highest value.

long long Kompex::SQLiteDatabase::GetLastInsertRowId ( ) const

inline

This function returns the rowid of the most recent successful INSERT into the database.
If no successful INSERTs have ever occurred on that database connection, zero is returned.

What is the rowid?
Each entry in a SQLite table has a unique 64-bit signed integer key called the "rowid".
The rowid is always available as an undeclared column named ROWID, OID or ROWID as long as
those names are not also used by explicitly declared columns. If the table has a column
of type INTEGER PRIMARY KEY then that column is another alias for the rowid.

int Kompex::SQLiteDatabase::GetLibVersionNumber ( ) const

inline

Returns the version number of sqlite.

int Kompex::SQLiteDatabase::GetLookasideMemoryHitCount ( bool resetValue = false )

Returns the number malloc attempts that were satisfied using lookaside memory.

Parameters

resetValue Allows to reset the highest value.

int Kompex::SQLiteDatabase::GetLookasideMemoryMissCountDueToFullMemory ( bool resetValue = false )

Returns the number malloc attempts that might have been satisfied using lookaside memory
but failed due to all lookaside memory already being in use.

Parameters

resetValue Allows to reset the highest value.

int Kompex::SQLiteDatabase::GetLookasideMemoryMissCountDueToSmallSlotSize ( bool resetValue = false )

Returns the number malloc attempts that might have been satisfied using lookaside memory
but failed due to the amount of memory requested being larger than the lookaside slot size.

Parameters

resetValue Allows to reset the highest value.

long long Kompex::SQLiteDatabase::GetMemoryHighwaterMark ( bool resetFlag = false ) const

inline

GetMemoryHighwaterMark() returns the maximum value of used bytes since the high-water mark was last reset.

Parameters

resetFlag The memory high-water mark is reset to the current value of GetMemoryUsage() if resetFlag is true.
The value returned by GetMemoryHighwaterMark(true) is the high-water mark prior to the reset.

long long Kompex::SQLiteDatabase::GetMemoryUsage ( ) const

inline

GetMemoryUsed() returns the number of bytes of memory currently outstanding (malloced but not freed).

int Kompex::SQLiteDatabase::GetNumberOfCheckedOutLookasideMemorySlots ( ) const

Returns the number of lookaside memory slots currently checked out.

int Kompex::SQLiteDatabase::GetNumberOfDirtyCacheEntries ( ) const

Returns the number of dirty cache entries that have been written to disk. Specifically,
the number of pages written to the wal file in wal mode databases, or the number of pages
written to the database file in rollback mode databases. Any pages written as part of
transaction rollback or database recovery operations are not included. If an IO or other
error occurs while writing a page to disk, the effect on subsequent SQLITE_DBSTATUS_CACHE_WRITE
requests is undefined.

int Kompex::SQLiteDatabase::GetNumberOfUnresolvedForeignKeys ( ) const

Returns zero if all foreign key constraints (deferred or immediate) have been resolved.

int Kompex::SQLiteDatabase::GetPagerCacheHitCount ( ) const

Returns the number of pager cache hits that have occurred.

int Kompex::SQLiteDatabase::GetPagerCacheMissCount ( ) const

Returns the number of pager cache misses that have occurred.

int Kompex::SQLiteDatabase::GetRuntimeStatusInformation	(	int	operation,
		bool	highwaterValue = `false`,
		bool	resetFlag = `false`
	)		const

protected

Returns internal runtime status information associated with the current database connection.

int Kompex::SQLiteDatabase::GetTotalDatabaseChanges ( ) const

inline

Returns the total number of row changes caused by INSERT, UPDATE or DELETE statements
since the database connection was opened. The count includes all changes from all trigger contexts.
However, the count does not include changes used to implement REPLACE constraints,
do rollbacks or ABORT processing, or DROP table processing.
The changes are counted as soon as the statement that makes them is completed.

void Kompex::SQLiteDatabase::InterruptDatabaseOperation ( ) const

inline

Causes any pending database operation to abort and return at its earliest opportunity.
This routine 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.

bool Kompex::SQLiteDatabase::IsDatabaseReadOnly ( )

This function returns true if the database was opened in read-only mode an false if the
database was opened in read/write mode.

void Kompex::SQLiteDatabase::MoveDatabaseToMemory ( UtfEncoding encoding = UTF8 )

Move the whole database into memory.
Please pay attention, that after a call of MoveDatabaseToMemory() all sql statements are executed into memory.
i.e. that all changes will be lost after closing the database! Hint: this method can only be used for databases which were openend with a UTF8 filename

Parameters

encoding Encoding which will be used for moving the data.

void Kompex::SQLiteDatabase::Open	(	const char *	filename,
		int	flags,
		const char *	zVfs
	)

Opens a connection to a SQLite database file.
Shut down existing database handle, if one exist.

Parameters

filename	Database filename (UTF-8)
flags	Flags SQLITE_OPEN_READONLY The database is opened in read-only mode. If the database does not already exist, an error is returned. SQLITE_OPEN_READWRITE The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned. SQLITE_OPEN_READWRITE \| SQLITE_OPEN_CREATE The database is opened for reading and writing, and is creates it if it does not already exist.
zVfs	Name of VFS module to use NULL for default

void Kompex::SQLiteDatabase::Open	(	const std::string &	filename,
		int	flags,
		const char *	zVfs
	)

Opens a connection to a SQLite database file. Shut down existing database handle, if one exist.

Parameters

filename	Database filename (UTF-8)
flags	Flags SQLITE_OPEN_READONLY The database is opened in read-only mode. If the database does not already exist, an error is returned. SQLITE_OPEN_READWRITE The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned. SQLITE_OPEN_READWRITE \| SQLITE_OPEN_CREATE The database is opened for reading and writing, and is creates it if it does not already exist.
zVfs	Name of VFS module to use NULL for default

void Kompex::SQLiteDatabase::Open ( const wchar_t * filename )

Opens a connection to a SQLite database file.
Shut down existing database handle, if one exist.

Parameters

filename Database filename (UTF-16)

int Kompex::SQLiteDatabase::ProcessDDLRow	(	void *	db,
		int	nColumns,
		char **	values,
		char **	columns
	)

staticprotected

Build and modify the structure of your tables and other objects in the memory database.

int Kompex::SQLiteDatabase::ProcessDMLRow	(	void *	db,
		int	nColumns,
		char **	values,
		char **	columns
	)

staticprotected

Insert all data from the origin database into the memory database.

void Kompex::SQLiteDatabase::ProfileOutput	(	void *	ptr,
		const char *	sql,
		sqlite3_uint64	time
	)

staticprotected

Callback function for ActivateProfiling() [sqlite3_profile].

int Kompex::SQLiteDatabase::ReleaseMemory ( int bytesOfMemory ) const

inline

The ReleaseMemory() interface attempts to free N bytes of heap memory by deallocating
non-essential memory allocations held by the database library.
Memory used to cache database pages to improve performance is an example of non-essential memory.
ReleaseMemory() returns the number of bytes actually freed, which might be more or less than the amount requested.

Parameters

bytesOfMemory Memory in bytes, which should be freed

void Kompex::SQLiteDatabase::ReleaseMemory ( )

inline

This function attempts to free as much heap memory as possible from the database connection.

void Kompex::SQLiteDatabase::SaveDatabaseFromMemoryToFile ( const std::string & filename = "" )

Takes a snapshot of a database which is located in memory and saves it to a database file.

Parameters

filename Filename for the new database file to which the snapshot will be saved.
When you leave the filename blank, you will overwrite your origin file database.

void Kompex::SQLiteDatabase::SaveDatabaseFromMemoryToFile ( const wchar_t * filename )

Takes a snapshot of a database which is located in memory and saves it to a database file.

Parameters

filename Filename for the new database file to which the snapshot will be saved.

void Kompex::SQLiteDatabase::SetSoftHeapLimit ( int heapLimit ) const

inline

The SetSoftHeapLimit() interface places a "soft" limit on the amount of heap memory that may be allocated by SQLite.
If an internal allocation is requested that would exceed the soft heap limit, sqlite3_release_memory()
is invoked one or more times to free up some space before the allocation is performed.
The limit is called "soft", because if sqlite3_release_memory() cannot free sufficient memory to
prevent the limit from being exceeded, the memory is allocated anyway and the current operation proceeds.
A negative or zero value for heapLimit means that there is no soft heap limit and sqlite3_release_memory()
will only be called when memory is exhausted. The default value for the soft heap limit is zero.

Parameters

heapLimit Heap limit in bytes.

void Kompex::SQLiteDatabase::TakeSnapshot ( sqlite3 * destinationDatabase )

protected

Takes and saves a snapshot of the memory database in a file.

void Kompex::SQLiteDatabase::TraceOutput	(	void *	ptr,
		const char *	sql
	)

staticprotected

Callback function for ActivateTracing() [sqlite3_trace].

Member Data Documentation

std::wstring Kompex::SQLiteDatabase::mDatabaseFilenameUtf16

private

Database filename UTF-16.

std::string Kompex::SQLiteDatabase::mDatabaseFilenameUtf8

private

Database filename UTF-8.

struct sqlite3* Kompex::SQLiteDatabase::mDatabaseHandle

private

SQLite db handle.

bool Kompex::SQLiteDatabase::mIsMemoryDatabaseActive

private

Is the database currently stored in memory?

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

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation