Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members   File Members  

mysqlpp::Query Class Reference

A class for building and executing SQL queries. More...

#include <query.h>

Inheritance diagram for mysqlpp::Query:

Inheritance graph
[legend]
Collaboration diagram for mysqlpp::Query:

Collaboration graph
[legend]
List of all members.

Public Methods

 Query (Connection *c, bool te=false)
 Create a new query object attached to a connection.

 Query (const Query &q)
 Create a new query object as a copy of another.

std::string error ()
 Get the last error message that happened on the connection we're bound to.

bool success ()
 Returns true if the query executed successfully.

std::string preview ()
 Return the query string currently in the buffer.

std::string preview (parms &p)
 Return the query string currently in the buffer.

bool exec (const std::string &str)
 Execute a query.

ResNSel execute ()
 Execute a query.

ResUse use ()
 Execute a query that can return a result set.

Result store ()
 Execute a query that can return a result set.

template<class Sequence> void storein_sequence (Sequence &con, query_reset r=RESET_QUERY)
 Execute a query, storing the result set in an STL sequence container.

template<class Set> void storein_set (Set &con, query_reset r=RESET_QUERY)
 Execute a query, storing the result set in an STL associative container.

template<class Container> void storein (Container &con, query_reset r=RESET_QUERY)
 Execute a query, and store the entire result set in an STL container.

template<class T> Query & update (const T &o, const T &n)
 Replace an existing row's data with new data.

template<class T> Query & insert (const T &v)
 Insert a new row.

template<class Iter> Query & insert (Iter first, Iter last)
 Insert multiple new rows.

template<class T> Query & replace (const T &v)
 Insert new row unless there is an existing row that matches on a unique index, in which case we replace it.


Detailed Description

A class for building and executing SQL queries.

This class is derived from SQLQuery. It adds to that a tie between the query object and a MySQL++ Connection object, so that the query can be sent to the MySQL server we're connected to.


Constructor & Destructor Documentation

mysqlpp::Query::Query Connection   c,
bool    te = false
[inline]
 

Create a new query object attached to a connection.

This is the constructor used by mysqlpp::Connection::query().

Parameters:
c  connection the finished query should be sent out on
te  if true, throw exceptions on errors


Member Function Documentation

bool mysqlpp::Query::exec const std::string &    str
 

Execute a query.

Same as execute(), except that it only returns a flag indicating whether the query succeeded or not. It is basically a thin wrapper around the C API function mysql_query().

Parameters:
str  the query to execute
Returns:
true if query was executed successfully
See also:
execute(), store(), storein(), and use()

ResNSel mysqlpp::Query::execute   [inline]
 

Execute a query.

Use this function if you don't expect the server to return a result set. For instance, a DELETE query. The returned ResNSel object contains status information from the server, such as whether the query succeeded, and if so how many rows were affected.

There are a number of overloaded versions of this function. The one without parameters simply executes a query that you have built up in the object in some way. (For instance, via the insert() method, or by using the object's stream interface.) You can also pass the function an std::string containing a SQL query, a SQLQueryParms object, or as many as 12 SQLStrings. The latter two (or is it 13?) overloads are for filling out template queries.

Returns:
ResNSel status information about the query
See also:
exec(), store(), storein(), and use()

template<class Iter>
Query& mysqlpp::Query::insert Iter    first,
Iter    last
[inline]
 

Insert multiple new rows.

Builds an INSERT SQL query using items from a range within an STL container. Insert the entire contents of the container by using the begin() and end() iterators of the container as parameters to this function.

Parameters:
first  iterator pointing to first element in range to insert
last  iterator pointing to one past the last element to insert
See also:
replace(), update()

Reimplemented from mysqlpp::SQLQuery.

template<class T>
Query& mysqlpp::Query::insert const T &    v [inline]
 

Insert a new row.

This function builds an INSERT SQL query. One uses it with MySQL++'s Specialized SQL Structures mechanism.

Parameters:
v  new row
See also:
replace(), update()

Reimplemented from mysqlpp::SQLQuery.

template<class T>
Query& mysqlpp::Query::replace const T &    v [inline]
 

Insert new row unless there is an existing row that matches on a unique index, in which case we replace it.

This function builds a REPLACE SQL query. One uses it with MySQL++'s Specialized SQL Structures mechanism.

Parameters:
v  new row
See also:
insert(), update()

Reimplemented from mysqlpp::SQLQuery.

Result mysqlpp::Query::store   [inline]
 

Execute a query that can return a result set.

This function returns the entire result set immediately. This is useful if you actually need all of the records at once, but if not, consider using use() instead, which returns the results one at a time. As a result of this difference, use() doesn't need to allocate as much memory as store().

You must use store(), storein() or use() for SELECT, SHOW, DESCRIBE and EXPLAIN queries. You can use these functions with other query types, but since they don't return a result set, exec() and execute() are more efficient.

The name of this method comes from the MySQL C API function it is implemented in terms of, mysql_store_result().

This function has the same set of overloads as execute().

Returns:
Result object containing entire result set
See also:
exec(), execute(), storein(), and use()

template<class Container>
void mysqlpp::Query::storein Container &    con,
query_reset    r = RESET_QUERY
[inline]
 

Execute a query, and store the entire result set in an STL container.

This is a set of specialized template functions that call either storein_sequence() or storein_set(), depending on the type of container you pass it. It understands std::vector, deque, list, slist (a common C++ library extension), set, and multiset.

Like the functions it wraps, this is actually an overloaded set of functions. See the other functions' documentation for details.

Use this function if you think you might someday switch your program from using a set-associative container to a sequence container for storing result sets, or vice versa.

See exec(), execute(), store(), and use() for alternative query execution mechanisms.

template<class Sequence>
void mysqlpp::Query::storein_sequence Sequence &    con,
query_reset    r = RESET_QUERY
[inline]
 

Execute a query, storing the result set in an STL sequence container.

This function works much like store() from the caller's perspective, because it returns the entire result set at once. It's actually implemented in terms of use(), however, so that memory for the result set doesn't need to be allocated twice.

There are many overloads for this function, pretty much the same as for execute(), except that there is a Container parameter at the front of the list. So, you can pass a container and a query string, or a container and template query parameters.

Parameters:
con  any STL sequence container, such as std::vector
r  whether the query automatically resets after being used
See also:
exec(), execute(), store(), and use()

template<class Set>
void mysqlpp::Query::storein_set Set   con,
query_reset    r = RESET_QUERY
[inline]
 

Execute a query, storing the result set in an STL associative container.

The same thing as storein_sequence(), except that it's used with associative STL containers, such as std::set. Other than that detail, that method's comments apply equally well to this one.

template<class T>
Query& mysqlpp::Query::update const T &    o,
const T &    n
[inline]
 

Replace an existing row's data with new data.

This function builds an UPDATE SQL query using the new row data for the SET clause, and the old row data for the WHERE clause. One uses it with MySQL++'s Specialized SQL Structures mechanism.

Parameters:
o  old row
n  new row
See also:
insert(), replace()

Reimplemented from mysqlpp::SQLQuery.

ResUse mysqlpp::Query::use   [inline]
 

Execute a query that can return a result set.

Unlike store(), this function does not return the result set directly. Instead, it returns an object that can walk through the result records one by one. This is superior to store() when there are a large number of results; store() would have to allocate a large block of memory to hold all those records, which could cause problems.

A potential downside of this method is that MySQL database resources are tied up until the result set is completely consumed. Do your best to walk through the result set as expeditiously as possible.

The name of this method comes from the MySQL C API function that initiates the retrieval process, mysql_use_result(). This method is implemented in terms of that function.

This function has the same set of overloads as execute().

Returns:
ResUse object that can walk through result set serially
See also:
exec(), execute(), store() and storein()


The documentation for this class was generated from the following files:
Generated on Thu May 26 09:40:35 2005 for MySQL++ by doxygen1.2.18