libfossil
fsl_db Struct Reference

Db handle wrapper class. More...

#include "db.h"

Collaboration diagram for fsl_db:

Data Fields

fsl_db_t * dbh
 Underlying db driver handle.
fsl_error error
 Holds error state from the underlying driver.
char * filename
 Holds the file name used when opening this db.
struct { 
   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 fsl_free() it). More...
   fsl_buffer   buffer 
 Internal buffer to reduce reallocations caused via fsl_db_prepare_cached(), fsl_db_see_check(), and perhaps other internals. More...
   struct { 
      fsl_db_event_f   f 
 Event listener callback. More...
      FILE *   fpTrace 
 Older-style (pre-fsl_db_event) trace output channel. More...
      fsl_flag32_t   maskIds 
 The FSL_DB_EVENT_mask_id-masked part of event IDs to fire the callback for. More...
      void *   state 
 Impl-specific state for f. More...
   }   event
   fsl_flag32_t   flags 
 Internal flags. More...
   int   openStatementCount 
 Debugging/test counter. More...
   struct { 
      fsl_stmt *   head 
 An internal cache of "static" queries - those which do not rely on call-time state unless that state can be bind()ed. More...
   }   stCache
 State for use with fsl_db_prepare_cached(). More...
   struct { 
      int   level 
 Counter for fsl_db_txn_begin/end(). More...
      sqlite3_stmt *   sRelease 
 Prepared statements for SAVEPOINT RELEASE. More...
      sqlite3_stmt *   sRollback 
 Prepared statements for ROLLBACK TO SAVEPOINT. More...
      sqlite3_stmt *   sSavepoint 
 Prepared statements for SAVEPOINT management. More...
   }   txn
 Transaction-related state. More...
} impl
 Private implementation details.
char * name
 Holds the database name for use in creating queries.
fsl_flag16_t role
 Describes what role(s) this db connection plays in fossil (if any).

Detailed Description

Db handle wrapper class.

Each instance wraps a single sqlite database handle. Though this type's interface is not opaque, it is never legal for clients to directly manipulate the members.

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. In practice, library clients do not ever need to use the underlying sqlite API.

See also
fsl_db_open();
fsl_db_close();
fsl_stmt

Definition at line 313 of file db.h.

Field Documentation

◆ allocStamp

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 fsl_free() it).

Definition at line 434 of file db.h.

◆ buffer

fsl_buffer fsl_db::buffer

Internal buffer to reduce reallocations caused via fsl_db_prepare_cached(), fsl_db_see_check(), and perhaps other internals.

Definition at line 426 of file db.h.

◆ dbh

fsl_db_t* fsl_db::dbh

Underlying db driver handle.

Definition at line 318 of file db.h.

◆ error

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_swap()) so that they can pass it on up the call chain.

Definition at line 327 of file db.h.

◆ [struct]

struct { ... } fsl_db::event

◆ f

fsl_db_event_f fsl_db::f

Event listener callback.

Definition at line 384 of file db.h.

◆ filename

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).

Design note: we currently hold the name as it is passed to the db-open routine, without canonicalizing it. That is very possibly a mistake, as it makes it impossible to properly compare the name to another arbitrary checkout-relative name for purposes of fsl_reserved_fn_check(). For purposes of fsl_cx we currently (2021-03-12) canonicalize db's which we fsl_db_open(), but not those which we ATTACH (which includes the repo and checkout dbs). We cannot reasonably canonicalize the repo db filename because it gets written into the checkout db so that the checkout knows where to find the repository. History has shown that that path needs to be stored exactly as a user entered it, which is often relative.

Memory is owned by this object.

Definition at line 349 of file db.h.

◆ flags

fsl_flag32_t fsl_db::flags

Internal flags.

Definition at line 380 of file db.h.

◆ fpTrace

FILE* fsl_db::fpTrace

Older-style (pre-fsl_db_event) trace output channel.

Definition at line 393 of file db.h.

◆ head

fsl_stmt* fsl_db::head

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, managed by the fsl_db_prepare_cached() and fsl_stmt_cached_yield() APIs.

See also
fsl_db_prepare_cached()

Definition at line 419 of file db.h.

◆ [struct]

struct { ... } fsl_db::impl

Private implementation details.

◆ level

int fsl_db::level

Counter for fsl_db_txn_begin/end().

Definition at line 399 of file db.h.

◆ maskIds

fsl_flag32_t fsl_db::maskIds

The FSL_DB_EVENT_mask_id-masked part of event IDs to fire the callback for.

Definition at line 391 of file db.h.

◆ name

char* fsl_db::name

Holds the database name for use in creating queries.

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

Memory is owned by this object.

Definition at line 358 of file db.h.

◆ openStatementCount

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 375 of file db.h.

◆ role

fsl_flag16_t fsl_db::role

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

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

Definition at line 365 of file db.h.

◆ sRelease

sqlite3_stmt* fsl_db::sRelease

Prepared statements for SAVEPOINT RELEASE.

Definition at line 403 of file db.h.

◆ sRollback

sqlite3_stmt* fsl_db::sRollback

Prepared statements for ROLLBACK TO SAVEPOINT.

Definition at line 405 of file db.h.

◆ sSavepoint

sqlite3_stmt* fsl_db::sSavepoint

Prepared statements for SAVEPOINT management.

Definition at line 401 of file db.h.

◆ state

void* fsl_db::state

Impl-specific state for f.

Definition at line 386 of file db.h.

◆ [struct]

struct { ... } fsl_db::stCache

State for use with fsl_db_prepare_cached().

◆ [struct]

struct { ... } fsl_db::txn

Transaction-related state.


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