Detailed Description

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 in either the form of a C or C++ string to one of the exec*(), store*(), or use() methods. The query is executed immediately, and any results returned.

For more complicated queries, it's often more convenient to build up the query string over several C++ statements using Query's stream interface. It works like any other C++ stream (std::cout, std::ostringstream, etc.) in that you can just insert things into the stream, building the query up piece by piece. When the query string is complete, you call the overloaded version of exec*(), store*(), or use() 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. Having done that, you call one of the the many exec*(), store*(), or use() overloads that take SQLTypeAdapter objects. There are 25 of each by default, differing only in the number of STA objects they take. (See lib/querydef.pl if you need to change the limit, or examples/tquery2.cpp for a way around it that doesn't require changing the library.) Only the version taking a single STA object is documented below, as to document all of them would just be repetitive. For each Query method that takes a single STA object, there's a good chance there's a set of undocumented overloads that take more of them for the purpose of filling out a template query.

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.

character buffer to hold escaped version; must point to at least (length * 2 + 1) bytes

original

pointer to the character buffer to escape

length

number of characters to escape

Return values

number

of characters placed in escaped

DBDriver provides two versions of this method and Query::escape_string() calls the appropriate one based on whether or not a database connection is available. If the connection is available, it can call the DBDriver::escape_string() method. If there is no database connection available (normally only in testing), then DBDriver provides a static version of the function that doesn't use a database connection.

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 SimpleResult 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.)

This method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

if this object is set up as a template query, this is the value to substitute for the first template query parameter; else, it is the SQL query string to execute

Because SQLTypeAdapter can be initialized from either a C string or a C++ string, this overload accepts query strings in either form. Beware, SQLTypeAdapter also accepts many other data types (this is its raisond'etre), so it will let you write code that compiles but results in bogus SQL queries.

To support template queries, there many more overloads of this type (25 total, by default; see lib/querydef.pl), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

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.

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.

Get ID generated for an AUTO_INCREMENT column in the previous INSERT query.

Return values

0

if the previous query did not generate an ID. Use the SQL function LAST_INSERT_ID() if you need the last ID generated by any query, not just the previous one. This applies to stored procedure calls because this function returns the ID generated by the last query, which was a CALL statement, and CALL doesn't generate IDs. You need to use LAST_INSERT_ID() to get the ID in this case.

Insert multiple new rows, or replace existing ones if there are existing rows that match on key fields.

Builds a REPLACE 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.

As of v3.0, Query objects auto-reset upon query execution unless you've set it up for making template queries. (It can't auto-reset in that situation, because it would forget the template info.) Therefore, the only time you must call this is if you have a Query object set up for making template queries, then want to build queries using one of the other methods. (Static strings, SSQLS, or the stream interface.)

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 method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

Execute a query that can return rows, returning all of the rows in a random-access container.

Parameters

str

if this object is set up as a template query, this is the value to substitute for the first template query parameter; else, it is the SQL query string to execute

Because SQLTypeAdapter can be initialized from either a C string or a C++ string, this overload accepts query strings in either form. Beware, SQLTypeAdapter also accepts many other data types (this is its raisond'etre), so it will let you write code that compiles but results in bogus SQL queries.

To support template queries, there many more overloads of this type (25 total, by default; see lib/querydef.pl), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

Execute a query that can return rows, returning all of the rows in a random-access container.

This overload is for situations where you have the query in a C string and have its length already. If you want to execute a query in a null-terminated C string or have the query string in some other form, you probably want to call store(const SQLTypeAdapter&) instead. SQLTypeAdapter converts from plain C strings and other useful data types implicitly.

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.

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.

This method is not intended to be used directly. It is part of the call chain in processing calls to one of the many storein() overloads that take a container and one or more SQLTypeAdapter parameters.

template<class Sequence >

void mysqlpp::Query::storein_sequence

(

Sequence &

con

)

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.

Executes a query, storing the result rows in an STL sequence container.

Parameters

con

the container to store the results in

s

if Query is set up as a template query, this is the value to substitute for the first template query parameter; else, the SQL query string

There many more overloads of this type (25 total, by default; see lib/querydef.pl), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

Execute template query using given parameters, storing the results in a sequence type container.

This method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

Executes a query, storing the result rows in an STL set-associative container.

Parameters

con

the container to store the results in

s

if Query is set up as a template query, this is the value to substitute for the first template query parameter; else, the SQL query string

There many more overloads of this type (25 total, by default; see lib/querydef.pl), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

Execute template query using given parameters, storing the results in a set type container.

This method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

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

Parameters

arg0

the value to substitute for the first template query parameter; because SQLTypeAdapter implicitly converts from many different data types, this method is very flexible in what it accepts as a parameter. You shouldn't have to use the SQLTypeAdapter data type directly in your code.

There many more overloads of this type (25 total, by default; see lib/querydef.pl), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

Execute a query that can return rows, with access to the rows in sequence.

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.

Execute a template query that can return rows, with access to the rows in sequence.

This method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

Execute a query that can return rows, with access to the rows in sequence.

Parameters

str

if this object is set up as a template query, this is the value to substitute for the first template query parameter; else, it is the SQL query string to execute

Because SQLTypeAdapter can be initialized from either a C string or a C++ string, this overload accepts query strings in either form. Beware, SQLTypeAdapter also accepts many other data types (this is its raisond'etre), so it will let you write code that compiles but results in bogus SQL queries.

To support template queries, there many more overloads of this type (25 total, by default; see lib/querydef.pl), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

Execute a query that can return rows, with access to the rows in sequence.

This overload is for situations where you have the query in a C string and have its length already. If you want to execute a query in a null-terminated C string or have the query string in some other form, you probably want to call use(const SQLTypeAdapter&) instead. SQLTypeAdapter converts from plain C strings and other useful data types implicitly.