libsq3
2007.10.18
|
Encapsulates a connection to an sqlite database. More...
#include <sq3.hpp>
Public Member Functions | |
sqlite3 * | handle () const |
The low-level handle to the sqlite db. More... | |
database () | |
Creates an unopened database. More... | |
void | take_handle (sqlite3 *dbh, std::string const &name="") |
dbh is assumed to be an opened, valid db handle. More... | |
sqlite3 * | take_handle () |
Transfers ownership of this->handle() to the caller. More... | |
database (std::string const &filename) | |
Opens/creates the given db file. More... | |
virtual | ~database () |
Closes this db. | |
bool | is_open () const |
Returns true if this db is opened. More... | |
std::string | name () const |
Returns the name of the db file. | |
std::string | errormsg () const |
Returns the last error message from sqlite, or an empty string if this object is not opened. More... | |
virtual int | open (char const *, long flags=0) |
Creates/opens the given db file. More... | |
int | open (std::string const &, long flags=0) |
Functionally identical to open(char const*,long). More... | |
int | close (bool force=false) |
"Closes" this db. More... | |
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. More... | |
int | setbusytimeout (int ms) |
See sqlite3_busy_timeout(). | |
int | execute (const std::string &sql) |
Functionally identical to execute(char const *). | |
int | execute (char const *sql) |
Executes a statement which is assumed to have a single step and a void result. More... | |
int | execute (std::string const &sql, int &tgt) |
Executes a statement which is assumed to have a single result step and an integer result. More... | |
int | execute (char const *sql, int &tgt) |
See execute( std::string, int & );. | |
int | execute (char const *sql, int64_t &tgt) |
See execute( std::string, int & );. | |
int | execute (std::string const &sql, int64_t &tgt) |
See execute( std::string, int & );. | |
int | execute (char const *sql, double &tgt) |
See execute( std::string, int & );. | |
int | execute (std::string const &sql, double &tgt) |
See execute( std::string, int & );. | |
int | execute (char const *sql, std::string &tgt) |
See execute( std::string, int & );. | |
int | execute (std::string const &sql, std::string &tgt) |
See execute( std::string, int & );. | |
int | execute (char const *sql, sqlite3_text_char_t const **tgt, int &len) |
See execute( std::string, int & );. More... | |
int | execute (std::string const &sql, sqlite3_text_char_t const **tgt, int &len) |
See execute( char const *, sqlite3_text_char_t const **, int & ). More... | |
int | execute (std::string const &sql, void const **tgt, int &sz) |
See execute( char const *, sqlite3_text_char_t **, int & ). More... | |
int | execute (char const *sql, void const **tgt, int &sz) |
See execute( char const *, sqlite3_text_char_t **, int & ). More... | |
int | execute (std::string const &sql, sqlite3_callback callback, void *data, std::string &errmsg) |
Executes the given query, calling the given callback function for each row of the result set. More... | |
int | execute (char const *sql, sqlite3_callback callback, void *data, std::string &errmsg) |
Identical to the execute(std::string,sqlite3_callback,void*,std::string&). | |
int | execute (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(). | |
int | execute (char 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(). | |
int | pragma (char const *code) |
This is a convenience wrapper for execute( "pragma ..." ). More... | |
int | vacuum () |
Convenience wrapper around execute("vacuum"). More... | |
virtual int | clear () |
Looks through sqlite_master for a list of views, triggers, and tables, and drops them all (in that order). More... | |
Protected Member Functions | |
virtual int | on_open () |
This function is called when open() succeeds. More... | |
Friends | |
class | statement |
Encapsulates a connection to an sqlite database.
This type is virtual/subclassable so that clients can add initialization routines to all of their databases, such as adding sqlite-builtin functions and collating sequences. Simply do such initializations in your subclass ctors.
A note on the lack of proper constness for much of this API... Potentially, in the face of triggers, multiple threads, and whatnot, it is not generically possible to 100% ensure that any given SQL statement does not modify the database in at least some way. To reflect this underlying state of flux, "it was decided" (it really was) that very little, if any, of the members of this class would be const. Only those which could 100% guaranty proper constness.
Notes about copying:
Copying a db object is actually shallow copying. All copies of this type will refer to the same underlying (sqlite3*) db handle until/unless:
sq3::database::database | ( | ) |
Creates an unopened database.
Use open() to open a file or take_handle() to transfer an existing db handle to this object.
|
explicit |
Opens/creates the given db file.
Use is_open() to see if the opening worked.
Subclasses should not call this from a ctor initialization list because this function may eventually call on_open(), which is virtual, but the subclass part of the class may not be in place to catch that virtual call. So subclasses should initialize with the no-arg parent class ctor and should then call open(filename) themselves.
Definition at line 549 of file sq3.cpp.
References open().
int sq3::database::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.
|
virtual |
Looks through sqlite_master for a list of views, triggers, and tables, and drops them all (in that order).
Subclasses are welcomed to reimplement it to do less destructive cleansing, such as just dropping data from a certain table.
Returns SQLITE_OK on success.
If you need to free up the newly-freed space, be sure to call vacuum(), or else the file size may not actually shrink.
Also remember that any code which is expecting data to be in this database will not work after this function is done!
Reimplemented in sq3::log_db, and sq3::settings_db.
Definition at line 827 of file sq3.cpp.
References sq3::statement::bind(), execute(), sq3::cursor::get(), sq3::statement::get_cursor(), is_open(), name(), and sq3::rc_is_okay().
int sq3::database::close | ( | bool | force = false | ) |
"Closes" this db.
That actually means that it queues it to be closed when the last database object which is using that db handle closes or goes out of scope.
The force parameter changes the handling of those sqlite3_close():
If force is false, this function always returns SQLITE_OK unless this object is already closed, in which case SQLITE_ERROR is returned but can almost certainly be safely ignored. Unfortunately, due to the asynchronous nature of this operation, we can't return the value from the actual sqlite3_close() call (if any) when force is set to false.
If force is true then the internal reference counting is anulled and the db handle is closed immediately. This affects all copies of this object, so use with care (but use if you must). In this case, the value of sqlite3_close() is returned, but the the exact state of the underlying database handle is ambiguously defined in the sqlite3 docs. So... if that happens then the underlying db handle is assumed to be invalid, since the "test*.c" files which come with sqlite3 seem to treat it as such.
Definition at line 663 of file sq3.cpp.
Referenced by open(), take_handle(), and ~database().
std::string sq3::database::errormsg | ( | ) | const |
int sq3::database::execute | ( | char const * | sql | ) |
Executes a statement which is assumed to have a single step and a void result.
Returned result is that of an underlying call to sqlite3_step(), which means that SQLITE_DONE or SQLITE_ROW evaluate to success.
Definition at line 703 of file sq3.cpp.
References sq3::statement::execute().
int sq3::database::execute | ( | std::string const & | sql, |
int & | tgt | ||
) |
Executes a statement which is assumed to have a single result step and an integer result.
On success, tgt will be set to the query's value. Typically one of SQLITE_ROW or SQLITE_DONE are returned on success.
Definition at line 713 of file sq3.cpp.
References sq3::statement::execute().
int sq3::database::execute | ( | char const * | sql, |
sqlite3_text_char_t const ** | tgt, | ||
int & | len | ||
) |
See execute( std::string, int & );.
sql is executed and the string result is written to tgt and the length of the result string (in bytes) is written to len. The text bytes are owned by sqlite and will likely become invalid on the next db cursor operation, so copy them if you need them.
Returns the result of stepping through a result set, which is typically one of SQLITE_ROW or SQLITE_DONE.
Definition at line 748 of file sq3.cpp.
References sq3::statement::execute().
int sq3::database::execute | ( | std::string const & | sql, |
sqlite3_text_char_t const ** | tgt, | ||
int & | len | ||
) |
See execute( char const *, sqlite3_text_char_t const **, int & ).
This function is identical.
Definition at line 753 of file sq3.cpp.
References sq3::statement::execute().
int sq3::database::execute | ( | std::string const & | sql, |
void const ** | tgt, | ||
int & | sz | ||
) |
See execute( char const *, sqlite3_text_char_t **, int & ).
This function is identical except that tgt is a void pointer.
Definition at line 764 of file sq3.cpp.
References sq3::statement::execute().
int sq3::database::execute | ( | char const * | sql, |
void const ** | tgt, | ||
int & | sz | ||
) |
See execute( char const *, sqlite3_text_char_t **, int & ).
This function is identical except that tgt is a void pointer.
Definition at line 760 of file sq3.cpp.
References sq3::statement::execute().
int sq3::database::execute | ( | std::string const & | sql, |
sqlite3_callback | callback, | ||
void * | data, | ||
std::string & | errmsg | ||
) |
Executes the given query, calling the given callback function for each row of the result set.
The data pointer is passed on as-is to the callback. Any error string is written to errmsg.
Return value is that of an underlying sqlite3_exec() call.
Definition at line 769 of file sq3.cpp.
References execute().
sqlite3 * sq3::database::handle | ( | ) | const |
The low-level handle to the sqlite db.
NEVER close this handle. It is permissible to use it to run queries, add functions to the db, etc.
This object retains ownership of the returned handle.
Definition at line 540 of file sq3.cpp.
Referenced by sq3::statement::prepare().
bool sq3::database::is_open | ( | ) | const |
Returns true if this db is opened.
Does not detect errors such as opening a non-db file.
Definition at line 563 of file sq3.cpp.
Referenced by clear(), sq3::log_db::log(), sq3::log_db::on_open(), sq3::log_db::show_last(), and sq3::log_db::trim().
|
protectedvirtual |
This function is called when open() succeeds.
The default implementation does nothing and always returns SQLITE_OK, but subclasses may wish to do something here. If this function returns any value other than SQLITE_OK then this->close() is called before open() returns.
Reimplemented in sq3::log_db.
Definition at line 632 of file sq3.cpp.
Referenced by open().
|
virtual |
Creates/opens the given db file.
The flags parameter is only used if this code is compiled against sqlite3 >= 3.5.1, and can theoretically take any values defined in the SQLITE_OPEN_xxx family of macros. The sqlite3 documentation only describes the use of SQLITE_OPEN_READONLY, SQLITE_OPEN_READWRITE, and SQLITE_OPEN_CREATE, thus other values may nor may not work. If (0==flags) then (SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE) is assumed. See sqlite3_open_v2() for the exact semantics.
On success it returns SQLITE_OK, or some other value on error.
Calling open() will implicitly call close() on any existing connection. If that close() fails then this open() will also fail. If the open() succeeds, it does NOT affect other (shallow) copies of this object: they will still refer to the older db handle.
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.
Windows users beware: according to the sqlite3 documentation, the db name MUST be in UTF8 format, regardless of the current codepage used by Windows, and it is the caller's responsibility to perform any conversion, if needed.
Internal notes:
If the underlying sqlite3_open() succeeds, the protected member on_open() in called. If it returns a value other than SQLITE_OK then this->close() is called and the value returned from on_open() is returned from this function.
Subclasses which override this function 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. If on_open() fails then this->close() should be called to free up the resources and mark this object as unopened.
The flags argument was added 20071018, suggested by Joaquim Campos Salles (Joaquim.Salles at br.unisys.com).
Definition at line 591 of file sq3.cpp.
References close(), and on_open().
Referenced by database(), sq3::log_db::log_db(), open(), and sq3::settings_db::settings_db().
int sq3::database::open | ( | std::string const & | dbn, |
long | flags = 0 |
||
) |
Functionally identical to open(char const*,long).
This function calls that one, so subclasses wishing to change open()'s behaviour need only reimplement that one.
Definition at line 627 of file sq3.cpp.
References open().
int sq3::database::pragma | ( | char const * | code | ) |
This is a convenience wrapper for execute( "pragma ..." ).
Return value is that of the underlying execute() call.
code should be a pragma key or key/value string, such as "temp_store=MEMORY" or "synchronous=OFF"
Definition at line 814 of file sq3.cpp.
References execute().
Referenced by sq3::log_db::on_open().
void sq3::database::take_handle | ( | sqlite3 * | dbh, |
std::string const & | name = "" |
||
) |
dbh is assumed to be an opened, valid db handle.
This function transfers ownership of dbh to this object. Specifically, dbh will be closed when the last database with the same db handle goes out of scope or is closed. The name is simply informative, and may or may not be the same actually used for opening dbh.
Note that this function does not call the protected this->on_open() because, quite frankly, i'm not yet sure if it really makes sense to do so.
sqlite3 * sq3::database::take_handle | ( | ) |
int sq3::database::vacuum | ( | ) |
Convenience wrapper around execute("vacuum").
The vacuum operation attempts to free up any unused disk space in the database.
Definition at line 822 of file sq3.cpp.
References execute().
Referenced by sq3::log_db::trim().