NCBI C++ ToolKit
Public Types | Public Member Functions | Static Public Member Functions | Private Types | Private Member Functions | Private Attributes | List of all members
CSQLITE_Connection Class Reference

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 stringGetFileName (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_StatementCreateVacuumStmt (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_ConnectionCreateInMemoryDatabase (CTempString file_name, bool shared=false)
 Create a read-only copy of the database in memory. More...
 

Private Types

typedef CObjPool< sqlite3, CSQLITE_HandleFactoryTHandlePool
 

Private Member Functions

 CSQLITE_Connection (const CSQLITE_Connection &)
 
CSQLITE_Connectionoperator= (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

Definition at line 341 of file sqlitewrapp.hpp.

◆ TOperationFlags

Bit mask of EOperationFlags.

Definition at line 234 of file sqlitewrapp.hpp.

Member Enumeration Documentation

◆ 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_nameFile 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).
flagsFlags 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  )

◆ 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

◆ 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:
Modified on Fri Apr 12 17:19:38 2024 by modify_doxy.py rev. 669887