libfossil
fsl_db Struct Reference

Db handle wrapper class. More...

#include "fossil-db.h"

Data Fields

void const * allocStamp
 A marker which tells fsl_db_close() whether or not fsl_db_malloc() allocated this instance (in which case fsl_db_close() will fsl_free() it) or not (in which case it does not free() it). More...
 
fsl_list beforeCommit
 List of SQL commands (char *) which should be executed prior to a commit. More...
 
int beginCount
 Counter for fsl_db_transaction_begin/end(). More...
 
fsl_stmtcacheHead
 An internal cache of "static" queries - those which do not rely on call-time state unless that state can be bind()ed. More...
 
fsl_dbh_tdbh
 Underlying db driver handle. More...
 
int doRollback
 Internal flag for communicating rollback state through the call stack. More...
 
fsl_error error
 Holds error state from the underlying driver. More...
 
fsl_cxf
 Fossil Context on whose behalf this instance is operating, if any. More...
 
char * filename
 Holds the file name used when opening this db. More...
 
char * name
 Holds the database name for use in creating queries. More...
 
int openStatementCount
 Debugging/test counter. More...
 
int priorChanges
 Internal change counter. More...
 
int role
 Describes what role(s) this db connection plays in fossil (if any). More...
 

Detailed Description

Db handle wrapper class.

Each instance wraps a single sqlite database handle.

Fossil is built upon sqlite3, but this abstraction is intended to hide that, insofar as possible, from clients so as to simplify an eventual port from v3 to v4. Clients should avoid relying on the underlying db being sqlite (or at least not rely on a specific version), but may want to register custom functions with the driver (or perform similar low-level operations) and the option is left open for them to access that handle via the fsl_db::dbh member.

See also
fsl_db_open();
fsl_db_close();
fsl_stmt

Definition at line 105 of file fossil-db.h.

Field Documentation

void const* fsl_db::allocStamp

A marker which tells fsl_db_close() whether or not fsl_db_malloc() allocated this instance (in which case fsl_db_close() will fsl_free() it) or not (in which case it does not free() it).

Definition at line 216 of file fossil-db.h.

fsl_list fsl_db::beforeCommit

List of SQL commands (char *) which should be executed prior to a commit.

This list is cleared when the transaction counter drops to zero as the result of fsl_db_transaction_end() or fsl_db_rollback_force().

TODO? Use (fsl_stmt*) objects instead of strings? Depends on how much data we need to bind here (want to avoid an extra copy if we need to bind big stuff). That was implemented in [9d9375ac2d], but that approach prohibits multi-statement pre-commit triggers, so it was not trunked. It's still unknown whether we need multi-statement SQL in this context (==fossil's infrastructure).

See also
fsl_db_before_commit()

Definition at line 199 of file fossil-db.h.

int fsl_db::beginCount

Counter for fsl_db_transaction_begin/end().

Definition at line 158 of file fossil-db.h.

fsl_stmt* fsl_db::cacheHead

An internal cache of "static" queries - those which do not rely on call-time state unless that state can be bind()ed.

Holds a linked list of (fsl_stmt*) instances.

See also
fsl_db_prepare_cached()

Definition at line 208 of file fossil-db.h.

fsl_dbh_t* fsl_db::dbh

Underlying db driver handle.

Definition at line 124 of file fossil-db.h.

int fsl_db::doRollback

Internal flag for communicating rollback state through the call stack.

If this is set to a true value, fsl_db_transaction_end() calls will behave like a rollback regardless of the value of the 2nd argument passed to that function. i.e. it propagates a rollback through nested transactions.

Potential TODO: instead of treating this like a boolean, store the error number which caused the rollback here. We'd have to go fix a lot of code for that, though :/.

Definition at line 172 of file fossil-db.h.

fsl_error fsl_db::error

Holds error state from the underlying driver.

fsl_db and fsl_stmt operations which fail at the driver level "should" update this state to include error info from the driver. fsl_cx APIs which fail at the DB level uplift this (using fsl_error_move()) so that they can pass it on up the call chain.

Definition at line 133 of file fossil-db.h.

fsl_cx* fsl_db::f

Fossil Context on whose behalf this instance is operating, if any.

Certain db operations behave differently depending on whether or not this is NULL.

Definition at line 111 of file fossil-db.h.

char* fsl_db::filename

Holds the file name used when opening this db.

Might not refer to a real file (e.g. might be ":memory:" or "" (similar to ":memory:" but may swap to temp storage).

Definition at line 140 of file fossil-db.h.

char* fsl_db::name

Holds the database name for use in creating queries.

Might or might not be set/needed, depending on the context.

Definition at line 147 of file fossil-db.h.

int fsl_db::openStatementCount

Debugging/test counter.

Closing a db with opened statements might assert() or trigger debug output when the db is closed.

Definition at line 153 of file fossil-db.h.

int fsl_db::priorChanges

Internal change counter.

Set when a transaction is started/committed.

Maintenance note: it's an int because that's what sqlite3_total_changes() returns.

Definition at line 181 of file fossil-db.h.

int fsl_db::role

Describes what role(s) this db connection plays in fossil (if any).

This is a bitmask of fsl_db_role_t values, and a db connection may have multiple roles. This is only used by the fsl_cx-internal API.

Definition at line 119 of file fossil-db.h.


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