POCO Data User Guide
Author: Applied Informatics Software Engineering GmbH and Contributors

# POCO Data Library

# POCO Data User Guide

## First Steps

POCO Data is POCO's database abstraction layer which allows users to easily send/retrieve data to/from various databases. Currently supported database connectors are SQLite, MySQL and ODBC. Framework is opened for extension, so additional native connectors (Oracle, PostgreSQL, ...) can be added. The intent behind the Poco::Data framework is to produce the integration between C++ and relational databses in a simple and natural way.

The following complete example shows how to use POCO Data:

    #include "Poco/Data/Session.h"
    #include "Poco/Data/SQLite/Connector.h"
    #include <vector>
    #include <iostream>

    using namespace Poco::Data::Keywords;
    using Poco::Data::Session;
    using Poco::Data::Statement;

    struct Person
    {
        std::string name;
        std::string address;
        int         age;
    };

    int main(int argc, char** argv)
    {
        // register SQLite connector
        Poco::Data::SQLite::Connector::registerConnector();

        // create a session
        Session session("SQLite", "sample.db");

        // drop sample table, if it exists
        session << "DROP TABLE IF EXISTS Person", now;

        // (re)create table
        session << "CREATE TABLE Person (Name VARCHAR(30), Address VARCHAR, Age INTEGER(3))", now;

        // insert some rows
        Person person =
        {
            "Bart Simpson",
            "Springfield",
            12
        };

        Statement insert(session);
        insert << "INSERT INTO Person VALUES(?, ?, ?)",
            use(person.name),
            use(person.address),
            use(person.age);

        insert.execute();

        person.name    = "Lisa Simpson";
        person.address = "Springfield";
        person.age     = 10;

        insert.execute();

        // a simple query
        Statement select(session);
        select << "SELECT Name, Address, Age FROM Person",
            into(person.name),
            into(person.address),
            into(person.age),
            range(0, 1); //  iterate over result set one row at a time

        while (!select.done())
        {
            select.execute();
            std::cout << person.name << " " << person.address << " " << person.age << std::endl;
        }

        return 0;
    }

The above example is pretty much self explanatory.

The `using namespace Poco::Data` is for convenience only but highly recommended for good readable code. While `ses << "SELECT COUNT(*) FROM PERSON", Poco::Data::Keywords::into(count), Poco::Data::Keywords::now;` is valid, the aesthetic aspect of the code is improved by eliminating the need for full namespace qualification; this document uses convention introduced in the example above.

The remainder of this tutorial is split up into the following parts:

- Sessions
- Inserting and Retrieving Data
- Statements
- STL Containers
- Tuples
- Limits, Ranges and Steps
- `RecordSets`, Iterators and Rows
- Complex data types: how to map C++ objects to a database table
- Conclusion

## Creating Sessions

Sessions are created via the Session constructor:

    Session session("SQLite", "sample.db");

The first parameter contains the type of the Session one wants to create. Currently, supported backends are "SQLite", "ODBC" and "MySQL". The second parameter contains the connection string.

In the case of SQLite, the path of the database file is sufficient as connection string.

For ODBC, the connection string may be a simple "DSN=MyDSNName" when a DSN is configured or a complete ODBC driver-specific connection string defining all the necessary connection parameters (for details, consult your ODBC driver documentation).

For MySQL, the connection string is a semicolon-delimited list of name-value pairs specifying various parameters like host, port, user, password, database, compression and automatic reconnect. Example: `"host=localhost;port=3306;db=mydb;user=alice;password=s3cr3t;compress=true;auto-reconnect=true"`

## Inserting and Retrieving Data

### Single Data Sets

Inserting data works by `using` the content of other variables. Assume we have a table that stores only forenames:

    ForeName (Name VARCHAR(30))

If we want to insert one single forename we could simply write:

    std::string aName("Peter");
    session << "INSERT INTO FORENAME VALUES(" << aName << ")", now;

However, a better solution is to use placeholders and connect each placeholder via a `use` expression with a variable that will provide the value during execution. Placeholders, depending on your database are recognized by having either a colon(`:`) in front of the name or simply by a question mark (`?`) as a placeholder. While having the placeholders marked with a colon followed by a human-readable name is very convenient due to readability, not all SQL dialects support this and universally accepted standard placeholder is (`?`). Consult your database SQL documentation to determine the valid placeholder syntax.

Rewriting the above code now simply gives:

    std::string aName("Peter");
    ses << "INSERT INTO FORENAME VALUES(?)", use(aName), now;

In this example the `use` expression matches the placeholder with the `Peter` value. Note that apart from the nicer syntax, the real benefits of placeholders — which are performance and protection against SQL injection attacks — don't show here. Check the `Statements` section to find out more.

Retrieving data from the Database works similar. The `into` expression matches the returned database values to C++ objects, it also allows to provide a default value in case null data is returned from the database:

    std::string aName;
    ses << "SELECT NAME FROM FORENAME", into(aName), now;
    ses << "SELECT NAME FROM FORENAME", into(aName, 0, "default"), now;

You'll note the integer zero argument in the second into() call. The reason for that is that Poco::Data supports multiple result sets for those databases/drivers that have such capbility and we have to indicate the resultset we are referring to. Attempting to create sufficient overloads of `into()` creates more trouble than what it's worth and null values can effectively be dealt with through use of either Poco::Nullable wrapper (see Handling Null Entries later in this document) or Poco::Dynamic::Var, which will be set as empty for null values when used as query output target.

It is also possible to combine into and use expressions:

    std::string aName;
    std::string match("Peter")
    ses << "SELECT NAME FROM FORENAME WHERE NAME=?", into(aName), use(match), now;
    poco_assert (aName == match);

Typically, tables will not be so trivial, i.e. they will have more than one column which allows for more than one into/use.

Lets assume we have a Person table that contains an age, a first and a last name:

    std::string firstName("Peter";
    std::string lastName("Junior");
    int age = 0;
    ses << INSERT INTO PERSON VALUES (?, ?, ?)", use(firstName), use(lastName), use(age), now;
    ses << "SELECT (firstname, lastname, age) FROM Person", into(firstName), into(lastName), into(age), now;

Most important here is the order of the into and use expressions. The first placeholder is matched by the first `use`, the 2nd by the 2nd `use` etc.

The same is true for the `into` statement. We select `firstname` as the first column of the result set, thus `into(firstName)` must be the first into clause.

### Handling NULL entries

A common case with databases are optional data fields that can contain NULL. To accomodate for NULL, use the Poco::Nullable template:

    std::string firstName("Peter";
    Poco::Nullable<std::string> lastName("Junior");
    Poco::Nullable<int> age = 0;
    ses << INSERT INTO PERSON VALUES (?, ?, ?)", use(firstName), use(lastName), use(age), now;
    ses << "SELECT (firstname, lastname, age) FROM Person", into(firstName), into(lastName), into(age), now;
    // now you can check if age was null:
    if (!lastName.isNull()) { ... }

The above used Poco::Nullable is a lightweight template class, wrapping any type for the purpose of allowing it to have null value.

If the returned value was null, age.isNull() will return true. Whether empty string is null or not is more of a philosophical question (a topic for discussion in some other time and place); for the purpose of this document, suffice it to say that different databases handle it differently and Poco::Data provides a way to tweak it to user's needs through folowing `Session` features:

- emptyStringIsNull
- forceEmptyString

So, if your database does not treat empty strings as null but you want Poco::Data to emulate such behavior, modify the session like this:

    ses.setFeature("emptyStringIsNull", true);

On the other side, if your database treats empty strings as nulls but you do not want it to, you'll alter the session feature:

    ses.setFeature("forceEmptyString", true);

Obviously, the above features are mutually exclusive; an attempt to se them both to true will result in an exception being thrown by the Data framework.

### Multiple Data Sets

Batches of statements are supported. They return multiple sets of data, so into() call needs and additional parameter to determine which data set it belongs to:

    typedef Tuple<std::string, std::string, std::string, int> Person;
    std::vector<Person> people;
    Person pHomer, pLisa;
    int aHomer(42), aLisa(10), aBart(0);

    session << "SELECT * FROM Person WHERE Age = ?; "
        "SELECT Age FROM Person WHERE FirstName = 'Bart'; "
        "SELECT * FROM Person WHERE Age = ?",
        into(pHomer, 0), use(aHomer),
        into(aBart, 1),
        into(pLisa, 2), use(aLisa),
        now;

#### Note

Batches of statements can be used, provided, of course, that the target driver and database engine properly support them. Additionally, the exact SQL syntax may vary for different databases. Stored procedures (see below) returning multiple data sets are handled in the same way.

### Now

And now, finally, a word about the `now` keyword. The simple description is: it is a manipulator. As it's name implies, it forces the immediate execution of the statement. If `now` is not present, the statement must be executed separately in order for anything interesting to happen.

More on statements and manipulators in the chapters that follow.

### Stored Procedures And Functions Support

Most of the modern database systems support stored procedures and/or functions. Does Poco::Data provide any support there? You bet. While the specifics on what exactly is possible (e.g. the data types passed in and out, automatic or manual data binding, binding direction, etc.) is ultimately database dependent, POCO Data does it's best to provide reasonable access to such functionality through `in`, `out` and `io` binding functions. As their names imply, these functions are performing parameters binding tho pass in or receive from the stored procedures, or both. The code is worth thousand words, so here's an Oracle ODBC example:

    session << "CREATE OR REPLACE "
        "FUNCTION storedFunction(param1 IN OUT NUMBER, param2 IN OUT NUMBER) RETURN NUMBER IS "
        " temp NUMBER := param1; "
        " BEGIN param1 := param2; param2 := temp; RETURN(param1+param2); "
        " END storedFunction;" , now;

    int i = 1, j = 2, result = 0;
    session << "{? = call storedFunction(?, ?)}", out(result), io(i), io(j), now; // i = 2, j = 1, result = 3

Stored procedures are allowed to return data sets (a.k.a. cursors):

    typedef Tuple<std::string, std::string, std::string, int> Person;
    std::vector<Person> people;
    int age = 13;
    session << "CREATE OR REPLACE "
        "FUNCTION storedCursorFunction(ageLimit IN NUMBER) RETURN SYS_REFCURSOR IS "
        " ret SYS_REFCURSOR; "
        "BEGIN "
        " OPEN ret FOR "
        " SELECT *  FROM Person  WHERE Age < ageLimit; "
        " RETURN ret; "
        "END storedCursorFunction;" , now;

    session << "{call storedCursorFunction(?)}", in(age), into(people), now;

The code shown above works with Oracle databases.

### A Word of Warning

As you may have noticed, in the above example, C++ code works very closely with SQL statements. And, as you know, your C++ compiler has no clue what SQL is (other than a string of characters). So it is your responsibility to make sure your SQL statements have the proper structure that corresponds to the number and type of the supplied functions.

## Statements

We often mentioned the term Statement in the previous section, but with the exception of the initial example, we have only worked with database session objects so far. Or at least, that's what we made you believe.

In reality, you have already worked with Statements. Lets take a look at the method signature of the << operator at Session:

    template <typename T>
    Statement Session::operator << (const T&amp; t);

Simply ignore the template stuff in front, you won't need it. The only thing that counts here is that the operator << creates a `Statement` internally and returns it.

What happened in the previous examples is that the returned Statement was never assigned to a variable but simply passed on to the `now` part which executed the statement. Afterwards the statement was destroyed.

Let's take one of the previous examples and change it so that we assign the statement:

    std::string aName("Peter");
    Statement stmt = ( ses << "INSERT INTO FORENAME VALUES(?)", use(aName) );

Note that the brackets around the right part of the assignment are mandatory, otherwise the compiler will complain.

What did we achieve by assigning the statement to a variable? Two things: Control when to `execute` and the possibility to create a RecordSet (described in its own chapter below).

Here's how we control when to actually execute the statement:

    std::string aName("Peter");
    Statement stmt = ( ses << "INSERT INTO FORENAME VALUES(?)", use(aName) );
    stmt.execute();
    poco_assert (stmt.done());

By calling `execute` we asserted that our query was executed and that the value was inserted. The check to `stmt.done()` simply guarantees that the statement was fully completed.

### Prepared Statements

A prepared statement is created by omitting the "now" clause.

    Statement stmt = ( ses << "INSERT INTO FORENAME VALUES(?)", use(aName) );

The advantage of a prepared statement is performance. Assume the following loop:

    std::string aName;
    Statement stmt = ( ses << "INSERT INTO FORENAME VALUES(?)", use(aName) );
    for (int i = 0; i < 100; ++i)
    {
        aName.append("x");
        stmt.execute();
    }

Instead of creating and parsing the Statement 100 times, we only do this once and then use the placeholder in combination with the `use` clause to insert 100 different values into the database.

Still, this isn't the best way to insert a collection of values into a database. Poco::Data is STL-aware and will cooperate with STL containers to extract multiple rows from the database. More on that in the chapter titled "STL Containers".

### Asynchronous Execution

So far, the statements were executing synchronously. In other words, regardless of whether the `execute()` method was invoked indirectly through `now` manipulator or through direct method call, it did not return control to the caller until the requested execution was completed. This behavior can be changed, so that `execute()` returns immediately, while, in fact, it keeps on running in a separate thread. This paragraph explains how this behavior can be achieved as well as warns about the dangers associated with asynchronous execution.

Asynchronous execution can be invoked on any statement, through the direct call to executeAsync() method. This method returns a `const` reference to `Statement::Result`. This reference can be used at a later time to ensure completion of the background execution and, for those statements that return rows, find out how many rows were retrieved.

Here's the code:

    Statement stmt = (ses << "SELECT (firstname, lastname, age) FROM Person", into(firstName), into(lastName), into(age));
    Statement::Result result = stmt.executeAsync();
    // ... do something else
    Statement::ResultType rows = result.wait();

The above code did not do anything "under the hood" to change the statement's nature. If we call `execute()` afterwards, it will execute synchronously as usual. There is, however, a way (or two) to turn the statement into asynchronous mode permanently.

First, there is an explicit `setAync()` call:

    Statement stmt = (ses << "SELECT (age) FROM Person", into(age));
    stmt.setAsync(true); // make stmt asynchronous
    stmt.execute(); // executes asynchronously
    // ... do something else
    Statement::ResultType rows = stmt.wait(); // synchronize and retrieve the number of rows

And, then, there is also the `async` manipulator that has the same effect as the `setAync(true)` code above:

    Statement stmt = (ses << "SELECT (age) FROM Person", into(age), async); // asynchronous statement
    stmt.execute(); // executes asynchronously
    // ... do something else
    Statement::ResultType rows = stmt.wait();

#### Note

In the first example, we have received `Result` from the statement, while in the second two, we did not assign the return value from `execute()`. The `Result` returned from `executeAsync()` is also known as `future` — a variable holding a result that will be known at some point in future. The reason for not keeping the `execute()` return value is because, for asynchronous statements, `execute()` always returns zero. This makes sense, because it does not know the number of returned rows (remember, asynchronous `execute()` call returns `immediately` and does not wait for the completion of the execution).

#### A Word of Warning

With power comes responsibility. When executing asynchronously, make sure to `synchronize` accordingly. When you fail to synchronize explicitly, you may encounter all kinds of funny things happening. Statement does internally try to protect you from harm, so the following code will usually throw `InvalidAccessException`:

    Statement stmt = (ses << "SELECT (age) FROM Person", into(age), async); // asynchronous statement
    Statement::Result result = stmt.execute(); // executes asynchronously
    stmt.execute(); // throws InvalidAccessException

We say "usually", because it may not happen every time, depending whether the first `execute()` call completed in the background prior to calling the second one. Therefore, to avoid unpleasant surprises, it is highly recommended to always call `wait()` on either the statement itself or the result (value returned from `executeAsync()`) prior to engaging into a next attempt to execute.

### Things NOT To Do

The `use` keyword expects as input a `reference` parameter, which is bound later during execution. Thus, one should never pass temporaries to `use()`:

    Statement stmt = (ses << "INSERT INTO PERSON VALUES (?, ?, ?)", use(getForename()), use(getSurname()), use(getAge())); //!!!
    // do something else
    stmt.execute(); // oops!

It is possible to use `bind()` instead of `use()`. The `bind()` call will always create a copy of the supplied argument. Also, it is possible to execute a statement returning data without supplying the storage and have the statement itself store the returned data for later retrieval through `RecordSet`. For details, see `RecordSet` chapter.

### Things TO Do

Constants, as well as naked variables (of POD and std::string types) are permitted in the comma-separated list passed to statement. The following example is valid:

    std::string fname = "Bart";
    std::string lname = "Simpson";
    int age = 42;
    Statement stmt = (ses << "INSERT INTO %s VALUES (?, ?, %d)", "PERSON", use(fname), use(lname), 12);
    stmt.execute();

Placeholders for values are very similar (but not identical) to standard printf family of functions. For details refer to `Poco::format()` documentation. Note: If you are alarmed by mention of `printf()`, a well-known source of many security problems in C and C++ code, do not worry. Poco::format() family of functions is `safe` (and, admittedly, slower than printf).

For cases where this type of formatting is used with queries containing the percent sign, use double percent ("%%"):

    Statement stmt = (ses << "SELECT * FROM %s WHERE Name LIKE 'Simp%%'", "Person");
    stmt.execute();

yields the following SQL statement string:

    SELECT * FROM Person WHERE Name LIKE 'Simp%'

## STL Containers

To handle many values at once, which is a very common scenario in database access, STL containers are used.

The framework supports the following container types out-of-the-box:

- deque: no requirements
- vector: no requirements
- list: no requirements
- set: the < operator must be supported by the contained datatype. Note that duplicate key/value pairs are ignored.
- multiset: the < operator must be supported by the contained datatype
- map: the () operator must be supported by the contained datatype and return the key of the object. Note that duplicate key/value pairs are ignored.
- multimap: the () operator must be supported by the contained datatype and return the key of the object

A "one-at-atime" bulk insert example via vector would be:

    std::string aName;
    std::vector<std::string> data;
    for (int i = 0; i < 100; ++i)
    {
        aName.append("x");
        data.push_back(aName);
    }
    ses << "INSERT INTO FORENAME VALUES(?)", use(data), now;

The same example would work with list, deque, set or multiset but not with map and multimap (std::string has no () operator).

Note that `use` requires a non-empty container!

Now reconsider the following example:

    std::string aName;
    ses << "SELECT NAME FROM FORENAME", into(aName), now;

Previously, it worked because the table contained only one single entry but now the database table contains at least 100 strings, yet we only offer storage space for one single result.

Thus, the above code will fail and throw an exception.

One possible way to handle this is:

    std::vector<std::string> names;
    ses << "SELECT NAME FROM FORENAME", into(names), now;

And again, instead of vector, one could use deque, list, set or multiset.

### Things NOT To Do

C++ containers in conjunction with stored procedures input parameters (i.e `in` and `io` functions) are not supported. Furthermore, there is one particular container which, due to its peculiar nature, can not be used in conjunction with `out` and `io` under any circumstances: `std::vector<bool>` . The details are beyond the scope of this manual. For those interested to learn more about it, there is an excellent explanation in S. Meyers book "Efective STL", Item 18 or Gotw #50, When Is a Container Not a Container]] paragraph.

## Tuples

Complex user-defined data types are supported through type handlers as described in one of the chapters below. However, in addition to STL containers, which are supported through binding/extraction there is another complex data type supported by POCO Data "out-of-the-box". The type is Poco::Tuple. The detailed description is beyond the scope of this manual, but suffice it to say here that this data structure allows for convenient and type-safe mix of different data types resulting in a perfect C++ match for the table row. Here's the code to clarify the point:

    typedef Poco::Tuple<std::string, std::string, int> Person;
    Person person("Bart Simpson", "Springfield", 12)
    session << "INSERT INTO Person VALUES(?, ?, ?)", use(person), now;

Automagically, POCO Data internally takes care of the data binding intricacies for you. Of course, as before, it is programmer's responsibility to make sure the Tuple data types correspond to the table column data types.

I can already see the reader wondering if it's possible to put tuples in a container and kill more than one bird with one stone. As usual, POCO Data will not disappoint you:

    typedef Poco::Tuple<std::string, std::string, int> Person;
    typedef std::vector<Person> People;
    People people;
    people.push_back(Person("Bart Simpson", "Springfield", 12));
    people.push_back(Person("Lisa Simpson", "Springfield", 10));
    session << "INSERT INTO Person VALUES(?, ?, ?)", use(people), now;

And thats it! There are multiple columns and multiple rows contained in a single variable and inserted in one shot. Needless to say, the reverse works as well:

    session << "SELECT Name, Address, Age FROM Person", into(people), now;

## Limits and Ranges

### Limit

Working with collections might be convenient to bulk process data but there is also the risk that large operations will block your application for a very long time. In addition, you might want to have better fine-grained control over your query, e.g. you only want to extract a subset of data until a condition is met.

To alleviate that problem, one can use the `limit` keyword.

Let's assume we are retrieving thousands of rows from a database to render the data to a GUI. To allow the user to stop fetching data any time (and to avoid having the user frantically click inside the GUI because it doesn't show anything for seconds), we have to partition this process:

    std::vector<std::string> names;
    ses << "SELECT NAME FROM FORENAME", into(names), limit(50), now;

The above example will retrieve up to 50 rows from the database (note that returning nothing is valid!) and append it to the names collection, i.e. the collection is not cleared!

If one wants to make sure that exactly 50 rows are returned one must set the second limit parameter (which per default is set to `false`) to `true`:

    std::vector<std::string> names;
    ses << "SELECT NAME FROM FORENAME", into(names), limit(50, true), now;

Iterating over a complete result collection is done via the Statement object until `statement.done()` returns true.

For the next example, we assume that our system knows about 101 forenames:

    std::vector<std::string> names;
    Statement stmt = (ses << "SELECT NAME FROM FORENAME", into(names), limit(50));
    stmt.execute(); //names.size() == 50
    poco_assert (!stmt.done());
    stmt.execute(); //names.size() == 100
    poco_assert (!stmt.done());
    stmt.execute(); //names.size() == 101
    poco_assert (stmt.done());

We previously stated that if no data is returned this is valid too. Thus, executing the following statement on an empty database table will work:

    std::string aName;
    ses << "SELECT NAME FROM FORENAME", into(aName), now;

To guarantee that at least one valid result row is returned use the `lowerLimit` clause:

    std::string aName;
    ses << "SELECT NAME FROM FORENAME", into(aName), lowerLimit(1), now;

If the table is now empty, an exception will be thrown. If the query succeeds, aName is guaranteed to be initialized. Note that `limit` is only the short name for `upperLimit`. To iterate over a result set step-by-step, e.g. one wants to avoid using a collection class, one would write

    std::string aName;
    Statement stmt = (ses << "SELECT NAME FROM FORENAME", into(aName), lowerLimit(1), upperLimit(1));
    while (!stmt.done()) stmt.execute();

### Range

For the lazy folks, there is the `range` command:

    std::string aName;
    Statement stmt = (ses << "SELECT NAME FROM FORENAME", into(aName), range(1,1));
    while (!stmt.done()) stmt.execute();

The third parameter to range is an optional boolean value which specifies if the upper limit is a hard limit, ie. if the amount of rows returned by the query must match exactly. Per default exact matching is off.

## Bulk

The `bulk` keyword allows to boost performance for the connectors that support column-wise operation and arrays of values and/or parameters (e.g. ODBC). Here's how to signal bulk insertion to the statement:

    std::vector<int> ints(100, 1);
    session << "INSERT INTO Test VALUES (?)", use(ints, bulk), now;

The above code will execute a "one-shot" insertion into the target table.

Selection in bulk mode looks like this:

    std::vector<int> ints;
    session << "SELECT * FROM Test", into(ints, bulk(100)), now;

Note that, when fetching data in bulk quantities, we must provide the size of data set we want to fetch, either explicitly as in the code above or implicitly, through size of the supplied container as in following example:

std::vector<int> ints(100, 1); session << "SELECT * FROM Test", into(ints, bulk), now;

For statements that generate their ow internal extraction storage (see RecordSet chapter below), bulk execution can be specified as follows:

    session << "SELECT * FROM Test", bulk(100), now;

### Usage Notes

When using bulk mode, execution limit is set internally. Mixing of `bulk` and `limit` keywords, although redundant, is allowed as long as they do not conflict in the value they specify.

Bulk operations are only supported for following STL containers:

- std::deque
- std::list
- std::vector, including std::vector<bool>, which is properly handled internally

For best results with `use()`, when passing POD types, it is recommended to use std::vector as it is passed directly as supplied by the user. For all the other scenarios (other containers as well as non-POD types), framework will create temporary storage.

Data types supported are:

- All POD types
- std::string
- Poco::Data::LOB (with BLOB and CLOB specializations)
- Poco::DateTime
- Poco::Data::Date
- Poco::Data::Time
- Poco::Dynamic::Var

### Important Considerations

Not all the connectors support `bulk` and some support it only to an extent, depending on the target system. Also, not all value types perform equally when used for bulk operations. To determine the optimal use in a given scenario, knowledge of the target system as well as some degree of experimentation is needed because different connectors and target systems shall differ in performance gains. In some scenarios, the gain is significant. For example, Oracle ODBC driver performs roughly 400-500 times faster when bulk-inserting a std::vector of 10,000 integers. However, when variable-sized entities, such as strings and BLOBs are brought into the picture, performance decreases drastically. So, all said, it is left to the end-user to make the best of this feature.

## RecordSets, Iterators and Rows

In all the examples so far the programmer had to supply the storage for data to be inserted or retrieved from a database.

It is usually desirable to avoid that and let the framework take care of it, something like this:

    session << "SELECT * FROM Person", now; // note the absence of target storage

No worries — that's what the RecordSet class does:

    Statement select(session); // we need a Statement for later RecordSet creation
    select << "SELECT * FROM Person", now;

    // create a RecordSet
    RecordSet rs(select);
    std::size_t cols = rs.columnCount();

    // print all column names
    for (std::size_t col = 0; col < cols; ++col)
        std::cout << rs.columnName(col) << std::endl;

    // iterate over all rows and columns
    for (RecordSet::Iterator it = rs.begin(); it != rs.end(); ++it)
        std::cout << *it << " ";

As you may see above, `RecordSet` class comes with a full-blown C++ compatible iterator that allows the above loop to be turned into a one-liner:

    std::copy(rs.begin(), rs.end(), std::ostream_iterator<Row>(std::cout));

RecordSet has the stream operator defined, so this shortcut to the above functionality will work, too:

    std::cout << rs;

The default formatter supplied with RecordSet is quite rudimentary, but user can implement custom formatters, by inheriting from RowFormatter and providing definitions of formatNames() and formatValues() virtual functions. See the RowFormatter sample for details on how to accomplish this.

You'll notice the Row class in the above snippet. The `RecordSet::Iterator` is actually a Poco::Data::RowIterator. It means that dereferencing it returns a Poco::Data::Row object. Here's a brief example to get an idea of what the Poco::Data::Row class does:

    Row row;
    row.append("Field0", 0);
    row.append("Field1", 1);
    row.append("Field2", 2);

The above code creates a row with three fields, "Field0", "Field1" and "Field2", having values 0, 1 and 2, respectively. Rows are sortable, which makes them suitable to be contained by standard sorted containers, such as std::map or std::set. By default, the first field of the row is used for sorting purposes. However, the sort criteria can be modified at runtime. For example, an additional field may be added to sort fields (think "... ORDER BY Name ASC, Age DESC"):

    row.addSortField("Field1"); // now Field0 and Field1 are used for sorting
    row.replaceSortField("Field0", "Field2");// now Field1 and Field2 are used for sorting

Finally, if you have a need for different RecordSet internal storage type than default (std::deque) provided by framework, there is a manipulator for that purpose:

    select << "SELECT * FROM Person", list, now; // use std::list as internal storage container

This can be very useful if you plan to manipulate the data after retrieving it from database. For example, std::list performs much better than std::vector for insert/delete operations and specifying it up-front as internal storage saves you the copying effort later. For large datasets, performance savings are significant.

Valid storage type manipulators are:

- deque (default)
- vector
- list

So, if neither data storage, nor storage type are explicitly specified, the data will internally be kept in standard deques. This can be changed through use of storage type manipulators.

## Complex Data Types

All the previous examples were contented to work with only the most basic data types: integer, string, ... a situation, unlikely to occur in real-world scenarios.

Assume you have a class Person:

    class Person
    {
    public:
        // default constructor+destr.
        // getter and setter methods for all members
        // ...

        bool operator <(const Person&amp; p) const
            /// we need this for set and multiset support
        {
            return _socialSecNr < p._socialSecNr;
        }

        Poco::UInt64 operator()() const
            /// we need this operator to return the key for the map and multimap
        {
            return _socialSecNr;
        }

    private:
        std::string _firstName;
        std::string _lastName;
        Poco::UInt64 _socialSecNr;
    };

Ideally, one would like to use a Person as simple as one used a string. All that is needed is a template specialization of the `TypeHandler` template. Note that template specializations must be declared in the same namespace as the original template, i.e. `Poco::Data`. The template specialization must implement the following methods:

    namespace Poco {
    namespace Data {

    template <>
    class TypeHandler<class Person>
    {
    public:
        static void bind(std::size_t pos, const Person&amp; obj, AbstractBinder::Ptr pBinder, AbstractBinder::Direction dir)
        {
            poco_assert_dbg (!pBinder.isNull());
            // the table is defined as Person (FirstName VARCHAR(30), lastName VARCHAR, SocialSecNr INTEGER(3))
            // Note that we advance pos by the number of columns the datatype uses! For string/int this is one.
            TypeHandler<std::string>::bind(pos++, obj.getFirstName(), pBinder, dir);
            TypeHandler<std::string>::bind(pos++, obj.getLastName(), pBinder, dir);
            TypeHandler<Poco::UInt64>::bind(pos++, obj.getSocialSecNr(), pBinder, dir);
        }

        static std::size_t size()
        {
            return 3; // we handle three columns of the Table!
        }

        static void prepare(std::size_t pos, const Person&amp; obj, AbstractPreparator::Ptr pPrepare)
        {
            poco_assert_dbg (!pPrepare.isNull());
            // the table is defined as Person (FirstName VARCHAR(30), lastName VARCHAR, SocialSecNr INTEGER(3))
            // Note that we advance pos by the number of columns the datatype uses! For string/int this is one.
            TypeHandler<std::string>::prepare(pos++, obj.getFirstName(), pPrepare);
            TypeHandler<std::string>::prepare(pos++, obj.getLastName(), pPrepare);
            TypeHandler<Poco::UInt64>::prepare(pos++, obj.getSocialSecNr(), pPrepare);
        }

        static void extract(std::size_t pos, Person&amp; obj, const Person&amp; defVal, AbstractExtractor::Ptr pExt)
            /// obj will contain the result, defVal contains values we should use when one column is NULL
        {
            poco_assert_dbg (!pExt.isNull());
            std::string firstName;
            std::string lastName;
            Poco::UInt64 socialSecNr = 0;
            TypeHandler<std::string>::extract(pos++, firstName, defVal.getFirstName(), pExt);
            TypeHandler<std::string>::extract(pos++, lastName, defVal.getLastName(), pExt);
            TypeHandler<Poco::UInt64>::extract(pos++, socialSecNr, defVal.getSocialSecNr(), pExt);
            obj.setFirstName(firstName);
            obj.setLastName(lastName);
            obj.setSocialSecNr(socialSecNr);
        }

    private:
        TypeHandler();
        ~TypeHandler();
        TypeHandler(const TypeHandler&amp;);
        TypeHandler&amp; operator=(const TypeHandler&amp;);
    };

    } } // namespace Poco::Data

And that's all you have to do. Working with Person is now as simple as working with a string:

    std::map<Poco::UInt64, Person> people;
    ses << "SELECT * FROM Person", into(people), now;

## Session Pooling

Creating a connection to a database is often a time consuming operation. Therefore it makes sense to save a session object for later reuse once it is no longer needed.

A Poco::Data::SessionPool manages a collection of sessions. When a session is requested, the SessionPool first looks in its set of already initialized sessions for an available object. If one is found, it is returned to the client and marked as "in-use". If no session is available, the SessionPool attempts to create a new one for the client. To avoid excessive creation of sessions, a limit can be set on the maximum number of objects.

The following code fragment shows how to use the SessionPool:

    SessionPool pool("ODBC", "...");
    // ...
    Session sess(pool.get());

Pooled sessions are automatically returned to the pool when the Session variable holding them is destroyed.

One session pool, of course, holds sessions for one database connection. For sessions to multiple databases, there is SessionPoolContainer:

    SessionPoolContainer spc;
    AutoPtr<SessionPool> pPool1 = new SessionPool("ODBC", "DSN1");
    AutoPtr<SessionPool> pPool2 = new SessionPool("ODBC", "DSN2");
    spc.add(pPool1);
    spc.add(pPool2);

## Conclusion

This document provides an overview of the most important features offered by the POCO Data framework. The framework also supports LOB (specialized to BLOB and CLOB) type as well as Poco::DateTime binding. The usage of these data types is no different than any C++ type, so we did not go into details here.

The great deal of `RecordSet` and `Row` runtime "magic" is achieved through employment of Poco::Dynamic::Var, which is the POCO equivalent of dynamic language data type. Obviously, due to its nature, there is a run time performance penalty associated with Poco::Dynamic::Var, but the internal details are beyond the scope of this document.

POCO Data tries to provide a broad spectrum of functionality, with configurable efficiency/convenience ratio, providing a solid foundation for quick development of database applications. We hope that, by reading this manual and experimenting with code along the way, you were able to get a solid understanding of the framework. We look forward to hearing from you about POCO Data as well as this manual. We also hope that you find both to be helpful aid in design of elegant and efficient standard C++ database access software.