KiCad PCB EDA Suite
Loading...
Searching...
No Matches
DATABASE_CONNECTION Class Reference

A read-only view of a database library source. More...

#include <database_connection.h>

Classes

class  LOAD_CYCLE
 Brackets the reads of one library load or refresh, so the backend can keep what it opens for them. More...
 
struct  QUERY_STATUS
 What a failed query left behind, copied before another thread's query can replace it. More...
 
struct  TABLE_FAILURE
 Why CacheTableInfo could not describe a table. More...
 
struct  TABLE_STATE
 A table the backend described, with the columns queries against it read. More...
 

Public Types

typedef std::map< std::string, std::any > ROW
 

Public Member Functions

 DATABASE_CONNECTION (std::unique_ptr< DATABASE_BACKEND > aBackend, bool aConnectNow=true)
 
void SetCacheParams (int aMaxSize, int aMaxAge)
 
bool Connect ()
 
bool Disconnect ()
 
bool IsConnected () const
 
bool CacheTableInfo (const std::string &aTable, const std::set< std::string > &aRequiredColumns, const std::set< std::string > &aOptionalColumns={})
 Caches schema information for a table so that subsequent queries know which columns exist.
 
bool SelectOne (const std::string &aTable, const std::pair< std::string, std::string > &aWhere, ROW &aResult)
 Retrieves a single row from a database table.
 
std::optional< TABLE_FAILURE > GetTableFailure (const std::string &aTable) const
 
bool SelectAll (const std::string &aTable, const std::string &aKey, std::vector< ROW > &aResults, QUERY_STATUS *aStatus=nullptr)
 Retrieves all rows from a database table.
 
bool SelectSample (const std::string &aTable, size_t aMaxRows, std::vector< std::string > &aColumns, std::vector< ROW > &aRows)
 Reads the first rows of a table, bypassing the row cache.
 
bool GetTables (std::vector< std::string > &aTables)
 Lists the tables and views visible through this connection, sorted by name.
 
bool GetColumns (const std::string &aTable, std::vector< std::string > &aColumns)
 Lists the columns of a table in catalog order.
 
void ClearCache (const std::string &aTable)
 
std::string GetLastError () const
 
DB_FAILURE GetLastFailure () const
 

Private Types

typedef DATABASE_CACHE< std::map< std::string, ROW > > DB_CACHE_TYPE
 

Private Member Functions

bool readAndCache (const std::string &aTable, const std::string &aKey, DB_CACHE_TYPE::CACHE_VALUE &aEntry)
 Reads a whole table into aEntry and offers it to the row cache.
 

Static Private Member Functions

static std::vector< std::string > columnNames (const TABLE_STATE &aTable)
 
static std::optional< size_t > findLabel (const std::vector< std::string > &aLabels, const std::string &aKey)
 
static ROW makeRow (const std::vector< std::string > &aLabels, std::vector< DB_VALUE > &&aValues)
 Converts one row delivered by the backend to text keyed by result-column label.
 

Private Attributes

std::unique_ptr< DATABASE_BACKEND > m_backend
 
std::map< std::string, TABLE_STATE > m_tables
 
std::map< std::string, TABLE_FAILURE > m_tableFailures
 Why CacheTableInfo could not describe each table, so a later query on it reports that table's own failure.
 
std::mutex m_queryMutex
 
std::unique_ptr< DB_CACHE_TYPE > m_cache
 

Detailed Description

A read-only view of a database library source.

Owns the backend that talks to the database and adds what every backend shares: serialised access, the row cache, column-name matching and the conversion of values to the text KiCad stores.

Definition at line 42 of file database_connection.h.

Member Typedef Documentation

◆ DB_CACHE_TYPE

typedef DATABASE_CACHE<std::map<std::string, ROW> > DATABASE_CONNECTION::DB_CACHE_TYPE
private

Definition at line 172 of file database_connection.h.

◆ ROW

typedef std::map<std::string, std::any> DATABASE_CONNECTION::ROW

Definition at line 45 of file database_connection.h.

Constructor & Destructor Documentation

◆ DATABASE_CONNECTION()

DATABASE_CONNECTION::DATABASE_CONNECTION ( std::unique_ptr< DATABASE_BACKEND > aBackend,
bool aConnectNow = true )
Parameters
aBackendthe backend to read through; must not be null
aConnectNowfalse defers connecting to the caller's Connect(), e.g. on a worker thread

Definition at line 31 of file database_connection.cpp.

References Connect(), m_backend, m_cache, and move.

Referenced by DATABASE_CONNECTION::LOAD_CYCLE::LOAD_CYCLE().

Member Function Documentation

◆ CacheTableInfo()

bool DATABASE_CONNECTION::CacheTableInfo ( const std::string & aTable,
const std::set< std::string > & aRequiredColumns,
const std::set< std::string > & aOptionalColumns = {} )

Caches schema information for a table so that subsequent queries know which columns exist.

Required columns are trusted even if the backend doesn't report them (e.g. SQLite generated columns). Optional columns are added only if confirmed present; otherwise they are dropped with a warning rather than breaking every query against the table. Matching is case-insensitive. Columns the backend reports as unreadable are dropped even when required.

Parameters
aTablethe name of a table in the database
aRequiredColumnscolumns that must be present in queries even if the backend does not report them
aOptionalColumnscolumns that are added only when the backend confirms they exist
Returns
true on success

Definition at line 105 of file database_connection.cpp.

References DATABASE_CONNECTION::TABLE_FAILURE::columns, DATABASE_CONNECTION::TABLE_FAILURE::error, DATABASE_CONNECTION::TABLE_FAILURE::failure, info, m_backend, m_queryMutex, m_tableFailures, m_tables, DB_COLUMN::name, DB_COLUMN::supported, table, and traceDatabase.

◆ ClearCache()

void DATABASE_CONNECTION::ClearCache ( const std::string & aTable)
inline

Definition at line 160 of file database_connection.h.

References m_cache.

◆ columnNames()

std::vector< std::string > DATABASE_CONNECTION::columnNames ( const TABLE_STATE & aTable)
staticprivate
Returns
the names of the columns to read from a table

Definition at line 215 of file database_connection.cpp.

References DATABASE_CONNECTION::TABLE_STATE::columns, DATABASE_CONNECTION::TABLE_STATE::info, DB_TABLE_INFO::name, and traceDatabase.

Referenced by readAndCache(), and SelectOne().

◆ Connect()

bool DATABASE_CONNECTION::Connect ( )

Definition at line 75 of file database_connection.cpp.

References m_backend, m_queryMutex, m_tableFailures, and m_tables.

Referenced by DATABASE_CONNECTION().

◆ Disconnect()

bool DATABASE_CONNECTION::Disconnect ( )

Definition at line 89 of file database_connection.cpp.

References m_backend, and m_queryMutex.

◆ findLabel()

std::optional< size_t > DATABASE_CONNECTION::findLabel ( const std::vector< std::string > & aLabels,
const std::string & aKey )
staticprivate
Returns
the position in aLabels of the key column, matched exactly first and then ignoring case

Definition at line 229 of file database_connection.cpp.

Referenced by readAndCache().

◆ GetColumns()

bool DATABASE_CONNECTION::GetColumns ( const std::string & aTable,
std::vector< std::string > & aColumns )

Lists the columns of a table in catalog order.

Definition at line 526 of file database_connection.cpp.

References m_backend, and m_queryMutex.

◆ GetLastError()

std::string DATABASE_CONNECTION::GetLastError ( ) const
inline

Definition at line 166 of file database_connection.h.

References m_backend.

◆ GetLastFailure()

DB_FAILURE DATABASE_CONNECTION::GetLastFailure ( ) const
inline
Returns
why the last connection attempt failed

Definition at line 169 of file database_connection.h.

References m_backend.

◆ GetTableFailure()

std::optional< DATABASE_CONNECTION::TABLE_FAILURE > DATABASE_CONNECTION::GetTableFailure ( const std::string & aTable) const
Returns
why CacheTableInfo could not describe aTable, or nothing if it was described

Definition at line 401 of file database_connection.cpp.

References m_queryMutex, and m_tableFailures.

◆ GetTables()

bool DATABASE_CONNECTION::GetTables ( std::vector< std::string > & aTables)

Lists the tables and views visible through this connection, sorted by name.

Definition at line 513 of file database_connection.cpp.

References m_backend, and m_queryMutex.

◆ IsConnected()

bool DATABASE_CONNECTION::IsConnected ( ) const

Definition at line 99 of file database_connection.cpp.

References m_backend.

Referenced by SCH_IO_DATABASE::connect().

◆ makeRow()

DATABASE_CONNECTION::ROW DATABASE_CONNECTION::makeRow ( const std::vector< std::string > & aLabels,
std::vector< DB_VALUE > && aValues )
staticprivate

Converts one row delivered by the backend to text keyed by result-column label.

Definition at line 248 of file database_connection.cpp.

References DatabaseValueToString(), and text.

Referenced by readAndCache(), SelectOne(), and SelectSample().

◆ readAndCache()

bool DATABASE_CONNECTION::readAndCache ( const std::string & aTable,
const std::string & aKey,
DB_CACHE_TYPE::CACHE_VALUE & aEntry )
private

Reads a whole table into aEntry and offers it to the row cache.

The caller must already hold m_queryMutex. aEntry is untouched and the cache unchanged unless the read succeeded.

Definition at line 265 of file database_connection.cpp.

References columnNames(), DatabaseValueToString(), findLabel(), m_backend, m_cache, m_tables, makeRow(), PROF_TIMER::msecs(), PROF_TIMER::Stop(), table, and traceDatabase.

Referenced by SelectAll(), and SelectOne().

◆ SelectAll()

bool DATABASE_CONNECTION::SelectAll ( const std::string & aTable,
const std::string & aKey,
std::vector< ROW > & aResults,
QUERY_STATUS * aStatus = nullptr )

Retrieves all rows from a database table.

Parameters
aTablethe name of a table in the database
aKeyholds the column name of the primary key used for caching results
aResultswill be filled with all rows in the table
aStatusif not null, receives the state of the failure when the query fails
Returns
true if the query succeeded and at least one ROW was found, false otherwise

Definition at line 412 of file database_connection.cpp.

References m_backend, m_cache, m_queryMutex, m_tableFailures, m_tables, readAndCache(), traceDatabase, and UNKNOWN.

◆ SelectOne()

bool DATABASE_CONNECTION::SelectOne ( const std::string & aTable,
const std::pair< std::string, std::string > & aWhere,
DATABASE_CONNECTION::ROW & aResult )

Retrieves a single row from a database table.

Table and column names are cached when the connection is created, so schema changes to the database won't be recognized unless the connection is recreated.

Parameters
aTablethe name of a table in the database
aWherecolumn to search, and the value to search for
aResultwill be filled with a row in the database if one was found
Returns
true if aResult was filled; false otherwise

Definition at line 323 of file database_connection.cpp.

References columnNames(), m_backend, m_cache, m_queryMutex, m_tables, makeRow(), readAndCache(), table, and traceDatabase.

◆ SelectSample()

bool DATABASE_CONNECTION::SelectSample ( const std::string & aTable,
size_t aMaxRows,
std::vector< std::string > & aColumns,
std::vector< ROW > & aRows )

Reads the first rows of a table, bypassing the row cache.

Parameters
aTablethe name of a table in the database
aMaxRowsstop fetching after this many rows; zero fetches only the column names
aColumnswill be filled with the column names in result order
aRowswill be filled with up to aMaxRows rows
Returns
true if the query succeeded

Definition at line 481 of file database_connection.cpp.

References info, m_backend, m_queryMutex, m_tables, and makeRow().

◆ SetCacheParams()

void DATABASE_CONNECTION::SetCacheParams ( int aMaxSize,
int aMaxAge )

Definition at line 59 of file database_connection.cpp.

References m_cache.

Member Data Documentation

◆ m_backend

◆ m_cache

std::unique_ptr<DB_CACHE_TYPE> DATABASE_CONNECTION::m_cache
private

◆ m_queryMutex

std::mutex DATABASE_CONNECTION::m_queryMutex
mutableprivate

◆ m_tableFailures

std::map<std::string, TABLE_FAILURE> DATABASE_CONNECTION::m_tableFailures
private

Why CacheTableInfo could not describe each table, so a later query on it reports that table's own failure.

Definition at line 203 of file database_connection.h.

Referenced by CacheTableInfo(), Connect(), GetTableFailure(), and SelectAll().

◆ m_tables

std::map<std::string, TABLE_STATE> DATABASE_CONNECTION::m_tables
private

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