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:

[legend]
Collaboration diagram for mysqlpp::Query:

[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:

- query.h
- query.cpp