Chapter 2. Connecting to an SQL server


Connecting to a non-predefined data source
Determining SQL database driver capabilities
#include <x/sql/connection.H>

std::pair<x::sql::connection, std::string> connret=henv->connect("DSN=dev");

auto conn=connret.first;

auto fullconnspec=connret.second;

auto conn2=conn->clone();

Invoking an environment object's connect() method establishes a connection to an SQL server, and returns a std::pair. Its first is a x::sql::connection, a reference to a reference-counted object, that represents the connection to the server; its second is a fully-qualified connection string. This string is a copy of the connection string parameter to connect() with explicit values for all defaulted or prompted connection parameters (see below). Passing the fully qualified connection string to connect() is guaranteed to create another connection to the same database server, using the same configuration settings as the first connection (presuming that the database server is available, of course).

clone() takes an existing connection and creates another connection, to the same server and database, using the same parameters. It is equivalent to calling connect() and passing the first connection's fully qualified connection string.

In all cases, an exception gets thrown if the connection fails.

connect() takes a string parameter that specifies the SQL server to connect to. DSN=name specifies a connection to a predefined ODBC data source name. The predefined data source connection, in this example, specifies all connection parameters, including any authentication credentials. A predefined data source connection can also be incomplete, and require additional parameters, or authorization credentials. Additional parameters are also given in the connection string, as a semicolon-delimited list:

std::pair<x::sql::connection, std::string> connret=henv->connect("DSN=dev;UID=citizenkane;PWD=rosebud");

The connection parameter UID and PWD give the authorization parameters. The second value in the returned tuple is a std::string that gives a complete connection string, with complete connection parameters that do not rely on connection defaults.

An alternative connect() takes a list of parameter tuples that specify the connection parameter as discrete values:

std::pair<x::sql::connection, std::string> connret=henv->connect("DSN", "dev", "UID", "citizenkane", "PWD", "rosebud");

It's also possible to supply connection parameters indirectly:

x::sql::env::base::arglist_t args;

args.push_back(std::make_pair("DSN", "dev"));
args.push_back(std::make_pair("UID", "citizenkane"));
args.push_back(std::make_pair("PWD", "rosebud"));

std::pair<x::sql::connection, std::string> connret=henv->connect(args);

x::sql::env::base::arglist_t is just a formal typedef for a std::list<std::pair<std::string, std::string>>.

std::pair<x::sql::connection, std::string> connret=henv->connect("DSN", "dev", x::sql::connect_flags::prompt);

The last parameter to connect() is optional, whether the connection parameters get specified as a single string, or as discrete values, and is one of the following x::sql::connect_flags values:


This is the default value. An exception gets thrown if the connection string does not specify all parameters that are needed for a connection.


Interactively prompt for connection parameters that are required, but absent from the connection string.

The ODBC connection manager library given by the x::sql::uiprompt application property gets loaded, to prompt for the additional parameters.


Like x::sql::connect_flags::complete_required, but also prompt for any optional connection parameters, in addition to the required ones.


Always prompt for connection parameters, even if the connection string specifies a complete connection. The values in the connection string are used as default values.


The reference-counted connection object automatically closes the connection to the database server when the last reference to the connection object goes out of scope, and it gets destroyed. Invoking disconnect() explicitly terminates the connection to the database server.

Connecting to a non-predefined data source

It is possible to connect to databases without setting up a named data source using the ODBC connection manager tool:

std::pair<x::sql::connection, std::string> connret=henv->connect("DRIVER={PostgreSQL};DATABASE=dev;SERVER=localhost;"

This example selects an ODBC driver named PostgreSQL. Use get_drivers() to enumerate available drivers. The remaining parameters are passed to the selected driver, as is.

The names and the right values for driver variables depend on the driver. Consult your ODBC driver's documentation for more information.

std::pair<x::sql::connection, std::string> connret=henv->connect("DRIVER={MySQL};DATABASE=dev;"

And this example selects an ODBC driver named MySQL.