Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class 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 Member Functions

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

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

Queryoperator= (const Query &rhs)
 Assign another query's state to this object.

std::string error ()
 Get the last error message that was set.

bool success ()
 Returns true if the last operation succeeded.

void parse ()
 Treat the contents of the query string as a template query.

void reset ()
 Reset the query object so that it can be reused.

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

std::string preview (const SQLString &arg0)
 Return the query string currently in the buffer with template query parameter substitution.

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

std::string str ()
 Get built query as a null-terminated C++ string.

std::string str (const SQLString &arg0)
 Get built query as a null-terminated C++ string with template query parameter substitution.

std::string str (query_reset r)
 Get built query as a null-terminated C++ string.

std::string str (SQLQueryParms &p)
 Get built query as a null-terminated C++ string.

std::string str (SQLQueryParms &p, query_reset r)
 Get built query as a null-terminated C++ string.

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

ResNSel execute ()
 Execute built-up query.

ResNSel execute (const SQLString &str)
 Execute query in a C++ string, or substitute string into a template query and execute it.

ResNSel execute (const char *str)
 Execute query in a C string.

ResNSel execute (const char *str, size_t len)
 Execute query in a known-length string of characters. This can include null characters.

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

ResUse use (const SQLString &str)
 Execute query in a C++ string.

ResUse use (const char *str)
 Execute query in a C string.

ResUse use (const char *str, size_t len)
 Execute query in a known-length C string.

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

Result store (const SQLString &str)
 Execute query in a C++ string.

Result store (const char *str)
 Execute query in a C string.

Result store (const char *str, size_t len)
 Execute query in a known-length C string.

template<typename Function> Function for_each (const SQLString &query, Function fn)
 Execute a query, and call a functor for each returned row.

template<typename Function> Function for_each (Function fn)
 Execute the query, and call a functor for each returned row.

template<class SSQLS, typename Function> Function for_each (const SSQLS &ssqls, Function fn)
 Run a functor for every row in a table.

template<class Sequence, typename Function> Function store_if (Sequence &seq, const SQLString &query, Function fn)
 Execute a query, conditionally storing each row in a container.

template<class Sequence, class SSQLS, typename Function> Function store_if (Sequence &seq, const SSQLS &ssqls, Function fn)
 Pulls every row in a table, conditionally storing each one in a container.

template<class Sequence, typename Function> Function store_if (Sequence &seq, Function fn)
 Execute the query, conditionally storing each row in a container.

Result store_next ()
 Return next result set, when processing a multi-query.

bool more_results ()
 Return whether more results are waiting for a multi-query or stored procedure response.

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> void storein (std::vector< T > &con, const char *s)
 Specialization of storein_sequence() for std::vector.

template<class T> void storein (std::deque< T > &con, const char *s)
 Specialization of storein_sequence() for std::deque.

template<class T> void storein (std::list< T > &con, const char *s)
 Specialization of storein_sequence() for std::list.

template<class T> void storein (std::set< T > &con, const char *s)
 Specialization of storein_set() for std::set.

template<class T> void storein (std::multiset< T > &con, const char *s)
 Specialization of storein_set() for std::multiset.

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

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

template<class Iter> Queryinsert (Iter first, Iter last)
 Insert multiple new rows.

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

 operator bool ()
 Return true if the last query was successful.

bool operator! ()
 Return true if the last query failed.


Public Attributes

SQLQueryParms def
 The default template parameters.


Friends

class SQLQueryParms

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.

One does not generally create Query objects directly. Instead, call mysqlpp::Connection::query() to get one tied to that connection.

There are several ways to build and execute SQL queries with this class.

The way most like other database libraries is to pass a SQL statement to one of the exec*(), store*(), or use() methods taking a C or C++ string. The query is executed immediately, and any results returned.

For more complicated queries, you can use Query's stream interface. You simply build up a query using the Query instance as you would any other C++ stream object. When the query string is complete, you call the overloaded version of exec*(), store*() or use() that takes no parameters, which executes the built query and returns any results.

If you are using the library's Specialized SQL Structures feature, Query has several special functions for generating common SQL queries from those structures. For instance, it offers the insert() method, which builds an INSERT query to add the contents of the SSQLS to the database. As with the stream interface, these methods only build the query string; call one of the parameterless methods mentioned previously to actually execute the query.

Finally, you can build "template queries". This is something like C's printf() function, in that you insert a specially-formatted query string into the object which contains placeholders for data. You call the parse() method to tell the Query object that the query string contains placeholders. Once that's done, you can call any of the many overloaded methods that take a number of SQLStrings (up to 25 by default) or any type that can be converted to SQLString, and those parameters will be inserted into the placeholders. When you call one of the parameterless functions the execute the query, the final query string is assembled and sent to the server.

See the user manual for more details about these options.


Constructor & Destructor Documentation

mysqlpp::Query::Query Connection c,
bool  te = true
 

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

mysqlpp::Query::Query const Query q  ) 
 

Create a new query object as a copy of another.

This is not a traditional copy ctor! Its only purpose is to make it possible to assign the return of Connection::query() to an empty Query object. In particular, the stream buffer and template query stuff will be empty in the copy, regardless of what values they have in the original.


Member Function Documentation

std::string mysqlpp::Query::error  ) 
 

Get the last error message that was set.

This class has an internal error message string, but if it isn't set, we return the last error message that happened on the connection we're bound to instead.

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_real_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 const char *  str,
size_t  len
 

Execute query in a known-length string of characters. This can include null characters.

Executes the query immediately, and returns the results.

ResNSel mysqlpp::Query::execute const char *  str  ) 
 

Execute query in a C string.

Executes the query immediately, and returns the results.

ResNSel mysqlpp::Query::execute const SQLString str  ) 
 

Execute query in a C++ string, or substitute string into a template query and execute it.

Parameters:
str If the object represents a compiled template query, substitutes this string in for the first parameter. Otherwise, takes the string as a complete SQL query and executes it.

ResNSel mysqlpp::Query::execute  )  [inline]
 

Execute built-up query.

Use one of the execute() overloads 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.

This overloaded version of execute() simply executes the 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.)

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

template<class SSQLS, typename Function>
Function mysqlpp::Query::for_each const SSQLS &  ssqls,
Function  fn
[inline]
 

Run a functor for every row in a table.

Just like for_each(Function), except that it builds a "select * from TABLE" query using the SQL table name from the SSQLS instance you pass.

Parameters:
ssqls the SSQLS instance to get a table name from
fn the functor called for each row
Returns:
a copy of the passed functor

template<typename Function>
Function mysqlpp::Query::for_each Function  fn  )  [inline]
 

Execute the query, and call a functor for each returned row.

Just like for_each(const SQLString&, Function), but it uses the query string held by the Query object already

Parameters:
fn the functor called for each row
Returns:
a copy of the passed functor

template<typename Function>
Function mysqlpp::Query::for_each const SQLString query,
Function  fn
[inline]
 

Execute a query, and call a functor for each returned row.

This method wraps a use() query, calling the given functor for every returned row. It is analogous to STL's for_each() algorithm, but instead of iterating over some range within a container, it iterates over a result set produced by a query.

Parameters:
query the query string
fn the functor called for each row
Returns:
a copy of the passed functor

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()

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()

bool mysqlpp::Query::more_results  ) 
 

Return whether more results are waiting for a multi-query or stored procedure response.

If this function returns true, you must call store_next() to fetch the next result set before you can execute more queries.

Wraps mysql_more_results() in the MySQL C API. That function only exists in MySQL v4.1 and higher. Therefore, this function always returns false when built against older API libraries.

Returns:
true if another result set exists

Query & mysqlpp::Query::operator= const Query rhs  ) 
 

Assign another query's state to this object.

The same caveats apply to this operator as apply to the copy ctor.

void mysqlpp::Query::parse  ) 
 

Treat the contents of the query string as a template query.

This method sets up the internal structures used by all of the other members that accept template query parameters. See the "Template Queries" chapter in the user manual for more information.

std::string mysqlpp::Query::preview const SQLString arg0  )  [inline]
 

Return the query string currently in the buffer with template query parameter substitution.

Parameters:
arg0 the value to substitute for the first template query parameter

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()

void mysqlpp::Query::reset  ) 
 

Reset the query object so that it can be reused.

This erases the query string and the contents of the parameterized query element list.

Result mysqlpp::Query::store const char *  str,
size_t  len
 

Execute query in a known-length C string.

Executes the query immediately, and returns an object that contains the entire result set. This is less memory-efficient than use(), but it lets you have random access to the results.

Result mysqlpp::Query::store const char *  str  ) 
 

Execute query in a C string.

Executes the query immediately, and returns an object that contains the entire result set. This is less memory-efficient than use(), but it lets you have random access to the results.

Result mysqlpp::Query::store const SQLString str  ) 
 

Execute query in a C++ string.

Executes the query immediately, and returns an object that contains the entire result set. This is less memory-efficient than use(), but it lets you have random access to the results.

Result mysqlpp::Query::store  )  [inline]
 

Execute a query that can return a result set.

Use one of the store() overloads to execute a query and retrieve the entire result set into memory. This is useful if you actually need all of the records at once, but if not, consider using one of the use() methods instead, which returns the results one at a time, so they don't 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 Sequence, typename Function>
Function mysqlpp::Query::store_if Sequence &  seq,
Function  fn
[inline]
 

Execute the query, conditionally storing each row in a container.

Just like store_if(Sequence&, const SQLString&, Function), but it uses the query string held by the Query object already

Parameters:
seq the destination container; needs a push_back() method
fn the functor called for each row
Returns:
a copy of the passed functor

template<class Sequence, class SSQLS, typename Function>
Function mysqlpp::Query::store_if Sequence &  seq,
const SSQLS &  ssqls,
Function  fn
[inline]
 

Pulls every row in a table, conditionally storing each one in a container.

Just like store_if(Sequence&, const SQLString&, Function), but it uses the SSQLS instance to construct a "select * from TABLE" query, using the table name field in the SSQLS.

Parameters:
seq the destination container; needs a push_back() method
ssqls the SSQLS instance to get a table name from
fn the functor called for each row
Returns:
a copy of the passed functor

template<class Sequence, typename Function>
Function mysqlpp::Query::store_if Sequence &  seq,
const SQLString query,
Function  fn
[inline]
 

Execute a query, conditionally storing each row in a container.

This method wraps a use() query, calling the given functor for every returned row, and storing the results in the given sequence container if the functor returns true.

This is analogous to the STL copy_if() algorithm, except that the source rows come from a database query instead of another container. (copy_if() isn't a standard STL algorithm, but only due to an oversight by the standardization committee.) This fact may help you to remember the order of the parameters: the container is the destination, the query is the source, and the functor is the predicate; it's just like an STL algorithm.

Parameters:
seq the destination container; needs a push_back() method
query the query string
fn the functor called for each row
Returns:
a copy of the passed functor

Result mysqlpp::Query::store_next  ) 
 

Return next result set, when processing a multi-query.

There are two cases where you'd use this function instead of the regular store() functions.

First, when handling the result of executing multiple queries at once. (See this page in the MySQL documentation for details.)

Second, when calling a stored procedure, MySQL can return the result as a set of results.

In either case, you must consume all results before making another MySQL query, even if you don't care about the remaining results or result sets.

As the MySQL documentation points out, you must set the MYSQL_OPTION_MULTI_STATEMENTS_ON flag on the connection in order to use this feature. See Connection::set_option().

Multi-queries only exist in MySQL v4.1 and higher. Therefore, this function just wraps store() when built against older API libraries.

Returns:
Result object containing the next result set.

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.

std::string mysqlpp::Query::str SQLQueryParms p,
query_reset  r
 

Get built query as a null-terminated C++ string.

Parameters:
p template query parameters to use, overriding the ones this object holds, if any
r if equal to RESET_QUERY, query object is cleared after this call

std::string mysqlpp::Query::str SQLQueryParms p  ) 
 

Get built query as a null-terminated C++ string.

Parameters:
p template query parameters to use, overriding the ones this object holds, if any

std::string mysqlpp::Query::str query_reset  r  )  [inline]
 

Get built query as a null-terminated C++ string.

Parameters:
r if equal to RESET_QUERY, query object is cleared after this call

std::string mysqlpp::Query::str const SQLString arg0  )  [inline]
 

Get built query as a null-terminated C++ string with template query parameter substitution.

Parameters:
arg0 the value to substitute for the first template query parameter

bool mysqlpp::Query::success  ) 
 

Returns true if the last operation succeeded.

Returns true if the last query succeeded, and the associated Connection object's success() method also returns true. If either object is unhappy, this method returns false.

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()

ResUse mysqlpp::Query::use const char *  str,
size_t  len
 

Execute query in a known-length C string.

Executes the query immediately, and returns an object that lets you walk through the result set one row at a time, in sequence. This is more memory-efficient than store().

ResUse mysqlpp::Query::use const char *  str  ) 
 

Execute query in a C string.

Executes the query immediately, and returns an object that lets you walk through the result set one row at a time, in sequence. This is more memory-efficient than store().

ResUse mysqlpp::Query::use const SQLString str  ) 
 

Execute query in a C++ string.

Executes the query immediately, and returns an object that lets you walk through the result set one row at a time, in sequence. This is more memory-efficient than store().

ResUse mysqlpp::Query::use  )  [inline]
 

Execute a query that can return a result set.

Use one of the use() overloads if memory efficiency is important. They return an object that can walk through the result records one by one, without fetching the entire result set from the server. 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()


Member Data Documentation

SQLQueryParms mysqlpp::Query::def
 

The default template parameters.

Used for filling in parameterized queries.


The documentation for this class was generated from the following files:
Generated on Wed Jul 11 15:35:29 2007 for MySQL++ by doxygen 1.3.5