Getting started

The most basic three types in libpqxx are the connection (which inherits its API from pqxx::connection_base and its setup behaviour from pqxx::connectionpolicy), the transaction (derived from pqxx::transaction_base), and the result (pqxx::result).

They fit together as follows:

• You connect to the database by creating a connection object (see Connection classes). The connection type you'll usually want is pqxx::connection.
• You create a transaction object (see Transaction classes) operating on that connection. You'll usually want the pqxx::work variety. If you don't want transactional behaviour, use pqxx::nontransaction. Once you're done you call the transaction's commit function to make its work final. If you don't call this, the work will be rolled back when the transaction object is destroyed.
• Until then, use the transaction's exec function to execute queries, which you pass in as simple strings.
• The function returns a pqxx::result object, which acts as a standard container of rows. Each row in itself acts as a container of fields. You can use array indexing and/or iterators to access either.
• The field's data is stored as a text string. You can read it as such using its c_str() function, or convert it to other types using its as() and to() member functions. These are templated on the destination type: myfield.as<int>(); or myfield.to(myint);
• After you've closed the transaction, the connection is free to run a next transaction.

Here's a very basic example. It connects to the default database (you'll need to have one set up), queries it for a very simple result, converts it to an int, and prints it out. It also contains some basic error handling.

#include <iostream>
#include <pqxx/pqxx>

int main()
{
  try
  {
    pqxx::connection c;
    pqxx::work w(c);
    pqxx::result r = w.exec("SELECT 1");
    w.commit();

    std::cout << r[0][0].as<int>() << std::endl;
  }
  catch (const std::exception &e)
  {
    std::cerr << e.what() << std::endl;
    return 1;
  }
}

This prints the number 1. Notice that you can keep the result object around after the transaction (or even the connection) has been closed.

Here's a slightly more complicated example. It takes an argument from the command line and retrieves a string with that value. The interesting part is that it uses the escaping-and-quoting function quote() to embed this string value in SQL safely. It also reads the result field's value as a plain C-style string using its c_str() function.

#include <iostream>
#include <pqxx/pqxx>

int main(int argc, char *argv[])
{
  if (!argv[1])
  {
    std::cerr << "Give me a string!" << std::endl;
    return 1;
  }
  try
  {
    pqxx::connection c;
    pqxx::work w(c);
    pqxx::result r = w.exec("SELECT " + w.quote(argv[1]));
    w.commit();

    std::cout << r[0][0].c_str() << std::endl;
  }
  catch (const std::exception &e)
  {
    std::cerr << e.what() << std::endl;
    return 1;
  }
}

You can find more about converting field values to native types, or converting values to strings for use with libpqxx, under String conversion. More about getting to the tuples and fields of a result is under Accessing results and result rows.

If you want to handle exceptions thrown by libpqxx in more detail, for example to print the SQL contents of a query that failed, see Exception classes.