Represents a SQLite3 database. More...

#include <sl3/database.hpp>

Classes
class	Transaction
	Transaction Guard. More...

Public Types
using	Callback = Command::Callback
	shortcut for Command::Callback

Public Member Functions
	Database (const Database &)=delete
Database &	operator= (const Database &)=delete
Database &	operator= (Database &&)=delete
	Database (const std::string &name, int openFlags=0)
	Constructor.
virtual	~Database () noexcept
	Destructor.
	Database (Database &&) noexcept
	Move constructor.
Command	prepare (const std::string &sql)
	Create an SQL command instance.
Command	prepare (const std::string &sql, const DbValues &params)
	Create a Command.
void	execute (const std::string &sql)
	Execute one or more SQL statements.
void	execute (const char *sql)
	Execute one or more SQL statements.
void	execute (const std::string &sql, RowCallback &cb)
	Execute one SQL statement and apply a SqlQueryHandler.
void	execute (const std::string &sql, Callback cb)
	Execute one SQL statement and apply a QueryCallback.
Dataset	select (const std::string &sql)
	Execute a SQL query and return the result.
Dataset	select (const std::string &sql, const Types &types)
	Execute a SQL query and return the result.
DbValue	selectValue (const std::string &sql)
	Select a single value from the database.
DbValue	selectValue (const std::string &sql, Type type)
	Select a single typed value from the database.
int	getMostRecentErrCode ()
	Returns last SQLite3 extended result code.
std::string	getMostRecentErrMsg ()
	Returns most recent error message.
std::size_t	getTotalChanges ()
	Returns the number of rows that have changed since the database was opened.
std::size_t	getRecentlyChanged ()
	Rows that have been changed from the most recent SQL statement.
int64_t	getLastInsertRowid ()
	Returns the rowid of the most recent successful INSERT statement.
Transaction	beginTransaction ()
	Create a TransactionGuard.

Protected Member Functions
sqlite3 *	db ()
	Access the underlying sqlite3 database.

Detailed Description

Represents a SQLite3 database.

Encapsulates some of the most useful methods for a SQLite3 database object. A Database is opened when an instance is created and closed when the instance goes out of scope.

Note: for valgrind: http://www.sqlite.org/cvstrac/tktview?tn=3428
since I don't know where to put this note else I place it just here

Member Typedef Documentation

◆ Callback

using sl3::Database::Callback = Command::Callback

shortcut for Command::Callback

Constructor & Destructor Documentation

◆ Database() [1/2]

sl3::Database::Database	(	const std::string &	name,
		int	openFlags = 0 )

explicit

Constructor.

Construction of this object opens, or creates a sqlite3 database. The exact behavior can be fine tuned using the openFlags parameter.

Parameters

name	database name. If name is ":memory:" then the database will be an in-memory

database.
If name has a size of 0 then the database will be a private on-disk

database.
Otherwise name will be interpreted as a file.

Parameters

openFlags if no flags are given, the defaults are SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE.

See also: https://www.sqlite.org/c3ref/open.html

Exceptions

sl3::SQLite3Error if the database can not be opened

◆ ~Database()

virtual sl3::Database::~Database ( )

virtualnoexcept

Destructor.

◆ Database() [2/2]

sl3::Database::Database ( Database && )

noexcept

Move constructor.

A Database is movable

Member Function Documentation

◆ beginTransaction()

Transaction sl3::Database::beginTransaction ( )

Create a TransactionGuard.

Returns: Transaction instance

◆ db()

sqlite3 * sl3::Database::db ( )

protected

Access the underlying sqlite3 database.

Derived classes may, if needed, access the pointer to the sqlite3 database.

Note: : Do not change the state of database (call close on it).

Returns: a handle to the underlying sqlite3 database;

◆ execute() [1/4]

void sl3::Database::execute ( const char * sql )

Execute one or more SQL statements.

Overload for const char* to avoid a copy for large commands like

create-database scripts, which are often static char*.

Exceptions

sl3::SQLite3Error in case of a problem.

Parameters

sql	SQL Statements

◆ execute() [2/4]

void sl3::Database::execute ( const std::string & sql )

Execute one or more SQL statements.

Exceptions

sl3::SQLite3Error in case of a problem.

Parameters

sql	SQL Statements

◆ execute() [3/4]

void sl3::Database::execute	(	const std::string &	sql,
		Callback	cb )

Execute one SQL statement and apply a QueryCallback.

Exceptions

sl3::SQLite3Error in case of a problem.

Parameters

sql	SQL Statements
cb	Callback to handle query result

◆ execute() [4/4]

void sl3::Database::execute	(	const std::string &	sql,
		RowCallback &	cb )

Execute one SQL statement and apply a SqlQueryHandler.

Exceptions

sl3::SQLite3Error in case of a problem.

Parameters

sql	SQL Statements
cb	RowCallback to handle query result

◆ getLastInsertRowid()

int64_t sl3::Database::getLastInsertRowid ( )

Returns the rowid of the most recent successful INSERT statement.

Returns the rowid (ROWID, OID, or ROWID or the column of type INTEGER PRIMARY KEY ) of the most recent successful INSERT into the database.
If no successful INSERTs have ever occurred on that database, zero is returned.

Returns: rowid

◆ getMostRecentErrCode()

int sl3::Database::getMostRecentErrCode ( )

Returns last SQLite3 extended result code.

Note: SQLite3 result code in case of a failure is triggered within a SQLite3Error.

The return value is only valid if the last call failed.

Note: This function returns extended result codes

Returns: SQLite3 extended error code

◆ getMostRecentErrMsg()

std::string sl3::Database::getMostRecentErrMsg ( )

Returns most recent error message.

Returns: SQLite3 error message.

◆ getRecentlyChanged()

std::size_t sl3::Database::getRecentlyChanged ( )

Rows that have been changed from the most recent SQL statement.

Returns the number of rows that have been changed from the most recent successful SQL INSERT/UPDATE or DELETE statement.

Returns: Count of changed rows

◆ getTotalChanges()

std::size_t sl3::Database::getTotalChanges ( )

Returns the number of rows that have changed since the database was opened.

Returns the number of rows that have been changed through successful SQL INSERT/UPDATE or DELETE statements since the database was opened.

Returns: Count of changed rows

◆ prepare() [1/2]

Command sl3::Database::prepare ( const std::string & sql )

Create an SQL command instance.

Parameters that the statement might contain will be automatically deduced and created as DbVariant values

Parameters

sql	SQL statement

Returns: a Command instance

◆ prepare() [2/2]

Command sl3::Database::prepare	(	const std::string &	sql,
		const DbValues &	params )

Create a Command.

Given parameters will be used to set up the command parameters,

Parameters

sql	SQL statement
params	parameters

Exceptions

sl3::ErrTypeMisMatch if params count is wrong

Returns: a Command instance

◆ select() [1/2]

Dataset sl3::Database::select ( const std::string & sql )

Execute a SQL query and return the result.

Exceptions

sl3::SQLite3Error in case of a problem.

Parameters

sql	SQL Statements

Returns: a Dataset with the result.

◆ select() [2/2]

Dataset sl3::Database::select	(	const std::string &	sql,
		const Types &	types )

Execute a SQL query and return the result.

If Types are

Exceptions

sl3::SQLite3Error	in case of problems.
sl3::ErrTypeMisMatch	in case of incorrect types.

Parameters

sql	SQL Statements
types	wanted types of the returned Dataset

Returns: a Dataset with the result.

◆ selectValue() [1/2]

DbValue sl3::Database::selectValue ( const std::string & sql )

Select a single value from the database.

This is a quick way to get single value results for queries like "SELECT COUNT(*) FROM someTable;"
This function returns the first column of the first result row of the given query. If query returns no rows, the return value will be null.

Exceptions

sl3::SQLite3Error in case of problems.

Parameters

sql	SQL statement

Returns: DbValue of the first available result.

◆ selectValue() [2/2]

DbValue sl3::Database::selectValue	(	const std::string &	sql,
		Type	type )

Select a single typed value from the database.

This is a quick way to get single value results for queries like "SELECT COUNT(*) FROM someTable;"
This function returns the first column of the first result row of the given query. If query returns no rows, the return value will be null.

Exceptions

sl3::ErrTypeMisMatch	if return type differs from requested type
sl3::SQLite3Error	in case of problems.

Parameters

sql	SQL statement
type	result has to be of that Type

Returns: DbValue of the first available result.

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

include/sl3/database.hpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ Callback

Constructor & Destructor Documentation

◆ Database() [1/2]

◆ ~Database()

◆ Database() [2/2]

Member Function Documentation

◆ beginTransaction()

◆ db()

◆ execute() [1/4]

◆ execute() [2/4]

◆ execute() [3/4]

◆ execute() [4/4]

◆ getLastInsertRowid()

◆ getMostRecentErrCode()

◆ getMostRecentErrMsg()

◆ getRecentlyChanged()

◆ getTotalChanges()

◆ prepare() [1/2]

◆ prepare() [2/2]

◆ select() [1/2]

◆ select() [2/2]

◆ selectValue() [1/2]

◆ selectValue() [2/2]