libfossil
fsl::Db Class Reference

C++ counterpart to fsl_db. More...

#include "fossil.hpp"

Data Structures

class  Transaction
 A utility to simplify db transaction lifetimes. More...
 

Public Member Functions

 Db ()
 Initializes internal state for a closed db. More...
 
 Db (char const *filename, int openFlags)
 Initializes internal state and calls Calls this->open(filename,openFlags). More...
 
virtual ~Db () throw ()
 Calls this->close(). More...
 
Dbattach (char const *filename, char const *label)
 Analog to fsl_db_attach(), but throws on error. More...
 
Dbbegin ()
 Pushes a level onto the pseudo-recursive transaction stack. More...
 
Dbclose () throw ()
 If this->ownsHandle() is true and this object has an opened db, it fsl_db_close() that db, (possibly) freeing the handle and (definitely) any db-owned resources. More...
 
Dbcommit ()
 Pops one level from the transaction stack as "successful," commiting the transaction only once all levels have been popped. More...
 
Dbdetach (char const *label)
 Analog to fsl_db_detach(), but throws on error. More...
 
Dbexec (char const *sql,...)
 Executes the given single fsl_appendf()-formatted SQL statement. More...
 
Dbexec (std::string const &sql)
 Equivalent to this->exec("%s", sql.c_str()). More...
 
DbexecMulti (char const *sql,...)
 Executes one or more SQL statements provided in the fsl_appendf()-formatted SQL string. More...
 
DbexecMulti (std::string const &sql)
 Equivalent to this->execMulti("%s", sql.c_str()). More...
 
char const * filename () throw ()
 Returns the filename used to open the DB or NULL if it is not opened. More...
 
Dbhandle (fsl_db *db, bool ownsHandle) throw ()
 Calls this->close() and replaces the internal db handle with the given one. More...
 
fsl_dbhandle () throw ()
 Returns this object's C-level fsl_db handle. More...
 
fsl_db const * handle () const throw ()
 Const-correct overload. More...
 
bool isOpened () const throw ()
 Returns true if this object has an opened db handle, else false. More...
 
Dbopen (char const *filename, int openFlags)
 Counterpart of fsl_db_open(), with the same semantics for the arguments, except that this function throws on error. More...
 
 operator fsl_db * () throw ()
 Implicit conversion to (fsl_db *) to simplify usage with the C API. More...
 
 operator fsl_db const * () const throw ()
 Const-correct overload. More...
 
bool ownsHandle () const throw ()
 Returns true if this object owns its underlying db handle, else false. More...
 
Dbrollback () throw ()
 Pops one level from the transaction stack and marks the whole transaction as failed. More...
 
int transactionLevel () const throw ()
 Returns the current number of transactions pushed onto the transaction stack. More...
 

Friends

class Stmt
 

Detailed Description

C++ counterpart to fsl_db.

The vast majority of the members (those not marked with throw()) throw an Exception on error.

Definition at line 822 of file fossil.hpp.

Constructor & Destructor Documentation

fsl::Db::Db ( )

Initializes internal state for a closed db.

Use open() to open it or handle() to import a foreign fsl_db handle.

fsl::Db::Db ( char const *  filename,
int  openFlags 
)

Initializes internal state and calls Calls this->open(filename,openFlags).

virtual fsl::Db::~Db ( )
throw (
)
virtual

Calls this->close().

Member Function Documentation

Db& fsl::Db::attach ( char const *  filename,
char const *  label 
)

Analog to fsl_db_attach(), but throws on error.

Db& fsl::Db::begin ( )

Pushes a level onto the pseudo-recursive transaction stack.

See fsl_db_transaction_begin().

Throws on error. Returns this object on success.

DO NOT EVER use transactions in the API without this function. For example, NEVER exec("BEGIN") because that bypasses the recursive transaction support.

For an exception-safer alternative to managing transaction lifetimes, see the Db::Transaction helper class.

Db& fsl::Db::close ( )
throw (
)

If this->ownsHandle() is true and this object has an opened db, it fsl_db_close() that db, (possibly) freeing the handle and (definitely) any db-owned resources.

If !this->ownsHandle() this this clears this object's reference to the underlying db but does _not_ fsl_db_close() it. If this object has no Db handle then this is a harmless no-op.

Db& fsl::Db::commit ( )

Pops one level from the transaction stack as "successful," commiting the transaction only once all levels have been popped.

See fsl_db_transaction_commit().

Throws on error. Returns this object on success.

DO NOT EVER commit a transaction without this function. For example, NEVER exec("COMMIT") because that bypasses the recursive transaction support.

Db& fsl::Db::detach ( char const *  label)

Analog to fsl_db_detach(), but throws on error.

Db& fsl::Db::exec ( char const *  sql,
  ... 
)

Executes the given single fsl_appendf()-formatted SQL statement.

See fsl_appendf() for the formatting options.

Throws on error. Returns this object.

See Stmt::prepare() for notes about how to sanely deal with unsanitized SQL strings from foreign sources.

Db& fsl::Db::exec ( std::string const &  sql)

Equivalent to this->exec("%s", sql.c_str()).

Db& fsl::Db::execMulti ( char const *  sql,
  ... 
)

Executes one or more SQL statements provided in the fsl_appendf()-formatted SQL string.

See fsl_db_exec_multi() for details. This can be used to import whole schemas at once, for example.

Throws on error. Returns this object.

Db& fsl::Db::execMulti ( std::string const &  sql)

Equivalent to this->execMulti("%s", sql.c_str()).

char const* fsl::Db::filename ( )
throw (
)

Returns the filename used to open the DB or NULL if it is not opened.

Db& fsl::Db::handle ( fsl_db db,
bool  ownsHandle 
)
throw (
)

Calls this->close() and replaces the internal db handle with the given one.

If ownsHandle is true then this object takes over ownership of db. It is CRITICAL that there never be more than one owner (and that owner may be at the C level, unaware of this class). It is also critical that the "owning" Db instance (or exteran fsl_db handle not associated with an owning Db instance) outlive any shared Db instances using that handle. (We can't currently ensure that with a shared pointer due to C-level ownership internals.)

If ownsHandle is false then this object becomes a proxy for the given handle but will never close the handle - its memory is assumed to live somewhere else and the fsl_db instance MUST OUTLIVE THIS OBJECT.

It is legal to pass NULL db, which triggers a close() and then clears the Db handle. In that case, this object will create a new handle if open() is called on it while it has none.

As a special case, if this->handle()==db, this is a no-op.

The primarily intention of this mechanism is so that fsl::Context, which proxies up to three db handles, can do so without having to fight the C-level API for ownership of those handles.

fsl_db* fsl::Db::handle ( )
throw (
)

Returns this object's C-level fsl_db handle.

Provided so that client APIs can use fsl_db_xxx() functions not wrapped by the C++ APIs. DO NOT, under ANY CIRCUMSTANCES, delete, free, fsl_db_close(), nor otherwise mess with this handle's ownership. It is owned by this object.

Returns NULL if not yet prepared.

fsl_db const* fsl::Db::handle ( ) const
throw (
)

Const-correct overload.

bool fsl::Db::isOpened ( ) const
throw (
)

Returns true if this object has an opened db handle, else false.

Db& fsl::Db::open ( char const *  filename,
int  openFlags 
)

Counterpart of fsl_db_open(), with the same semantics for the arguments, except that this function throws on error.

Throws on error, else returns this object.

Throws if the db is currently opened.

fsl::Db::operator fsl_db * ( )
throw (
)

Implicit conversion to (fsl_db *) to simplify usage with the C API.

ABSOLUTELY DO NOT:

  • ... use this conversion to pass this object to fsl_db_close()!!! Doing so will lead to a dangling pointer and an eventual segfault and/or double-free().
  • ... expect this conversion to be picked up when a function takes a void pointer argument.
fsl::Db::operator fsl_db const * ( ) const
throw (
)

Const-correct overload.

bool fsl::Db::ownsHandle ( ) const
throw (
)

Returns true if this object owns its underlying db handle, else false.

Note that it may legally return true even when handle() returns NULL, meaning that this object is prepared to create a handle of its own if needed.

Db& fsl::Db::rollback ( )
throw (
)

Pops one level from the transaction stack and marks the whole transaction as failed.

It will not actually roll back the transaction until all levels have been popped, but further commit() calls will implicitly fail until the top-most transaction level is committed, at which point it will recognize the failure and perform a rollback instead.

See fsl_db_transaction_rollback().

Throws on error. Returns this object on success.

DO NOT EVER roll back a transaction without this function. For example, NEVER exec("ROLLBACK") because that bypasses the recursive transaction support.

int fsl::Db::transactionLevel ( ) const
throw (
)

Returns the current number of transactions pushed onto the transaction stack.

If this is greater than 0 then a transaction is active (though it might have a failure from a rollback() performed higher up in the stack).

Friends And Related Function Documentation

friend class Stmt
friend

Definition at line 1098 of file fossil.hpp.


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