## Description |
|
|
This is general class that hold connection with database. It provides C++ interface for `dbi_conn` -- [connection infrastructure](http://libdbi.sourceforge.net/docs/programmers-guide/reference-conn.html) of libdbi. |
|
## Session Management |
|
### Constructor |
|
session(); |
session(std::string const &backend); |
|
Create connection object and optionaly load database driver (see, [dbi\_conn\_new](http://libdbi.sourceforge.net/docs/programmers-guide/reference-conn.html#DBI-CONN-NEW)) |
|
This object is non-copyable. |
|
### Configuration Member Functions |
|
void driver(std::string const &backend); |
void param(std::string const &par,std::string const &val); |
void param(std::string const &par,int); |
|
`driver(...)` function provides an ability to load driver if it is not specified in construction. |
|
`param(...)` overloaded function allows to setup different |
backend parameters. They represent [dbi\_conn\_set\_option](http://libdbi.sourceforge.net/docs/programmers-guide/reference-conn.html#DBI-CONN-SET-OPTION) and [dbi\_conn\_set\_option\_numeric](http://libdbi.sourceforge.net/docs/programmers-guide/reference-conn.html#DBI-CONN-SET-OPTION-NUMERIC) . You should refer to [libdbi-drivers documentation](http://libdbi-drivers.sourceforge.net/docs.html) for specific parameters. |
|
### Connection |
|
void connect(); |
void reconnect(); |
void close(); |
|
These member functions are used for connecting, reconnecting and disconnecting configured backend to database. |
|
For example: |
|
session sql; |
sql.driver("sqlite3"); |
sql.param("dbname","test.db"); |
sql.param("sqlite3_dbdir","./"); |
sql.connect(); |
|
## Preparing a query |
|
void query(std::string const &query); |
session &operator<<(std::string const &query); |
|
Function `query` is used for assignment of the next query for execution. Operator `<<` is syntactic sugar for calling `query()`. |
|
sql<<"SELECT name,value FROM options"; |
|
|
After we had defined the query we can bind additional parameters, if any. |
|
bind(X const &value,bool isnull=false); |
|
|
Where X is one of: `std::string`, `int`, `unsigned`, `long long`, `unsigned long long`, `double`, `std::tm` and `dbixx::null`. The parameters are marked as "?" in the queries, and they are replaced with appropriate values. |
|
sql.query("INSERT INTO t VALUES(?,?,?)" |
sql.bind(10); |
sql.bind("Your name is 'Smith'"); |
sql.bind(null()); |
|
Creates following query: |
|
INSERT INTO t VALUES(10,'Your name is \'Smith\'',NULL) |
|
Parameter `std::string` is always automatically escaped |
and it is safe to bind any data to it. |
|
There is a syntactic sugar available as well: |
|
template<typename T> |
session &operator,(T v); |
template<typename T> |
session &operator,(std::pair<T,bool> p); |
|
So the above query can be set up as following: |
|
sql<< "INSERT INTO t VALUES(?,?,?)", |
10,"Your name is 'Smith'",null(); |
|
### Notes: |
|
1. You should never use something like: |
|
sql<< "INSERT INTO t VALUES('?')",message; |
|
"?" symbol inside quotation marks '' would be interpreted |
as "?" and not placeholder for value. Beginning and end quotes are automatically added for std::strings. |
2. You should never create queries like this: |
|
sql<< "INSERT INTO t VALUES('"+message+"')"; |
|
Such query is not escaped and can lead to SQL Injections. |
|
|
