libsqlite3x 2007.10.18
|
Represents a connection to an sqlite3 database. More...
#include <sqlite3x.hpp>
Public Member Functions | |
sqlite3 * | db () const |
Returns a handle to the underlying sqlite3 database. | |
sqlite3_connection () | |
Default ctor. | |
sqlite3_connection (std::string const &dbname) | |
Opens a database with the given name. | |
sqlite3_connection (sqlite3 *dbh) | |
See take(sqlite3*). | |
virtual | ~sqlite3_connection () |
Calls this->close() if close() has not already been called. | |
std::string | name () const |
Returns this object's name. | |
virtual void | open (char const *) |
Creates/opens the given db, throwing on error. | |
void | open (std::string const &dbname) |
Functionally the same as open( char const *). | |
void | take (sqlite3 *dbh) |
Transfers control of dbh to this object and makes this object point at dbh. | |
sqlite3 * | take () throw () |
Transfers ownership of the returned handle to the caller. | |
void | close () |
Closes this database. | |
int64_t | insertid () |
Returns the rowid of the most recently inserted row on this db. | |
int | changes () |
Returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement. | |
void | setbusytimeout (int ms) |
See sqlite3_busy_timeout(). | |
void | executenonquery (const std::string &sql) |
Executes a command which is assumed to have a single step and a void result. | |
void | executenonquery (char const *sql) |
Overloaded to avoid an internal copy of sql. | |
int | executeint (const std::string &sql) |
Executes the query, which is expected to have an integer field as the first result field. | |
int | executeint (char const *sql) |
Overloaded to avoid an internal copy of sql. | |
int64_t | executeint64 (const std::string &sql) |
Executes the query, which is expected to have a (int64_t) field as the first result field. | |
int64_t | executeint64 (char const *sql) |
Overloaded to avoid an internal copy of sql. | |
double | executedouble (const std::string &sql) |
Executes the query, which is expected to have a double field as the first result field. | |
double | executedouble (char const *sql) |
Overloaded to avoid an internal copy of sql. | |
std::string | executestring (const std::string &sql) |
Executes the query, which is expected to have a string or blob field as the first result field. | |
std::string | executeblob (const std::string &sql) |
Executes the query, which is expected to have a string or blob field as the first result field. | |
int | executecallback (std::string const &sql, sqlite3_callback callback, void *data, std::string &errmsg) |
Executes the given SQL code, calling callback for each row of the data set. | |
int | executecallback (std::string const &sql, sqlite3_callback callback, void *data=0) |
Convenience overload which has a default data value of 0 and ignores any error string passed back by sqlite3_exec(). | |
std::string | errormsg () const |
Returns the equivalent of sqlite3_errmsg(), or an empty string if that function returns null. | |
Protected Member Functions | |
virtual void | on_open () |
This function is called when open() succeeds. | |
Friends | |
class | sqlite3_command |
Represents a connection to an sqlite3 database.
About the only reason to subclass this type would be to do customizations to the underlying sqlite3 db handle upon construction of each object, e.g. to add custom sqlite functions or load custom modules.
Definition at line 148 of file sqlite3x.hpp.
sqlite3x::sqlite3_connection::sqlite3_connection | ( | ) |
Default ctor.
DB is unusable until open() is called.
Definition at line 39 of file sqlite3x_connection.cpp.
|
explicit |
Opens a database with the given name.
Throws if this->open(dbname) fails.
Definition at line 41 of file sqlite3x_connection.cpp.
References open().
sqlite3x::sqlite3_connection::sqlite3_connection | ( | sqlite3 * | dbh | ) |
See take(sqlite3*).
This ctor is identical except that it throws if passed a null pointer.
Definition at line 51 of file sqlite3x_connection.cpp.
References take().
|
virtual |
int sqlite3x::sqlite3_connection::changes | ( | ) |
Returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement.
SQLite implements the command "DELETE FROM table" without a WHERE clause by dropping and recreating the table. To get an accurate count of the number of rows deleted, use "DELETE FROM table WHERE 1" instead.
Definition at line 183 of file sqlite3x_connection.cpp.
void sqlite3x::sqlite3_connection::close | ( | ) |
Closes this database.
If the db is not opened, this is a no-op.
Definition at line 169 of file sqlite3x_connection.cpp.
Referenced by sqlite3x::settings_db::close(), open(), take(), and ~sqlite3_connection().
sqlite3 * sqlite3x::sqlite3_connection::db | ( | ) | const |
Returns a handle to the underlying sqlite3 database.
Friend classes should NEVER call sqlite3_close() on this handle. Doing so will result in undefined behaviour later on (when this class is used or destructs).
This function is only public so that clients can do things like register new sqlite3 functions with the database.
Definition at line 104 of file sqlite3x_connection.cpp.
Referenced by open(), and sqlite3x::sqlite3_command::prepare().
std::string sqlite3x::sqlite3_connection::errormsg | ( | ) | const |
Returns the equivalent of sqlite3_errmsg(), or an empty string if that function returns null.
Reminder: the sqlite3 docs say that sqlite3_errmsg() always returns a non-empty string, even if the string is "not an error" (no joke).
Definition at line 114 of file sqlite3x_connection.cpp.
Referenced by sqlite3x::sqlite3_cursor::reset().
std::string sqlite3x::sqlite3_connection::executeblob | ( | const std::string & | sql | ) |
Executes the query, which is expected to have a string or blob field as the first result field.
Note that numeric results can be returned using this function, but will come back as a string (lexically cast).
Definition at line 285 of file sqlite3x_connection.cpp.
References sqlite3x::sqlite3_command::executeblob().
int sqlite3x::sqlite3_connection::executecallback | ( | std::string const & | sql, |
sqlite3_callback | callback, | ||
void * | data, | ||
std::string & | errmsg ) |
Executes the given SQL code, calling callback for each row of the data set.
The data pointer is passed on as-is to the callback, and may be 0. If execution generates an error message it is stored in errmsg.
If this function intercepts an exception (thrown from the callback) then it propagates that exception back to the caller. If it catches no exception, it returns the result code, with zero being success and non-zero being failure.
See sqlite3_exec() for more details.
Definition at line 297 of file sqlite3x_connection.cpp.
Referenced by executecallback().
int sqlite3x::sqlite3_connection::executecallback | ( | std::string const & | sql, |
sqlite3_callback | callback, | ||
void * | data = 0 ) |
Convenience overload which has a default data value of 0 and ignores any error string passed back by sqlite3_exec().
Definition at line 326 of file sqlite3x_connection.cpp.
References executecallback().
double sqlite3x::sqlite3_connection::executedouble | ( | char const * | sql | ) |
Overloaded to avoid an internal copy of sql.
sql MUST be non-NULL and null-terminated.
Definition at line 243 of file sqlite3x_connection.cpp.
References sqlite3x::sqlite3_command::executedouble().
double sqlite3x::sqlite3_connection::executedouble | ( | const std::string & | sql | ) |
Executes the query, which is expected to have a double field as the first result field.
Definition at line 248 of file sqlite3x_connection.cpp.
References executedouble().
Referenced by executedouble().
int sqlite3x::sqlite3_connection::executeint | ( | char const * | sql | ) |
Overloaded to avoid an internal copy of sql.
sql MUST be non-NULL and null-terminated.
Definition at line 212 of file sqlite3x_connection.cpp.
References sqlite3x::sqlite3_command::executeint().
int sqlite3x::sqlite3_connection::executeint | ( | const std::string & | sql | ) |
Executes the query, which is expected to have an integer field as the first result field.
Definition at line 216 of file sqlite3x_connection.cpp.
References executeint().
Referenced by executeint(), and sqlite3x::table_generator::table_generator().
int64_t sqlite3x::sqlite3_connection::executeint64 | ( | char const * | sql | ) |
Overloaded to avoid an internal copy of sql.
sql MUST be non-NULL and null-terminated.
Definition at line 227 of file sqlite3x_connection.cpp.
References sqlite3x::sqlite3_command::executeint64().
int64_t sqlite3x::sqlite3_connection::executeint64 | ( | const std::string & | sql | ) |
Executes the query, which is expected to have a (int64_t) field as the first result field.
Definition at line 232 of file sqlite3x_connection.cpp.
References executeint64().
Referenced by executeint64().
void sqlite3x::sqlite3_connection::executenonquery | ( | char const * | sql | ) |
Overloaded to avoid an internal copy of sql.
sql MUST be non-NULL and null-terminated.
Definition at line 200 of file sqlite3x_connection.cpp.
References sqlite3x::sqlite3_command::executenonquery().
void sqlite3x::sqlite3_connection::executenonquery | ( | const std::string & | sql | ) |
Executes a command which is assumed to have a single step and a void result.
Definition at line 196 of file sqlite3x_connection.cpp.
References executenonquery().
Referenced by sqlite3x::sqlite3_transaction::begin(), sqlite3x::settings_db::clear(), sqlite3x::settings_db::clear(), sqlite3x::sqlite3_transaction::commit(), sqlite3x::table_generator::create(), executenonquery(), and sqlite3x::sqlite3_transaction::rollback().
std::string sqlite3x::sqlite3_connection::executestring | ( | const std::string & | sql | ) |
Executes the query, which is expected to have a string or blob field as the first result field.
Note that numeric results can be returned using this function, but will come back as a string (lexically cast).
Definition at line 259 of file sqlite3x_connection.cpp.
References sqlite3x::sqlite3_command::executestring().
int64_t sqlite3x::sqlite3_connection::insertid | ( | ) |
Returns the rowid of the most recently inserted row on this db.
Definition at line 178 of file sqlite3x_connection.cpp.
std::string sqlite3x::sqlite3_connection::name | ( | ) | const |
Returns this object's name.
It is only valid if the (char const *) ctor or open(char const *) was used with a non-null name, otherwise it is an empty string.
Definition at line 109 of file sqlite3x_connection.cpp.
|
protectedvirtual |
This function is called when open() succeeds.
Subclasses which wish to do custom db initialization or sanity checks may do them here.
Definition at line 120 of file sqlite3x_connection.cpp.
|
virtual |
Creates/opens the given db, throwing on error.
Remember that sqlite3 supports the name ":memory:" as a pseudo-name for an in-memory database.
On success it returns, else it throws.
Note that sqlite3 supports the special db name ":memory:" to represent an in-memory database. Such databases cannot be saved directly to disk and are lost when this object closes the db.
Internal notes:
Once an sqlite3_open() succeeds, the protected member this->on_open() in called. That member should throw on error.
Subclasses which override this and do not want to call the base implementation should call on_open() when done to allow subclasses to initialize the database if they like.
Definition at line 124 of file sqlite3x_connection.cpp.
References close(), db(), and on_open().
Referenced by open(), and sqlite3_connection().
void sqlite3x::sqlite3_connection::open | ( | std::string const & | dbname | ) |
Functionally the same as open( char const *).
Definition at line 147 of file sqlite3x_connection.cpp.
References open().
void sqlite3x::sqlite3_connection::setbusytimeout | ( | int | ms | ) |
See sqlite3_busy_timeout().
Definition at line 189 of file sqlite3x_connection.cpp.
sqlite3 * sqlite3x::sqlite3_connection::take | ( | ) | ||||
throw | ( | ) |
Transfers ownership of the returned handle to the caller.
This object is then considered closed. NULL is returned if this object is closed.
Definition at line 97 of file sqlite3x_connection.cpp.
Referenced by sqlite3_connection().
void sqlite3x::sqlite3_connection::take | ( | sqlite3 * | dbh | ) |
Transfers control of dbh to this object and makes this object point at dbh.
dbh is assumed to be a valid, opened sqlite3 db handle.
If this->db() == dbh then this function does nothing.
If this object had an opened db handle then it is closed before dbh is taken. Closing may throw, but this function takes ownership of dbh regardless of whether it throws or not.
If dbh is null, the effect is identical to calling close().
This function triggers the protected on_open() function if dbh is not null.
Definition at line 74 of file sqlite3x_connection.cpp.
|
friend |
Definition at line 155 of file sqlite3x.hpp.