#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:
x::sql::connect_flags::nopromptThis is the default value. An exception gets thrown if the connection string does not specify all parameters that are needed for a connection.
x::sql::connect_flags::complete_requiredInteractively 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.
x::sql::connect_flags::complete
Like x::sql::connect_flags::complete_required,
but also prompt for any optional connection parameters, in addition
to the required ones.
x::sql::connect_flags::promptAlways prompt for connection parameters, even if the connection string specifies a complete connection. The values in the connection string are used as default values.
conn->disconnect();
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.
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;" "PORT=5432;UID=citizenkane;PWD=rosebud");
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;" "SERVER=localhost;UID=citizenkane;PWD=rosebud;option=67108864");
And this example selects an ODBC driver named “MySQL”.