|
KiCad PCB EDA Suite
|
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 |
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.
|
private |
Definition at line 172 of file database_connection.h.
| typedef std::map<std::string, std::any> DATABASE_CONNECTION::ROW |
Definition at line 45 of file database_connection.h.
| DATABASE_CONNECTION::DATABASE_CONNECTION | ( | std::unique_ptr< DATABASE_BACKEND > | aBackend, |
| bool | aConnectNow = true ) |
| aBackend | the backend to read through; must not be null |
| aConnectNow | false 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().
| 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.
| aTable | the name of a table in the database |
| aRequiredColumns | columns that must be present in queries even if the backend does not report them |
| aOptionalColumns | columns that are added only when the backend confirms they exist |
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.
|
inline |
Definition at line 160 of file database_connection.h.
References m_cache.
|
staticprivate |
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().
| 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().
| bool DATABASE_CONNECTION::Disconnect | ( | ) |
Definition at line 89 of file database_connection.cpp.
References m_backend, and m_queryMutex.
|
staticprivate |
Definition at line 229 of file database_connection.cpp.
Referenced by readAndCache().
| 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.
|
inline |
Definition at line 166 of file database_connection.h.
References m_backend.
|
inline |
Definition at line 169 of file database_connection.h.
References m_backend.
| std::optional< DATABASE_CONNECTION::TABLE_FAILURE > DATABASE_CONNECTION::GetTableFailure | ( | const std::string & | aTable | ) | const |
Definition at line 401 of file database_connection.cpp.
References m_queryMutex, and m_tableFailures.
| 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.
| bool DATABASE_CONNECTION::IsConnected | ( | ) | const |
Definition at line 99 of file database_connection.cpp.
References m_backend.
Referenced by SCH_IO_DATABASE::connect().
|
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().
|
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().
| 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.
| aTable | the name of a table in the database |
| aKey | holds the column name of the primary key used for caching results |
| aResults | will be filled with all rows in the table |
| aStatus | if not null, receives the state of the failure when the query fails |
Definition at line 412 of file database_connection.cpp.
References m_backend, m_cache, m_queryMutex, m_tableFailures, m_tables, readAndCache(), traceDatabase, and UNKNOWN.
| 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.
| aTable | the name of a table in the database |
| aWhere | column to search, and the value to search for |
| aResult | will be filled with a row in the database if one was found |
Definition at line 323 of file database_connection.cpp.
References columnNames(), m_backend, m_cache, m_queryMutex, m_tables, makeRow(), readAndCache(), table, and traceDatabase.
| 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.
| aTable | the name of a table in the database |
| aMaxRows | stop fetching after this many rows; zero fetches only the column names |
| aColumns | will be filled with the column names in result order |
| aRows | will be filled with up to aMaxRows rows |
Definition at line 481 of file database_connection.cpp.
References info, m_backend, m_queryMutex, m_tables, and makeRow().
| void DATABASE_CONNECTION::SetCacheParams | ( | int | aMaxSize, |
| int | aMaxAge ) |
Definition at line 59 of file database_connection.cpp.
References m_cache.
|
private |
Definition at line 198 of file database_connection.h.
Referenced by CacheTableInfo(), Connect(), DATABASE_CONNECTION(), Disconnect(), GetColumns(), GetLastError(), GetLastFailure(), GetTables(), IsConnected(), readAndCache(), SelectAll(), SelectOne(), and SelectSample().
|
private |
Definition at line 207 of file database_connection.h.
Referenced by ClearCache(), DATABASE_CONNECTION(), readAndCache(), SelectAll(), SelectOne(), and SetCacheParams().
|
mutableprivate |
Definition at line 205 of file database_connection.h.
Referenced by CacheTableInfo(), Connect(), Disconnect(), GetColumns(), GetTableFailure(), GetTables(), SelectAll(), SelectOne(), and SelectSample().
|
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().
|
private |
Definition at line 200 of file database_connection.h.
Referenced by CacheTableInfo(), Connect(), readAndCache(), SelectAll(), SelectOne(), and SelectSample().