libsl3  1.12.2
C++ interface for sqlite3
Classes | Public Types | Public Member Functions | Protected Member Functions | List of all members
sl3::Database Class Reference

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

Public Member Functions

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

Protected Member Functions

sqlite3 * db ()
 Access the underlying sqlite3 database. More...
 

Detailed Description

represents a SQLite3 Database

Encapsulate some/the most - useful methods for a SQLite3 database object.

A Database is opened when a instance is created and close 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

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
namedatabase name.
If name is ":memory:" than the database will be an in memory database.
If name has a size of 0 than the database will be private on disk database.
Otherwise name will be interpreted as a file.
openFlagsif no flags are given, the defaults are SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE.
See also
https://www.sqlite.org/c3ref/open.html
Exceptions
sl3::SQLite3Errorif 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 std::string &  sql)

Execute one or more SQL statements.

Exceptions
sl3::SQLite3Errorin case of a problem.
Parameters
sqlSQL Statements

◆ execute() [2/4]

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

Execute one or more SQL statements.

Overload for const char to avoid a copy for larg command like create database scripts which are often static char*

Exceptions
sl3::SQLite3Errorin case of a problem.
Parameters
sqlSQL Statements

◆ execute() [3/4]

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

Execute one SQL statements and apply a SqlQueryHandler.

Exceptions
sl3::SQLite3Errorin case of a problem.
Parameters
sqlSQL Statements
cbRowCallback to handle query result

◆ execute() [4/4]

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

Execute one SQL statements and apply a QueryCallback.

Exceptions
sl3::SQLite3Errorin case of a problem.
Parameters
sqlSQL Statements
cbCallback to handle query result

◆ getLastInsertRowid()

int64_t sl3::Database::getLastInsertRowid ( )

returns 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 number of row that have changed since database opening.

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

Returns
Count of changed rows

◆ prepare() [1/2]

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

create a SqlCommand instance.

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

Parameters
sqlSQL 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
sqlSQL statement
paramsparameters
Exceptions
sl3::ErrTypeMisMatchif 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::SQLite3Errorin case of a problem.
Parameters
sqlSQL 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 returns the result .

If Types are

Exceptions
sl3::SQLite3Errorin case of a problems.
sl3::ErrTypeMisMatchin case of incorrect types.
Parameters
sqlSQL Statements
typeswanted 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 form 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::SQLite3Errorin case of a problems.
Parameters
sqlSQL 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 form 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::ErrTypeMisMatchif return type differs from requested type
sl3::SQLite3Errorin case of a problems.
Parameters
sqlSQL statement
typeresult has to be of that Type
Returns
DbValue of the first available result.

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