libsl3
1.1.31001
The convenient C++11 interface for SQLite 3.x
|
libsl3 allows efficient communication with SQLite3 databases in a natural way, which is SQL.
The library does not try to be a ORM and does also not introduce some SQL like C++ syntax for communication with a sqlite database.
Read from and write to a database is supported via SQL and prepared commands, aka stored procedures.
The SQLite duck typing concept is fully supported but there is also a way to add type checking to the communication with a database.
A database is represented via sl3::Database.
A database can execute SQL strings to read or write data.
A sl3::Command is a compiled SQL statement which can contain parameters.
Parameters are sl3::DbValues, a sl3::Container of sl3::DbValue instances.
sl3::DbValues can also be used to receive data from a database.
Requesting data from a database will return a sl3::Dataset with rows of sl3::DbValues where each field is a sl3::DbValue.
An other, and fully customizable way to receive data from a database is covered in the RowCallback and Callback functions
section.
since the ostream operator for sl3::DbValue is overloaded, this will print
sl3::Database encapsulates a sqlite database.
It can be directly used, but it has also a virtual destructor and can be used as a base class.
The types in libsl3 are those which are available in
datatypes as sqlite does.
since a database value can also be NULL there is a type for it.
There is one additional sl3::Type.
In sqlite a clomun can hold different types and libsl3 supports this concept.
See sl3::DbValue for more information.
This class can be used to read from and write to a sl3::Database.
A sl3::DbValues can hold different types. It can be defined if any type is allowed for an instance or only a certain one.
There are two sl3::Type properties. One defines the type rule, the other the type value.
Both properties are used to validate reads and writes at runtime.
If a value is set or read that is omitted by the type property an sl3::ErrTypeMisMatch exception is thrown.
Setting a value can be done via
sl3::DbValue::setNull can be used to set a value to Null.
There are getters for each type
There are 2 version for this function, with and without a default value as argument.
The version without default value will throw an sl3::ErrNullValueAccess exception is case that sl3::DbValue::isNull is true for the instance.
The version with a default value as argument will return the passed argument in case that the current sl3::DbValue::isNull.
If a type getter is used for a wrong the storage type a sl3::ErrTypeMisMatch exception is thrown.
Additional, there is a sl3::DbValue::get version which will never throw.
This function always requires a default value which has to be one of the 4 value types.
If the type is incorrect or the value is Null the given default value will be returned.
This example will print
A sl3::Command is a compiled SQL statement which can contain parameters.
sl3::Database::prepare does create a command.
If a command has parameters the types are specified at creation.
A command can return data or not, depending on the SQL that is used.
A insert or update statement does not return data, while a select statement does.
A command has therefor 2 ways to run it.
In the A first example overview example all sl3::Command parameters have been of type sl3::Typ::Variant since nothing was specified.
But it can be ensured that certain types are used.
The output of this program will be:
It is not a problem to insert different types into a column, sqlite supports this and so does libsl3
But is might be unwanted and can therefore be turned off.
A sl3::Dataset is a generic way to receive data from a sl3::Database.
It is return by a sl3::Command::select or sl3::Database::select
If there are different types in a column, a sl3::Dataset will automatically provide correct sl3::DbValue object.
running this program will print
Of course it might be unwanted to get different types for one column into a sl3::Dataset.
This can be ensured by passing the allowed sl3::Types to the sl3::Database::select call.
If the wanted types are not these which are in the table, an sl3::TypeMisMatch exception is thrown.
this code will throw an exception, as expected and print
A custom way to handle query results is to usea
a sl3::RowCallback or the sl3::Commad::Callback function.
They can be passed to the sl3::Database::execute and sl3::Commad::execute function.
The callback will be called with a sl3::Columns representing the current row for each row in the query result.
The callback returns if it wants proceed to be called or not.
In a callback the sl3::Columns class give access to the current row.
There are several methods to query the type, size and get the values.
Running this program, the output will be