Search Toolkit Book for CSQLITE_Connection

Connection to SQLite database. More...

#include <db/sqlite/sqlitewrapp.hpp>

Inheritance diagram for CSQLITE_Connection:

Collaboration diagram for CSQLITE_Connection:

Public Types
enum	EOperationFlags { fInternalMT = 0x00 , fExternalMT = 0x01 , fDefaultMT = fInternalMT , eAllMT = fInternalMT + fExternalMT , fVacuumOn = 0x00 , fVacuumOff = 0x02 , fVacuumManual = 0x04 , fDefaultVacuum = fVacuumOn , eAllVacuum = fVacuumOn + fVacuumOff + fVacuumManual , fJournalDelete = 0x00 , fJournalTruncate = 0x08 , fJournalPersist = 0x10 , fJournalMemory = 0x20 , fJournalOff = 0x40 , fDefaultJournal = fJournalDelete , eAllJournal , fSyncFull = 0x000 , fSyncOn = 0x080 , fSyncOff = 0x100 , fDefaultSync = fSyncFull , eAllSync = fSyncOff + fSyncOn + fSyncFull , fTempToMemory = 0x000 , fTempToFile = 0x200 , fDefaultTemp = fTempToMemory , eAllTemp = fTempToMemory + fTempToFile , fWritesSync = 0x000 , fWritesAsync = 0x400 , fDefaultWrites = fWritesSync , eAllWrites , fReadOnly = 0x8000 , eDefaultFlags }
	Flags controlling specifics of database connection operation. More...

typedef int	TOperationFlags
	Bit mask of EOperationFlags. More...

Public Member Functions
	CSQLITE_Connection (CTempString file_name, TOperationFlags flags=eDefaultFlags)
	Connect to SQLite database. More...

	~CSQLITE_Connection (void)

const string &	GetFileName (void) const
	Get database file name for the connection. More...

TOperationFlags	GetFlags (void) const
	Get flags controlling database connection operation. More...

void	SetFlags (TOperationFlags flags)
	Change flags controlling database connection operation. More...

void	SetPageSize (unsigned int size)
	Set page size for the database (in bytes). More...

unsigned int	GetPageSize (void)
	Get page size used in the database (in bytes) More...

void	SetCacheSize (unsigned int size)
	Set recommended size of the database cache (number of pages). More...

unsigned int	GetCacheSize (void)
	Get recommended size of the database cache. More...

void	Vacuum (size_t max_free_size)
	Try to shrink database and free up to max_free_size bytes of disk space. More...

CSQLITE_Statement *	CreateVacuumStmt (size_t max_free_size)
	Create statement for executing manual vacuuming. More...

void	ExecuteSql (CTempString sql)
	Execute sql statement without returning any results. More...

void	DeleteDatabase (void)
	Delete database under this connection. More...

sqlite3 *	LockHandle (void)
	Lock and return low-level connection handle. More...

void	UnlockHandle (sqlite3 *handle)
	Unlock unused low-level connection handle. More...

void	SetupNewConnection (sqlite3 *handle)
	Setup newly created low-level connection handle. More...

Static Public Member Functions
static CSQLITE_Connection *	CreateInMemoryDatabase (CTempString file_name, bool shared=false)
	Create a read-only copy of the database in memory. More...

Private Types
typedef CObjPool< sqlite3, CSQLITE_HandleFactory >	THandlePool

Private Member Functions
	CSQLITE_Connection (const CSQLITE_Connection &)

CSQLITE_Connection &	operator= (const CSQLITE_Connection &)

void	x_CheckFlagsValidity (TOperationFlags flags, EOperationFlags mask)
	Check that only one flag in specific group of flags is given. More...

void	x_ExecuteSql (sqlite3 *handle, CTempString sql)
	Execute sql statement on given low-level connection handle. More...

Private Attributes
string	m_FileName
	File name of SQLite database. More...

TOperationFlags	m_Flags
	Flags for object operation. More...

unsigned int	m_PageSize
	Page size inside the database. More...

unsigned int	m_CacheSize
	Recommended size of cache for the database. More...

THandlePool	m_HandlePool
	Pool of low-level database connections. More...

sqlite3 *	m_InMemory

Detailed Description

Connection to SQLite database.

Definition at line 141 of file sqlitewrapp.hpp.

Member Typedef Documentation

◆ THandlePool

typedef CObjPool<sqlite3, CSQLITE_HandleFactory> CSQLITE_Connection::THandlePool

private

Definition at line 341 of file sqlitewrapp.hpp.

◆ TOperationFlags

typedef int CSQLITE_Connection::TOperationFlags

Bit mask of EOperationFlags.

Definition at line 234 of file sqlitewrapp.hpp.

Member Enumeration Documentation

◆ EOperationFlags

enum CSQLITE_Connection::EOperationFlags

Flags controlling specifics of database connection operation.

Only one flag can be used in each group of flags (separated by comments).

Enumerator
fInternalMT	Object and all statements and blobs created on top of it should support internal synchronization between different threads.
fExternalMT	Object and all statements and blobs created on top of it will not be used from different threads simultaneously, thus performance is optimized, object creates only one low-level SQLite connection.
fDefaultMT	Default value for multi-threading group of flags.
eAllMT
fVacuumOn	Vacuuming is on, database file has always the minimum size possible.
fVacuumOff	Vacuuming is off, database file can only grow.
fVacuumManual	Vacuuming is only by request.
fDefaultVacuum	Default value for vacuuming group of flags.
eAllVacuum
fJournalDelete	Journal on disk, journal file is deleted after each transaction.
fJournalTruncate	Journal on disk, size of journal file is nullified after each transaction.
fJournalPersist	Journal on disk, journal file can only grow, never shrinks.
fJournalMemory	Journaling is entirely in-memory.
fJournalOff	Journaling is completely off (not recommended - transactions cannot be rollbacked unless they consist of just one simple operation)
fDefaultJournal	Default value for journaling group of flags.
eAllJournal
fSyncFull	Full synchronization, database cannot be corrupted.
fSyncOn	Synchronization is on, there is a slight chance of database corruption when OS crashes.
fSyncOff	Synchronization is off, database can be corrupted on OS crash or power outage.
fDefaultSync	Default value for synchronization group of flags.
eAllSync
fTempToMemory	Mode of storing temporary data. Store all temporary tables in memory
fTempToFile	Use actual disk file for temporary storage.
fDefaultTemp	Default value for "temporary" group of flags.
eAllTemp
fWritesSync	Mode of doing all writes to the database. All writes are synchronous - when update has executed data is already in file (though See also fSyncOff)
fWritesAsync	All writes are asynchronous - updates return as quick as they can, actual writes to database happen in background thread (. See also CSQLITE_Global::RunAsyncWritesThread)
fDefaultWrites	Default value for writes mode group of flags.
eAllWrites
fReadOnly	The DB is read-only. Also forces fVacuumOff flag.
eDefaultFlags	Default value of all flags.

Definition at line 147 of file sqlitewrapp.hpp.

Constructor & Destructor Documentation

◆ CSQLITE_Connection() [1/2]

CSQLITE_Connection::CSQLITE_Connection	(	CTempString	file_name,
		TOperationFlags	flags = `eDefaultFlags`
	)

Connect to SQLite database.

NOTE: Vacuuming flags have any value here only when new database is created. When old database is opened with some data in it then vacuuming flags are no-op, flags used at creation are in effect. NOTE: Connection should be destroyed after all statements or blobs created on top of it. destroying statements after connection was destroyed will result in segmentation fault.

Parameters

file_name File name of SQLite database. If it doesn't exist it will be created. If directory for file doesn't exist exception will be thrown. If file name is empty connection to temporary file will be open. This file will be deleted after connection is closed. If file name is ":memory:" then connection to in-memory database will be open. In both cases (temporary file and in-memory database) flag fExternalMT should be set (it is not checked but you will get malfunctioning otherwise).

flags Flags for object operations

Definition at line 473 of file sqlitewrapp.cpp.

References eAllJournal, eAllMT, eAllSync, eAllTemp, eAllVacuum, eAllWrites, flags, and x_CheckFlagsValidity().

Referenced by CreateInMemoryDatabase().

◆ ~CSQLITE_Connection()

CSQLITE_Connection::~CSQLITE_Connection ( void )

Definition at line 491 of file sqlitewrapp.cpp.

References m_HandlePool, m_InMemory, and CObjPool< TObjType, TObjFactory >::Return().

◆ CSQLITE_Connection() [2/2]

CSQLITE_Connection::CSQLITE_Connection ( const CSQLITE_Connection & )

private

Member Function Documentation

◆ CreateInMemoryDatabase()

CSQLITE_Connection * CSQLITE_Connection::CreateInMemoryDatabase	(	CTempString	file_name,
		bool	shared = `false`
	)

static

Create a read-only copy of the database in memory.

The in-memory database is never synchronized with the original file. If 'shared' is true, a single copy of in-memory database is used. Otherwise each call to the function creates a new database and the returned connection is the only way to access it. On error return NULL.

Definition at line 617 of file sqlitewrapp.cpp.

References CSQLITE_Connection(), dbname(), fExternalMT, file_name, fJournalOff, fReadOnly, fSyncOff, fTempToMemory, fVacuumOff, LockHandle(), NULL, and UnlockHandle().

Referenced by CLDS2_Database::x_GetConn().

◆ CreateVacuumStmt()

CSQLITE_Statement * CSQLITE_Connection::CreateVacuumStmt ( size_t max_free_size )

Create statement for executing manual vacuuming.

Caller is responsible for deleting returned statement object.

See also: Vacuum

Definition at line 594 of file sqlitewrapp.cpp.

References kSQLITE_DefPageSize, sql, and NStr::UInt8ToString().

Referenced by Vacuum().

◆ DeleteDatabase()

void CSQLITE_Connection::DeleteDatabase ( void )

Delete database under this connection.

Method makes sure that journal file is deleted along with database file itself. All CSQLITE_Statement and CSQLITE_Blob objects on this connection should be deleted before call to this method. Any use of connection after call to this method will cause the database file to be created again.

Definition at line 605 of file sqlitewrapp.cpp.

References CObjPool< TObjType, TObjFactory >::Clear(), m_FileName, m_HandlePool, and CDirEntry::Remove().

◆ ExecuteSql()

void CSQLITE_Connection::ExecuteSql ( CTempString sql )

inline

Execute sql statement without returning any results.

Definition at line 874 of file sqlitewrapp.hpp.

References sql, and stmt.

Referenced by CLDS2_Database::BeginRead(), and CLDS2_Database::EndRead().

◆ GetCacheSize()

unsigned int CSQLITE_Connection::GetCacheSize ( void )

inline

Get recommended size of the database cache.

If cache size was not set by SetCacheSize() method then this method returns 0, though actually SQLite uses some default value.

Definition at line 837 of file sqlitewrapp.hpp.

References int, and m_CacheSize.

◆ GetFileName()

const string & CSQLITE_Connection::GetFileName ( void ) const

inline

Get database file name for the connection.

Definition at line 812 of file sqlitewrapp.hpp.

References m_FileName.

Referenced by CSQLITE_HandleFactory::CreateObject().

◆ GetFlags()

CSQLITE_Connection::TOperationFlags CSQLITE_Connection::GetFlags ( void ) const

inline

Get flags controlling database connection operation.

Definition at line 818 of file sqlitewrapp.hpp.

References m_Flags.

Referenced by CSQLITE_HandleFactory::CreateObject().

◆ GetPageSize()

unsigned int CSQLITE_Connection::GetPageSize ( void )

inline

Get page size used in the database (in bytes)

Definition at line 824 of file sqlitewrapp.hpp.

References m_PageSize.

◆ LockHandle()

sqlite3 * CSQLITE_Connection::LockHandle ( void )

inline

Lock and return low-level connection handle.

Definition at line 850 of file sqlitewrapp.hpp.

References eAllMT, fExternalMT, CObjPool< TObjType, TObjFactory >::Get(), m_Flags, m_HandlePool, m_InMemory, result, and CObjPool< TObjType, TObjFactory >::Return().

Referenced by CreateInMemoryDatabase(), CSQLITE_Blob::x_OpenBlob(), and CSQLITE_Statement::x_Prepare().

◆ operator=()

CSQLITE_Connection& CSQLITE_Connection::operator= ( const CSQLITE_Connection & )

private

◆ SetCacheSize()

void CSQLITE_Connection::SetCacheSize ( unsigned int size )

inline

Set recommended size of the database cache (number of pages).

If value is not set or set to 0 then default SQLite value is used.

Definition at line 843 of file sqlitewrapp.hpp.

References CObjPool< TObjType, TObjFactory >::Clear(), m_CacheSize, m_HandlePool, and ncbi::grid::netcache::search::fields::size.

◆ SetFlags()

void CSQLITE_Connection::SetFlags ( TOperationFlags flags )

Change flags controlling database connection operation.

NOTE: Vacuuming flags cannot be changed here. New flags will be applied only to newly created low-level SQLite connections. Thus in fInternalMT mode it is recommended to destroy all CSQLITE_Statement and CSQLITE_Blob objects before changing flags. In fExternalMT mode this cleaning of statements is mandatory - you will get memory and other resources leak otherwise.

Definition at line 582 of file sqlitewrapp.cpp.

References CObjPool< TObjType, TObjFactory >::Clear(), eAllVacuum, flags, m_Flags, m_HandlePool, and NCBI_THROW.

◆ SetPageSize()

void CSQLITE_Connection::SetPageSize ( unsigned int size )

inline

Set page size for the database (in bytes).

Setting has any value only if database is empty (has no tables) and no statements are created yet. Page size should be power of 2 and be less than or equal to 32768. If page size is not set default value is used.

Definition at line 830 of file sqlitewrapp.hpp.

References CObjPool< TObjType, TObjFactory >::Clear(), m_HandlePool, m_PageSize, and ncbi::grid::netcache::search::fields::size.

Referenced by CNCDBIndexFile::CNCDBIndexFile().

◆ SetupNewConnection()

void CSQLITE_Connection::SetupNewConnection ( sqlite3 * handle )

Setup newly created low-level connection handle.

Executes all necessary pragmas according to operation flags set.

Definition at line 500 of file sqlitewrapp.cpp.

References eAllJournal, eAllSync, eAllTemp, eAllVacuum, fJournalDelete, fJournalMemory, fJournalOff, fJournalPersist, fJournalTruncate, fReadOnly, fSyncFull, fSyncOff, fSyncOn, fTempToFile, fTempToMemory, fVacuumManual, fVacuumOff, fVacuumOn, NStr::IntToString(), m_CacheSize, m_Flags, m_PageSize, x_CheckFlagsValidity(), and x_ExecuteSql().

Referenced by CSQLITE_HandleFactory::CreateObject().

◆ UnlockHandle()

void CSQLITE_Connection::UnlockHandle ( sqlite3 * handle )

inline

Unlock unused low-level connection handle.

This handle will be used later by some other statement. Essentially no-op in eExternalMT mode.

See also: EMultiThreadMode

Definition at line 863 of file sqlitewrapp.hpp.

References eAllMT, fInternalMT, m_Flags, m_HandlePool, m_InMemory, and CObjPool< TObjType, TObjFactory >::Return().

Referenced by CreateInMemoryDatabase(), CSQLITE_Blob::~CSQLITE_Blob(), and CSQLITE_Statement::~CSQLITE_Statement().

◆ Vacuum()

void CSQLITE_Connection::Vacuum ( size_t max_free_size )

inline

Try to shrink database and free up to max_free_size bytes of disk space.

Method is no-op when vacuum mode is other than fVacuumManual.

See also: EOperationFlags

Definition at line 881 of file sqlitewrapp.hpp.

References CreateVacuumStmt(), and stmt.

◆ x_CheckFlagsValidity()

void CSQLITE_Connection::x_CheckFlagsValidity	(	TOperationFlags	flags,
		EOperationFlags	mask
	)

private

Check that only one flag in specific group of flags is given.

Definition at line 455 of file sqlitewrapp.cpp.

References flags, NStr::IntToString(), mask, and NCBI_THROW.

Referenced by CSQLITE_Connection(), and SetupNewConnection().

◆ x_ExecuteSql()

void CSQLITE_Connection::x_ExecuteSql	(	sqlite3 *	handle,
		CTempString	sql
	)

inlineprivate

Execute sql statement on given low-level connection handle.

Definition at line 467 of file sqlitewrapp.cpp.

References sql, and stmt.

Referenced by SetupNewConnection().

Member Data Documentation

◆ m_CacheSize

unsigned int CSQLITE_Connection::m_CacheSize

private

Recommended size of cache for the database.

Definition at line 350 of file sqlitewrapp.hpp.

Referenced by GetCacheSize(), SetCacheSize(), and SetupNewConnection().

◆ m_FileName

string CSQLITE_Connection::m_FileName

private

File name of SQLite database.

Definition at line 344 of file sqlitewrapp.hpp.

Referenced by DeleteDatabase(), and GetFileName().

◆ m_Flags

TOperationFlags CSQLITE_Connection::m_Flags

private

Flags for object operation.

Definition at line 346 of file sqlitewrapp.hpp.

Referenced by GetFlags(), LockHandle(), SetFlags(), SetupNewConnection(), and UnlockHandle().

◆ m_HandlePool

THandlePool CSQLITE_Connection::m_HandlePool

private

Pool of low-level database connections.

Definition at line 352 of file sqlitewrapp.hpp.

Referenced by DeleteDatabase(), LockHandle(), SetCacheSize(), SetFlags(), SetPageSize(), UnlockHandle(), and ~CSQLITE_Connection().

◆ m_InMemory

sqlite3* CSQLITE_Connection::m_InMemory

private

Definition at line 355 of file sqlitewrapp.hpp.

Referenced by LockHandle(), UnlockHandle(), and ~CSQLITE_Connection().

◆ m_PageSize

unsigned int CSQLITE_Connection::m_PageSize

private

Page size inside the database.

Definition at line 348 of file sqlitewrapp.hpp.

Referenced by GetPageSize(), SetPageSize(), and SetupNewConnection().

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

include/db/sqlite/sqlitewrapp.hpp
src/db/sqlite/sqlitewrapp.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ THandlePool

◆ TOperationFlags

Member Enumeration Documentation

◆ EOperationFlags

Constructor & Destructor Documentation

◆ CSQLITE_Connection() [1/2]

◆ ~CSQLITE_Connection()

◆ CSQLITE_Connection() [2/2]

Member Function Documentation

◆ CreateInMemoryDatabase()

◆ CreateVacuumStmt()

◆ DeleteDatabase()

◆ ExecuteSql()

◆ GetCacheSize()

◆ GetFileName()

◆ GetFlags()

◆ GetPageSize()

◆ LockHandle()

◆ operator=()

◆ SetCacheSize()

◆ SetFlags()

◆ SetPageSize()

◆ SetupNewConnection()

◆ UnlockHandle()

◆ Vacuum()

◆ x_CheckFlagsValidity()

◆ x_ExecuteSql()

Member Data Documentation

◆ m_CacheSize

◆ m_FileName

◆ m_Flags

◆ m_HandlePool

◆ m_InMemory

◆ m_PageSize