A read-only source of tables. More...

#include <database_backend.h>

Inheritance diagram for DATABASE_BACKEND:

Public Member Functions
virtual	~DATABASE_BACKEND ()=default

virtual bool	Connect ()=0

virtual void	Disconnect ()=0

virtual bool	IsConnected () const =0

virtual bool	ListTables (std::vector< std::string > &aTables)=0
	Lists the tables and views, sorted by name.

virtual std::optional< DB_TABLE_INFO >	DescribeTable (const std::string &aTable)=0

virtual bool	ListColumns (const std::string &aTable, std::vector< std::string > &aColumns)
	Lists the column names of a table as the catalog reports them, empty if it has none, false if the catalog failed.

virtual bool	ReadTable (const DB_TABLE_INFO &aTable, const std::vector< std::string > &aColumns, size_t aMaxRows, std::vector< std::string > &aLabels, const DB_ROW_SINK &aSink)=0
	Reads rows of a table, handing each to aSink.

virtual bool	ReadAllRows (const DB_TABLE_INFO &aTable, const std::vector< std::string > &aColumns, std::vector< std::string > &aLabels, const DB_ROW_SINK &aSink, const DB_RESTART_SINK &aRestart)
	Reads every row of a table for a caller that keeps them, handing each to aSink.

virtual void	BeginLoadCycle (const DB_STOP_CHECK &aStopped)
	Brackets a load cycle, in which the caller reads each table once.

virtual void	EndLoadCycle ()

virtual std::optional< bool >	ReadRow (const DB_TABLE_INFO &aTable, const std::vector< std::string > &aColumns, const std::string &aKeyColumn, const std::string &aKey, std::vector< std::string > &aLabels, std::vector< DB_VALUE > &aRow)
	Reads the one row whose key column equals aKey, using an indexed lookup if the backend has one.

virtual std::string	GetLastError () const =0

virtual DB_FAILURE	GetLastFailure () const =0

Static Public Member Functions
static DB_BACKEND_RESULT	Create (const DATABASE_SOURCE &aSource, const wxString &aBasePath)
	Builds the backend for a source.

Static Public Attributes
static constexpr size_t	ALL_ROWS = std::numeric_limits<size_t>::max()
	Passed as ReadTable()'s row limit to read every row.

Detailed Description

A read-only source of tables.

DATABASE_CONNECTION owns one and supplies the locking, row cache, column matching and conversion to text, so a backend only talks to its database. A backend is never called from two threads at once.

Definition at line 102 of file database_backend.h.

Constructor & Destructor Documentation

◆ ~DATABASE_BACKEND()

virtual DATABASE_BACKEND::~DATABASE_BACKEND ( )

virtualdefault

Member Function Documentation

◆ BeginLoadCycle()

virtual void DATABASE_BACKEND::BeginLoadCycle ( const DB_STOP_CHECK & aStopped )

inlinevirtual

Brackets a load cycle, in which the caller reads each table once.

A backend may keep what it opens for the cycle's reads until the cycle ends. Cycles may nest, and only the outermost begin and end count. Nesting is backend-wide and may cross threads, as when a lookup on one thread reads a table while a refresh on another has a cycle open. The nested read keeps the stop check and sessions of the outermost cycle.

Parameters

aStopped may be empty; a backend that retries a read gives up when it returns true

Reimplemented in ACE_BACKEND.

Definition at line 161 of file database_backend.h.

◆ Connect()

virtual bool DATABASE_BACKEND::Connect ( )

pure virtual

Implemented in ACE_BACKEND, ODBC_BACKEND, and SQLITE_BACKEND.

◆ Create()

DB_BACKEND_RESULT DATABASE_BACKEND::Create	(	const DATABASE_SOURCE &	aSource,
		const wxString &	aBasePath )

static

Builds the backend for a source.

Parameters

aSource	the source as configured; ${CWD} is expanded in its connection string and path
aBasePath	the directory ${CWD} stands for

Returns: the backend, or a null backend with the failure and a message naming the problem

Definition at line 34 of file database_backend.cpp.

References _, ACCESS, DATABASE_SOURCE::Expanded(), INVALID, INVALID_TYPE, ACE_BACKEND::MISSING, NOT_SUPPORTED_ON_PLATFORM, ODBC, PROVIDER_MISSING, ACE_BACKEND::ProviderMissingMessage(), ACE_BACKEND::ProviderState(), source, SQLITE, UNKNOWN, and utf8().

Referenced by SCH_IO_DATABASE::connectOnce(), and SCH_IO_DATABASE::CreateConnection().

◆ DescribeTable()

virtual std::optional< DB_TABLE_INFO > DATABASE_BACKEND::DescribeTable ( const std::string & aTable )

pure virtual

Returns: the table's columns in catalog order, or nullopt if it was not found or the catalog failed

Implemented in ACE_BACKEND, ODBC_BACKEND, and SQLITE_BACKEND.

Referenced by ListColumns().

◆ Disconnect()

virtual void DATABASE_BACKEND::Disconnect ( )

pure virtual

Implemented in ACE_BACKEND, ODBC_BACKEND, and SQLITE_BACKEND.

◆ EndLoadCycle()

virtual void DATABASE_BACKEND::EndLoadCycle ( )

inlinevirtual

Reimplemented in ACE_BACKEND.

Definition at line 163 of file database_backend.h.

◆ GetLastError()

virtual std::string DATABASE_BACKEND::GetLastError ( ) const

pure virtual

Implemented in ACE_BACKEND, ODBC_BACKEND, and SQLITE_BACKEND.

Referenced by ListColumns().

◆ GetLastFailure()

virtual DB_FAILURE DATABASE_BACKEND::GetLastFailure ( ) const

pure virtual

Implemented in ACE_BACKEND, ODBC_BACKEND, and SQLITE_BACKEND.

◆ IsConnected()

virtual bool DATABASE_BACKEND::IsConnected ( ) const

pure virtual

Implemented in ACE_BACKEND, ODBC_BACKEND, and SQLITE_BACKEND.

◆ ListColumns()

bool DATABASE_BACKEND::ListColumns	(	const std::string &	aTable,
		std::vector< std::string > &	aColumns )

virtual

Lists the column names of a table as the catalog reports them, empty if it has none, false if the catalog failed.

Reimplemented in ODBC_BACKEND.

Definition at line 71 of file database_backend.cpp.

References DescribeTable(), GetLastError(), info, and DB_COLUMN::name.

◆ ListTables()

virtual bool DATABASE_BACKEND::ListTables ( std::vector< std::string > & aTables )

pure virtual

Lists the tables and views, sorted by name.

Implemented in ACE_BACKEND, ODBC_BACKEND, and SQLITE_BACKEND.

◆ ReadAllRows()

virtual bool DATABASE_BACKEND::ReadAllRows	(	const DB_TABLE_INFO &	aTable,
		const std::vector< std::string > &	aColumns,
		std::vector< std::string > &	aLabels,
		const DB_ROW_SINK &	aSink,
		const DB_RESTART_SINK &	aRestart )

inlinevirtual

Reads every row of a table for a caller that keeps them, handing each to aSink.

A backend that checks one read against another may deliver the table more than once, and calls aRestart before every delivery after the first, so the caller drops the rows it already took. The default reads once.

Parameters

aLabels is filled with the result-column labels before each delivery's first call to aSink

Returns: false on failure, in which case the caller discards any rows already delivered

Reimplemented in ACE_BACKEND.

Definition at line 146 of file database_backend.h.

References ALL_ROWS, and ReadTable().

◆ ReadRow()

virtual std::optional< bool > DATABASE_BACKEND::ReadRow	(	const DB_TABLE_INFO &	aTable,
		const std::vector< std::string > &	aColumns,
		const std::string &	aKeyColumn,
		const std::string &	aKey,
		std::vector< std::string > &	aLabels,
		std::vector< DB_VALUE > &	aRow )

inlinevirtual

Reads the one row whose key column equals aKey, using an indexed lookup if the backend has one.

Returns: nullopt if the backend has no indexed lookup, otherwise true when aRow was filled

Reimplemented in ODBC_BACKEND.

Definition at line 170 of file database_backend.h.

◆ ReadTable()

virtual bool DATABASE_BACKEND::ReadTable	(	const DB_TABLE_INFO &	aTable,
		const std::vector< std::string > &	aColumns,
		size_t	aMaxRows,
		std::vector< std::string > &	aLabels,
		const DB_ROW_SINK &	aSink )

pure virtual

Reads rows of a table, handing each to aSink.

Parameters

aColumns	the columns to read; empty reads all of them
aMaxRows	stops after this many rows; zero fills aLabels and fetches no rows. A bounded read is ordered by the first column where the backend can.
aLabels	is filled with the result-column labels as the source spells them, before the first call to aSink

Returns: false on failure, in which case the caller discards any rows already delivered

Implemented in ACE_BACKEND, ODBC_BACKEND, and SQLITE_BACKEND.

Referenced by ReadAllRows().

Member Data Documentation

◆ ALL_ROWS

size_t DATABASE_BACKEND::ALL_ROWS = std::numeric_limits<size_t>::max()

staticconstexpr

Passed as ReadTable()'s row limit to read every row.

Definition at line 106 of file database_backend.h.

Referenced by ReadAllRows(), ACE_BACKEND::ReadTable(), ODBC_BACKEND::ReadTable(), SQLITE_BACKEND::ReadTable(), and ACE_BACKEND::readVerified().

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~DATABASE_BACKEND()

Member Function Documentation

◆ BeginLoadCycle()

◆ Connect()

◆ Create()

◆ DescribeTable()

◆ Disconnect()

◆ EndLoadCycle()

◆ GetLastError()

◆ GetLastFailure()

◆ IsConnected()

◆ ListColumns()

◆ ListTables()

◆ ReadAllRows()

◆ ReadRow()

◆ ReadTable()

Member Data Documentation

◆ ALL_ROWS