CernVM-FS  2.12.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
sqlite::Database< DerivedT > Class Template Reference

#include <sql.h>

Inheritance diagram for sqlite::Database< DerivedT >:
Collaboration diagram for sqlite::Database< DerivedT >:

Classes

struct  DatabaseRaiiWrapper
 

Public Types

enum  OpenMode { kOpenReadOnly, kOpenReadWrite }
 

Public Member Functions

bool IsEqualSchema (const float value, const float compare) const
 
bool BeginTransaction () const
 
bool CommitTransaction () const
 
template<typename T >
GetProperty (const std::string &key) const
 
template<typename T >
GetPropertyDefault (const std::string &key, const T default_value) const
 
template<typename T >
bool SetProperty (const std::string &key, const T value)
 
bool HasProperty (const std::string &key) const
 
sqlite3 * sqlite_db () const
 
const std::string & filename () const
 
float schema_version () const
 
unsigned schema_revision () const
 
bool read_write () const
 
unsigned GetModifiedRowCount () const
 
double GetFreePageRatio () const
 
void GetMemStatistics (MemStatistics *stats) const
 
bool Vacuum () const
 
void PrintSqlError (const std::string &error_msg)
 
std::string GetLastErrorMsg () const
 
void TakeFileOwnership ()
 
void DropFileOwnership ()
 
bool OwnsFile () const
 
void EnforceSchema (float version, unsigned revision)
 

Static Public Member Functions

static DerivedT * Create (const std::string &filename)
 
static DerivedT * Open (const std::string &filename, const OpenMode open_mode)
 

Static Public Attributes

static const float kSchemaEpsilon = 0.0005
 

Protected Member Functions

 Database (const std::string &filename, const OpenMode open_mode)
 
bool Initialize ()
 
bool CreatePropertiesTable ()
 
bool PrepareCommonQueries ()
 
bool OpenDatabase (const int sqlite_open_flags)
 
bool Configure ()
 
bool FileReadAhead ()
 
void ReadSchemaRevision ()
 
bool StoreSchemaRevision ()
 
void set_schema_version (const float ver)
 
void set_schema_revision (const unsigned rev)
 

Private Attributes

DatabaseRaiiWrapper database_
 
const bool read_write_
 
float schema_version_
 
unsigned schema_revision_
 
UniquePtr< Sqlbegin_transaction_
 
UniquePtr< Sqlcommit_transaction_
 
UniquePtr< Sqlhas_property_
 
UniquePtr< Sqlset_property_
 
UniquePtr< Sqlget_property_
 

Static Private Attributes

static const char * kSchemaVersionKey = "schema"
 
static const char * kSchemaRevisionKey = "schema_revision"
 

Additional Inherited Members

- Private Member Functions inherited from SingleCopy
 SingleCopy ()
 

Detailed Description

template<class DerivedT>
class sqlite::Database< DerivedT >

Encapsulates an SQlite connection.

This is an abstract base class for different SQLite database flavours used throughout CernVM-FS. It provides a general interface for creating, opening, compacting and migrating an SQLite database. Furthermore it manages a properties table in each database, to store simple key-value style information in a common fashion. For that, it offers the templated methods SetProperty(), GetProperty<>() and HasProperty() that take all common data types and persist it in the database.

By default Database<> objects do not take ownership of the underlying SQLite database file and hence do not unlink it on database closure. If the using code calls Database<>::TakeFileOwnership() the SQLite file will be unlinked in the destructor of the Database<> object.

Note: This implements a Curiously Recurring Template Pattern in order to implement Database::Create and Database::Open as a static polymorphism

The following methods need to be implemented by each subclass: (Database<> assumes 'true' as a return value on success)

-> bool CreateEmptyDatabase() creates all necessary SQLite tables for the concrete Database implementation. Furthermore it can insert default data into the newly created database tables. -> bool CheckSchemaCompatibility() checks a database for compatibility directly after opening it. Database<> provides schema_version() and schema_revision() to access the compatibility stored in the properties table -> bool LiveSchemaUpgradeIfNecessary() this allows for on-the-fly schema updates and is always called when a database is opened read/write. It assumes 'true' both on successful migration and if no migration was necessary -> bool CompactDatabase() here implementation specific cleanup actions can take place on databases opened as read/write. It is invoked by the Vacuum() method, that can be used by higher level user code

Furthermore Database<> expects two static constants to be defined:

-> kLatestSchema - the newest schema version generated by invoking DerivedT::CreateEmptyDatabase() -> kLatestSchemaRevision - same as kLatestSchema, however different schema revisions are supposed to be backward compatible or on-the-fly updateable by DerivedT::LiveSchemaUpgradeIfNecessary()

Parameters
DerivedTthe name of the inheriting Database implementation class (Curiously Recurring Template Pattern)

TODO(rmeusel): C++11 Move Constructors to allow for stack allocated databases

Definition at line 98 of file sql.h.

Member Enumeration Documentation

template<class DerivedT>
enum sqlite::Database::OpenMode
Enumerator
kOpenReadOnly 
kOpenReadWrite 

Definition at line 100 of file sql.h.

Constructor & Destructor Documentation

template<class DerivedT >
sqlite::Database< DerivedT >::Database ( const std::string &  filename,
const OpenMode  open_mode 
)
protected

Private constructor! Use the factory methods DerivedT::Create() or DerivedT::Open() to instantiate a database object of type DerivedT.

Definition at line 21 of file sql_impl.h.

Member Function Documentation

template<class DerivedT >
bool sqlite::Database< DerivedT >::Configure ( )
protected

Definition at line 184 of file sql_impl.h.

Here is the call graph for this function:

template<class DerivedT >
DerivedT * sqlite::Database< DerivedT >::Create ( const std::string &  filename)
static

Creates a new database file of the type implemented by DerivedT. During the invocation of this static method DerivedT::CreateEmptyDatabase() is called.

Parameters
filenamethe file location of the newly created database (file does not need to exist)
Returns
an empty database of type DerivedT (or NULL on failure)

Definition at line 30 of file sql_impl.h.

Referenced by catalog::WritableCatalogManager::CreateNestedCatalog(), swissknife::CommandMigrate::MigrationWorker_20x::CreateNewEmptyCatalog(), and catalog::WritableCatalogManager::CreateRepository().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
bool sqlite::Database< DerivedT >::CreatePropertiesTable ( )
protected

Definition at line 285 of file sql_impl.h.

Here is the call graph for this function:

template<class DerivedT >
void sqlite::Database< DerivedT >::DropFileOwnership ( )

Resigns from the ownership of the SQLite database file underlying this Database<> object. After calling this the using code is responsible of managing the database file.

Definition at line 350 of file sql_impl.h.

Referenced by catalog::Catalog::DropDatabaseFileOwnership().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT>
void sqlite::Database< DerivedT >::EnforceSchema ( float  version,
unsigned  revision 
)
inline

Used when attaching legacy catalogs to set 0.9 schema where mistakenly 1.0 was used.

Definition at line 227 of file sql.h.

Referenced by catalog::Catalog::OpenDatabase().

Here is the caller graph for this function:

template<class DerivedT>
const std::string& sqlite::Database< DerivedT >::filename ( ) const
inline
template<class DerivedT >
bool sqlite::Database< DerivedT >::FileReadAhead ( )
protected

Definition at line 203 of file sql_impl.h.

Here is the call graph for this function:

template<class DerivedT >
double sqlite::Database< DerivedT >::GetFreePageRatio ( ) const

Figures out the ratio of free SQLite memory pages in the SQLite database file. A high ratio can be an indication of a necessary call to Vacuum(). Note: This is not done automatically and the decision is left to the using code!

Returns
the free-page ratio in the opened database file (free pages/pages)

Definition at line 406 of file sql_impl.h.

Referenced by catalog::WritableCatalog::VacuumDatabaseIfNecessary().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
std::string sqlite::Database< DerivedT >::GetLastErrorMsg ( ) const

Returns the english language error description of the last error happened in the context of the encapsulated sqlite3 database object. Note: In a multithreaded context it might be unpredictable which the actual last error is.

Returns
english language error description of last error

Definition at line 335 of file sql_impl.h.

Referenced by sqlite::Database< DerivedT >::PrintSqlError(), and catalog::WritableCatalog::VacuumDatabaseIfNecessary().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
void sqlite::Database< DerivedT >::GetMemStatistics ( MemStatistics stats) const

Retrieves the per-connection memory statistics from SQlite

Ask SQlite for per-connection memory statistics

Definition at line 368 of file sql_impl.h.

Referenced by catalog::Catalog::PrintMemStatistics().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
unsigned sqlite::Database< DerivedT >::GetModifiedRowCount ( ) const

Provides the number of rows modified by INSERT, UPDATE or DELETE statements that have been run against this database since it was opened.

Returns
number of rows modified by all executed manipulating statements

Definition at line 358 of file sql_impl.h.

Referenced by swissknife::CommandMigrate::PendingCatalog::HasChanges().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
template<typename T >
T sqlite::Database< DerivedT >::GetProperty ( const std::string &  key) const

Definition at line 305 of file sql_impl.h.

Referenced by catalog::Catalog::GetLastModified(), catalog::Catalog::GetVOMSAuthz(), catalog::Catalog::OpenDatabase(), and StatisticsDatabase::OpenStandardDB().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
template<typename T >
T sqlite::Database< DerivedT >::GetPropertyDefault ( const std::string &  key,
const T  default_value 
) const

Definition at line 317 of file sql_impl.h.

Referenced by catalog::Catalog::GetPreviousRevision(), catalog::Catalog::GetRevision(), catalog::Catalog::GetTTL(), and catalog::Catalog::OpenDatabase().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
bool sqlite::Database< DerivedT >::HasProperty ( const std::string &  key) const

Definition at line 293 of file sql_impl.h.

Referenced by sqlite::Database< DerivedT >::GetPropertyDefault(), catalog::Catalog::HasExplicitTTL(), catalog::Catalog::OpenDatabase(), and sqlite::Database< DerivedT >::ReadSchemaRevision().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
bool sqlite::Database< DerivedT >::Initialize ( )
protected

Definition at line 93 of file sql_impl.h.

Here is the call graph for this function:

template<class DerivedT>
bool sqlite::Database< DerivedT >::IsEqualSchema ( const float  value,
const float  compare 
) const
inline
template<class DerivedT >
DerivedT * sqlite::Database< DerivedT >::Open ( const std::string &  filename,
const OpenMode  open_mode 
)
static

Opens a database file and assumes it to be of type DerivedT. This method will call DerivedT::CheckSchemaCompatibility() to figure out readability of the contained schema revision. Furthermore, if the database was opened in read/write mode, it calls DerivedT::LiveSchemaUpgradeIfNecessary() to allow for on-the-fly schema upgrades of the underlying database file.

Parameters
filenamepath to the SQLite file to be opened as DerivedT
open_modekOpenReadOnly or kOpenReadWrite open modes
Returns
a database of type DerivedT (or NULL on failure)

Definition at line 73 of file sql_impl.h.

Referenced by catalog::Catalog::OpenDatabase(), and swissknife::CommandFileStats::ProcessCatalog().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
bool sqlite::Database< DerivedT >::OpenDatabase ( const int  sqlite_open_flags)
protected

Definition at line 129 of file sql_impl.h.

Here is the call graph for this function:

template<class DerivedT>
bool sqlite::Database< DerivedT >::OwnsFile ( ) const
inline

Check if the SQLite database file is managed by the Database<> object Note: unmanaged means, that the using code needs to take care of the file management (i.e. delete the file after usage)

Returns
false if file is unmanaged

Definition at line 221 of file sql.h.

Referenced by catalog::Catalog::OwnsDatabaseFile().

Here is the caller graph for this function:

template<class DerivedT >
bool sqlite::Database< DerivedT >::PrepareCommonQueries ( )
protected

Definition at line 234 of file sql_impl.h.

Here is the call graph for this function:

template<class DerivedT >
void sqlite::Database< DerivedT >::PrintSqlError ( const std::string &  error_msg)

Prints the given error message, together with the last encountered SQLite error of this database.

Parameters
error_msgan error message to be printed along with the SQL error

Definition at line 431 of file sql_impl.h.

Here is the call graph for this function:

template<class DerivedT>
bool sqlite::Database< DerivedT >::read_write ( ) const
inline

Definition at line 151 of file sql.h.

template<class DerivedT >
void sqlite::Database< DerivedT >::ReadSchemaRevision ( )
protected

Definition at line 253 of file sql_impl.h.

Here is the call graph for this function:

template<class DerivedT>
void sqlite::Database< DerivedT >::set_schema_revision ( const unsigned  rev)
inlineprotected

Definition at line 253 of file sql.h.

template<class DerivedT>
void sqlite::Database< DerivedT >::set_schema_version ( const float  ver)
inlineprotected

Definition at line 252 of file sql.h.

template<class DerivedT >
template<typename T >
bool sqlite::Database< DerivedT >::SetProperty ( const std::string &  key,
const T  value 
)
template<class DerivedT>
sqlite3* sqlite::Database< DerivedT >::sqlite_db ( ) const
inline

Definition at line 147 of file sql.h.

Referenced by sqlite::Database< DerivedT >::DatabaseRaiiWrapper::Close(), sqlite::Database< DerivedT >::Configure(), sqlite::Database< DerivedT >::CreatePropertiesTable(), sqlite::Database< DerivedT >::GetFreePageRatio(), sqlite::Database< DerivedT >::GetLastErrorMsg(), sqlite::Database< DerivedT >::GetMemStatistics(), sqlite::Database< DerivedT >::GetModifiedRowCount(), sqlite::Database< DerivedT >::PrepareCommonQueries(), swissknife::CommandFileStats::ProcessCatalog(), catalog::SqlAllChunks::SqlAllChunks(), catalog::SqlCatalog::SqlCatalog(), catalog::SqlChunkInsert::SqlChunkInsert(), catalog::SqlChunksCount::SqlChunksCount(), catalog::SqlChunksListing::SqlChunksListing(), catalog::SqlChunksRemove::SqlChunksRemove(), SqlContainsReference::SqlContainsReference(), SqlCountReferences::SqlCountReferences(), history::SqlCountTags::SqlCountTags(), catalog::SqlCreateCounter::SqlCreateCounter(), catalog::SqlDirentInsert::SqlDirentInsert(), catalog::SqlDirentTouch::SqlDirentTouch(), catalog::SqlDirentUnlink::SqlDirentUnlink(), catalog::SqlDirentUpdate::SqlDirentUpdate(), catalog::SqlGetCounter::SqlGetCounter(), history::SqlGetHashes::SqlGetHashes(), SqlGetTimestamp::SqlGetTimestamp(), catalog::SqlIncLinkcount::SqlIncLinkcount(), history::SqlInsertBranch::SqlInsertBranch(), history::SqlListBranches::SqlListBranches(), catalog::SqlListContentHashes::SqlListContentHashes(), SqlListReferences::SqlListReferences(), catalog::SqlLookupXattrs::SqlLookupXattrs(), catalog::SqlMaxHardlinkGroup::SqlMaxHardlinkGroup(), catalog::SqlNestedCatalogListing::SqlNestedCatalogListing(), catalog::SqlNestedCatalogLookup::SqlNestedCatalogLookup(), catalog::SqlOwnNestedCatalogListing::SqlOwnNestedCatalogListing(), history::SqlRecycleBinFlush::SqlRecycleBinFlush(), history::SqlRecycleBinList::SqlRecycleBinList(), SqlRemoveReference::SqlRemoveReference(), history::SqlRemoveTag::SqlRemoveTag(), catalog::SqlUpdateCounter::SqlUpdateCounter(), and sqlite::Database< DerivedT >::Vacuum().

Here is the caller graph for this function:

template<class DerivedT >
bool sqlite::Database< DerivedT >::StoreSchemaRevision ( )
protected

Definition at line 264 of file sql_impl.h.

Here is the call graph for this function:

template<class DerivedT >
void sqlite::Database< DerivedT >::TakeFileOwnership ( )

Transfers the ownership of the SQLite database file to the Database<> ob- ject. Hence, it will automatically unlink the file, once the Database<> object goes out of scope or is deleted.

Definition at line 342 of file sql_impl.h.

Referenced by catalog::Catalog::OpenDatabase(), swissknife::CommandFileStats::ProcessCatalog(), and catalog::Catalog::TakeDatabaseFileOwnership().

Here is the call graph for this function:

Here is the caller graph for this function:

template<class DerivedT >
bool sqlite::Database< DerivedT >::Vacuum ( ) const

Performs a VACUUM call on the opened database file to compacts the database. As a first step it runs DerivedT::CompactDatabase() to allow for implement- ation dependent cleanup actions. Vacuum() assumes that the SQLite database was opened in read/write mode.

Returns
true on success

Definition at line 423 of file sql_impl.h.

Referenced by catalog::WritableCatalog::VacuumDatabaseIfNecessary().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

template<class DerivedT>
UniquePtr<Sql> sqlite::Database< DerivedT >::begin_transaction_
private
template<class DerivedT>
UniquePtr<Sql> sqlite::Database< DerivedT >::commit_transaction_
private
template<class DerivedT>
UniquePtr<Sql> sqlite::Database< DerivedT >::get_property_
private
template<class DerivedT>
UniquePtr<Sql> sqlite::Database< DerivedT >::has_property_
private
template<class DerivedT>
const char * sqlite::Database< DerivedT >::kSchemaRevisionKey = "schema_revision"
staticprivate
template<class DerivedT>
const char * sqlite::Database< DerivedT >::kSchemaVersionKey = "schema"
staticprivate
template<class DerivedT>
const bool sqlite::Database< DerivedT >::read_write_
private
template<class DerivedT>
UniquePtr<Sql> sqlite::Database< DerivedT >::set_property_
private

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