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

Search Toolkit Book for CDatabase

Database connection object. More...

#include <dbapi/simple/sdbapi.hpp>

+ Collaboration diagram for CDatabase:

Public Types

enum  EConnectionCheckMethod { eNoCheck , eFastCheck , eFullCheck }
 How thoroughly IsConnected should actually check the connection. More...
 

Public Member Functions

 CDatabase (void)
 Empty constructor of database object. More...
 
 CDatabase (const CSDB_ConnectionParam &param)
 Create database object for particular database parameters. More...
 
 CDatabase (const string &url_string)
 Create database object and take database parameters from given URL and application configuration. More...
 
 ~CDatabase (void)
 
 CDatabase (const CDatabase &db)
 Copying of database object. More...
 
CDatabaseoperator= (const CDatabase &db)
 
CSDB_ConnectionParamGetConnectionParam (void)
 Get connection parameters. More...
 
const CSDB_ConnectionParamGetConnectionParam (void) const
 
void Connect (void)
 Explicitly (re)connect to the database server. More...
 
void Close (void)
 Close database object. More...
 
CDatabase Clone (void)
 Clone database object. More...
 
bool IsConnected (EConnectionCheckMethod check_method=eNoCheck)
 Check if database object was already connected to database server. More...
 
CQuery NewQuery (void)
 Get new CQuery object for this database. More...
 
CQuery NewQuery (const string &sql)
 Get new CQuery object with particular sql statement for this database. More...
 
CBulkInsert NewBulkInsert (const string &table_name, int autoflush)
 Get new CBulkInsert object. More...
 
CBlobBookmark NewBookmark (const string &table_name, const string &column_name, const string &search_conditions, CBlobBookmark::EBlobType column_type=CBlobBookmark::eUnknown, ETriState has_legacy_type=eTriState_Unknown)
 Get new CBlobBookmark object. More...
 
CBlobStoreStaticNewBlobStore (const string &table_name, TNewBlobStoreFlags flags=TNewBlobStoreFlags(0), size_t image_limit=1<< 24)
 Get new CBlobStoreStatic object (to be owned by caller). More...
 
CBlobStoreStaticNewBlobStore (const string &table_name, const string &key_col_name, const string &num_col_name, const vector< string > blob_col_names, TNewBlobStoreFlags flags=TNewBlobStoreFlags(0), size_t image_limit=1<< 24)
 Get new CBlobStoreStatic object (to be owned by caller). More...
 
CSDBAPI::EDriver GetDriverVersion (void) const
 Get the driver version. More...
 

Private Member Functions

void x_ConnectAsNeeded (const char *operation)
 

Private Attributes

CSDB_ConnectionParam m_Params
 Database parameters. More...
 
CRef< CDatabaseImplm_Impl
 Database implementation object. More...
 

Friends

CAutoTrans::CSubject DBAPI_MakeTrans (CDatabase &db)
 (S)DBAPI_TRANSACTION glue for CDatabase. More...
 

Detailed Description

Database connection object.

Definition at line 1223 of file sdbapi.hpp.

Member Enumeration Documentation

◆ EConnectionCheckMethod

How thoroughly IsConnected should actually check the connection.

Enumerator
eNoCheck 
eFastCheck 
eFullCheck 

Definition at line 1227 of file sdbapi.hpp.

Constructor & Destructor Documentation

◆ CDatabase() [1/4]

CDatabase::CDatabase ( void  )

Empty constructor of database object.

Object created this way cannot be used for anything except assigning from another database object.

Definition at line 1987 of file sdbapi.cpp.

◆ CDatabase() [2/4]

CDatabase::CDatabase ( const CSDB_ConnectionParam param)

Create database object for particular database parameters.

Definition at line 1991 of file sdbapi.cpp.

◆ CDatabase() [3/4]

CDatabase::CDatabase ( const string url_string)

Create database object and take database parameters from given URL and application configuration.

See CSDB_ConnectionParam ctor for URL format and rules of overriding.

Definition at line 1995 of file sdbapi.cpp.

◆ ~CDatabase()

CDatabase::~CDatabase ( void  )

◆ CDatabase() [4/4]

CDatabase::CDatabase ( const CDatabase db)

Copying of database object.

Objects copied this way will work over the same physical connection to the server unless they're reconnected again.

Definition at line 1999 of file sdbapi.cpp.

References operator=().

Member Function Documentation

◆ Clone()

CDatabase CDatabase::Clone ( void  )

◆ Close()

void CDatabase::Close ( void  )

Close database object.

You cannot do anything with CQuery and CBulkInsert objects created from this database object after call to this method. Although you can reconnect to the database server CQuery and CBulkInsert objects will not work anyway.

Definition at line 2035 of file sdbapi.cpp.

References CDatabaseImpl::Close(), CDatabaseImpl::IsOpen(), m_Impl, and SDBAPI_CATCH_LOWLEVEL.

Referenced by IsConnected(), CSdbapiTest::Run(), CNSTDatabase::x_PreCheckConnection(), CNSTDBConnectionThread::x_RestoreConnection(), CNetStorageGCDatabase::~CNetStorageGCDatabase(), and CNSTDatabase::~CNSTDatabase().

◆ Connect()

void CDatabase::Connect ( void  )

Explicitly (re)connect to the database server.

NB: NewQuery et al. automatically establish initial connections, but do not automatically reconnect, because the original connection may have had important state.

Definition at line 2023 of file sdbapi.cpp.

References CDatabaseImpl::Connect(), CDatabaseImpl::EverConnected(), m_Impl, m_Params, CRef< C, Locker >::Reset(), and SDBAPI_CATCH_LOWLEVEL.

Referenced by CNSTDatabase::InitialConnect(), CSdbapiTest::Run(), CAsnSubCacheCreateApplication::SBlobVersion::s_PopulateSatelliteMap(), CSdbapiSimpleApp::SetupDb(), CNetStorageGCDatabase::x_Connect(), x_ConnectAsNeeded(), CNSTDatabase::x_PreCheckConnection(), CNSTDBConnectionThread::x_RestoreConnection(), and CDBLBClientApp::x_RunLookup().

◆ GetConnectionParam() [1/2]

CSDB_ConnectionParam & CDatabase::GetConnectionParam ( void  )
inline

Get connection parameters.

Definition at line 1689 of file sdbapi.hpp.

References m_Params.

◆ GetConnectionParam() [2/2]

const CSDB_ConnectionParam & CDatabase::GetConnectionParam ( void  ) const
inline

Definition at line 1695 of file sdbapi.hpp.

References m_Params.

◆ GetDriverVersion()

CSDBAPI::EDriver CDatabase::GetDriverVersion ( void  ) const

◆ IsConnected()

bool CDatabase::IsConnected ( EConnectionCheckMethod  check_method = eNoCheck)

Check if database object was already connected to database server.

By default, this checks only that Connect() method was called and Close() wasn't called, but more thorough checks are possible. NB: eFullCheck mode cannot coexist with active queries.

Definition at line 2046 of file sdbapi.cpp.

References _ASSERT, Close(), conn, eFastCheck, eFullCheck, eNoCheck, CDatabaseImpl::GetConnection(), CDatabaseImpl::IsOpen(), m_Impl, NewQuery(), NULL, ok, query, and row.

Referenced by Clone(), x_ConnectAsNeeded(), CNSTDatabase::x_PostCheckConnection(), and CNSTDatabase::x_PreCheckConnection().

◆ NewBlobStore() [1/2]

CBlobStoreStatic * CDatabase::NewBlobStore ( const string table_name,
const string key_col_name,
const string num_col_name,
const vector< string blob_col_names,
TNewBlobStoreFlags  flags = TNewBlobStoreFlags(0),
size_t  image_limit = 1 << 24 
)

Get new CBlobStoreStatic object (to be owned by caller).

Automatically establish an initial connection if necessary, but do not automatically reconnect.

Parameters
table_nameName of the table holding the blobs (structure given explicitly via key_col_name, num_col_name, and blob_col_names).
key_col_nameName of the column holding keys with which blobs are associated.
num_col_nameName of the column holding the number of blob columns used.
blob_col_namesNames of the actual blob columns.
flagsFlags governing compression, transaction logging, and blob column textuality.
image_limitMaximum size of a single blob (to be split across columns as needed).

Definition at line 2152 of file sdbapi.cpp.

References CONNECT_AS_NEEDED, flags, IConnection::GetCDB_Connection(), CDatabaseImpl::GetConnection(), m_Impl, s_CheckCompressionFlags(), s_TranslateBlobStoreFlags(), and table_name.

◆ NewBlobStore() [2/2]

CBlobStoreStatic * CDatabase::NewBlobStore ( const string table_name,
TNewBlobStoreFlags  flags = TNewBlobStoreFlags(0),
size_t  image_limit = 1 << 24 
)

Get new CBlobStoreStatic object (to be owned by caller).

Automatically establish an initial connection if necessary, but do not automatically reconnect.

Parameters
table_nameName of the table holding the blobs (structure to be deduced by inspection).
flagsFlags governing compression and transaction logging.
image_limitMaximum size of a single blob (to be split across columns as needed).

Definition at line 2135 of file sdbapi.cpp.

References CONNECT_AS_NEEDED, ERR_POST_X_ONCE, flags, fNBS_IsText, IConnection::GetCDB_Connection(), CDatabaseImpl::GetConnection(), m_Impl, s_CheckCompressionFlags(), s_TranslateBlobStoreFlags(), table_name, and Warning().

◆ NewBookmark()

CBlobBookmark CDatabase::NewBookmark ( const string table_name,
const string column_name,
const string search_conditions,
CBlobBookmark::EBlobType  column_type = CBlobBookmark::eUnknown,
ETriState  has_legacy_type = eTriState_Unknown 
)

Get new CBlobBookmark object.

Automatically establish an initial connection if necessary, but do not automatically reconnect.

Parameters
table_nameName of the table to update.
column_nameName of the column to update.
search_conditionsSQL expression identifying the relevant row. (Failure to match exactly one row yields undefined behavior, and may result in updating multiple rows in some cases.)
column_typeGeneral column type (text or binary), if known. (Optional.)
has_legacy_typeWhether the column has a legacy type (IMAGE or [N]TEXT) or a modern type like [N]VARCHAR(MAX). (Optional.)
See also
CQuery::CField::GetBookmark

Definition at line 2106 of file sdbapi.cpp.

References CONNECT_AS_NEEDED, CDB_BlobDescriptor::eBinary, CBlobBookmark::eBinary, CDB_BlobDescriptor::eText, CBlobBookmark::eText, CDB_BlobDescriptor::eUnknown, m_Impl, and table_name.

◆ NewBulkInsert()

CBulkInsert CDatabase::NewBulkInsert ( const string table_name,
int  autoflush 
)

Get new CBulkInsert object.

Automatically establish an initial connection if necessary, but do not automatically reconnect.

Parameters
table_nameName of the table to insert to
autoflushNumber of rows to insert before the batch is committed to database

Definition at line 2099 of file sdbapi.cpp.

References CONNECT_AS_NEEDED, m_Impl, and table_name.

Referenced by CSdbapiTest::Run().

◆ NewQuery() [1/2]

CQuery CDatabase::NewQuery ( const string sql)
inline

Get new CQuery object with particular sql statement for this database.

Automatically establish an initial connection if necessary, but do not automatically reconnect.

Definition at line 1701 of file sdbapi.hpp.

References NewQuery(), CQuery::SetSql(), and sql.

◆ NewQuery() [2/2]

CQuery CDatabase::NewQuery ( void  )

Get new CQuery object for this database.

Automatically establish an initial connection if necessary, but do not automatically reconnect.

Definition at line 2092 of file sdbapi.cpp.

References CONNECT_AS_NEEDED, and m_Impl.

Referenced by CSdbapiSimpleApp::DemoDynamicSql(), CSdbapiSimpleApp::DemoParamerizedSql(), CSdbapiSimpleApp::DemoStaticSql(), CSdbapiSimpleApp::DemoStoredProc(), CNSTDatabase::ExecSP_AddAttribute(), CNSTDatabase::ExecSP_CreateClient(), CNSTDatabase::ExecSP_CreateObjectWithClientID(), CNSTDatabase::ExecSP_CreateUser(), CNSTDatabase::ExecSP_DelAttribute(), CNSTDatabase::ExecSP_DoesObjectExist(), CNSTDatabase::ExecSP_GetAttribute(), CNSTDatabase::ExecSP_GetAttributeNames(), CNSTDatabase::ExecSP_GetClientObjects(), CNSTDatabase::ExecSP_GetClients(), CNSTDatabase::ExecSP_GetGeneralDBInfo(), CNSTDatabase::ExecSP_GetObjectExpiration(), CNSTDatabase::ExecSP_GetObjectFixedAttributes(), CNSTDatabase::ExecSP_GetObjectSize(), CNSTDatabase::ExecSP_GetObjectSizeAndLocator(), CNSTDatabase::ExecSP_GetStatDBInfo(), CNSTDatabase::ExecSP_GetUserObjects(), CNSTDatabase::ExecSP_GetUsers(), CNSTDatabase::ExecSP_RemoveObject(), CNSTDatabase::ExecSP_SetExpiration(), CNSTDatabase::ExecSP_UpdateObjectOnRead(), CNSTDatabase::ExecSP_UpdateObjectOnRelocate(), CNSTDatabase::ExecSP_UpdateObjectOnWrite(), CNSTDatabase::ExecSP_UpdateObjectSizeIfNULL(), CNSTDatabase::ExecSP_UpdateUserIDForObject(), CNSTDatabase::ExecSP_UpdateUserKeyObjectOnWrite(), CNetStorageGCDatabase::GetAppLock(), CNetStorageGCDatabase::GetDBStructureVersion(), CNetStorageGCDatabase::GetGCCandidates(), IsConnected(), NewQuery(), CNetStorageGCDatabase::ReleaseAppLock(), CNetStorageGCDatabase::RemoveObject(), CSdbapiTest::Run(), CAsnSubCacheCreateApplication::SBlobVersion::s_PopulateSatelliteMap(), CNSTDatabase::UpdateExpirationIfExists(), and CDBLBClientApp::x_RunLookup().

◆ operator=()

CDatabase & CDatabase::operator= ( const CDatabase db)

Definition at line 2005 of file sdbapi.cpp.

References m_Impl, and m_Params.

Referenced by CDatabase().

◆ x_ConnectAsNeeded()

void CDatabase::x_ConnectAsNeeded ( const char *  operation)
private

Friends And Related Function Documentation

◆ DBAPI_MakeTrans

CAutoTrans::CSubject DBAPI_MakeTrans ( CDatabase db)
friend

(S)DBAPI_TRANSACTION glue for CDatabase.

Definition at line 3537 of file sdbapi.cpp.

Member Data Documentation

◆ m_Impl

CRef<CDatabaseImpl> CDatabase::m_Impl
private

◆ m_Params

CSDB_ConnectionParam CDatabase::m_Params
private

Database parameters.

Definition at line 1373 of file sdbapi.hpp.

Referenced by Clone(), Connect(), GetConnectionParam(), and operator=().


The documentation for this class was generated from the following files:
Modified on Thu Jul 18 16:07:59 2024 by modify_doxy.py rev. 669887