Connect From C++ App
MariaDB Connector/C++ enables C++ applications to establish client connections to MariaDB Cloud over TLS.
Requirements
MariaDB Connector/C++ has dependencies. You must install MariaDB Connector/C to use it.
1.1
3.2.3 or later
1.0
3.1.1 or later
For additional information, see "MariaDB Connector/C++ Release Notes".
Linux Installation (Binary Tarball)
To install MariaDB Connector/C++ on Linux:
Go to the MariaDB Connector C++ download page.
In the "OS" dropdown, select the Linux distribution you want to use.
Click the "Download" button to download the binary tarball.
Extract the tarball:
tar -xvzf mariadb-connector-cpp-*.tar.gz
Change into the relevant directory:
cd mariadb-connector-cpp-*/
Install the directories for the header files:
sudo install -d /usr/include/mariadb/conncpp sudo install -d /usr/include/mariadb/conncpp/compat
Install the header files:
sudo install include/mariadb/* /usr/include/mariadb/ sudo install include/mariadb/conncpp/* /usr/include/mariadb/conncpp sudo install include/mariadb/conncpp/compat/* /usr/include/mariadb/conncpp/compat
Install the directories for the shared libraries:
On CentOS, RHEL, Rocky Linux:
sudo install -d /usr/lib64/mariadb sudo install -d /usr/lib64/mariadb/plugin
On Debian, Ubuntu:
sudo install -d /usr/lib/mariadb sudo install -d /usr/lib/mariadb/plugin
Install the shared libraries:
On CentOS, RHEL, Rocky Linux:
sudo install lib64/mariadb/libmariadbcpp.so /usr/lib64 sudo install lib64/mariadb/plugin/* /usr/lib64/mariadb/plugin
On Debian, Ubuntu:
sudo install lib/mariadb/libmariadbcpp.so /usr/lib sudo install lib/mariadb/plugin/* /usr/lib/mariadb/plugin
Windows Installation (MSI)
To install MariaDB Connector/C++ on Windows:
MariaDB Connector/C dependency will be installed when Connector/C++ is installed.
Click the "Download" button to download the MSI package.
Run the MSI package and click "Next" to start the Setup Wizard.
On the second screen, click the license agreement checkbox, then click "Next."
On the third screen, click "Typical."
On the fourth screen, click "Install."
Click "Finish."
Add the directory path that contains the
mariadbcpp
LIB
file (example"C:\Program Files\MariaDB\MariaDB C++ Connector 64-bit"
) toPATH
environment variable.
For latest release visit C & C++ Connectors
Connection Info
The connection is configured via the information that is initially acquired from the MariaDB Cloud Portal pages:
Hostname in the URL
The fully Qualified Domain Name from the "Connect" window in MariaDB Cloud portal
Port number in the URL
The Read-Write Port or Read-Only Port from the "Connect" window in MariaDB Cloud portal
user parameter
The desired username, which might be the default username in the Service Credentials view
password parameter
The user's password, which might be the default password in the Service Credentials view if it was not yet customized
Connection URL Syntax
While MariaDB Connector/C++ supports several connection styles, we are going to detail just the JDBC syntax since all connections to MariaDB Cloud use a single idiom of hostname, port, user, password, and SSL parameters.
The base URL is specified as follows:
jdbc:mariadb://example.skysql.com:5001/dbname
If the trailing database name is left off of the URL, the connection will start without selecting a database.
Optional Connection Parameters
MariaDB Connector/C++ supports several optional connection parameters. These parameters can be specified using a Properties
object, as we do in our examples, or appended to the URL in standard name=value
query-string encoding.
In the following list, we've left out any parameters that aren't pertinent to accessing SkySQL:
autoReconnect
Defines whether the connector automatically reconnects after a connection failure.
bool
false
OPT_RECONNECT
connectTimeout
Defines the connect timeout value in milliseconds. When set to 0, there is no connect timeout.
int
30000
enabledTlsCipherSuites
A list of permitted ciphers or cipher suites to use for TLS.
string
enabledSslCipherSuites
jdbcCompliantTruncation
This mode is enabled by default. This mode configures the connector to add STRICT_TRANS_TABLES to sql_mode, which causes ES to handle truncation issues as errors instead of warnings.
bool
true
password
Defines the password of the user account to connect with.
socketTimeout
Defines the network socket timeout (SO_TIMEOUT) in milliseconds. When set to 0, there is no socket timeout. This connection parameter is not intended to set a maximum time for statements. To set a maximum time for statements, please see the max_statement_time.
int
0
OPT_READ_TIMEOUT
tcpRcvBuf
The buffer size for TCP/IP and socket communication. tcpSndBuf changes the same buffer value, and the biggest value of the two is selected.
int
0x4000
tcpSndBuf
tcpSndBuf
The buffer size for TCP/IP and socket communication. tcpRcvBuf changes the same buffer value, and the biggest value of the two is selected.
int
0x4000
tcpRcvBuf
tlsCert
Path to the X509 certificate file.
string
sslCert
tlsCRL
Path to a PEM file that should contain one or more revoked X509 certificates.
string
tlsCrl
useCompression
Compresses network traffic between the client and server.
bool
false
CLIENT_COMPRESS
user
Defines the user name of the user account to connect with.
userName
useServerPrepStmts
Defines whether the connector uses server-side prepared statements using the PREPARE Statement, EXECUTE statement, and DEALLOCATE / DROP PREPARE statements statements. By default, the connector uses client-side prepared statements.
bool
false
useTls
Whether to force TLS. This enables TLS with the default system settings.
bool
useSsl
Connection Methods
Two categories of methods are available to establish a connection.
sql::Driver::connect()
MariaDB Connector/C++ can connect using the non-static connect()
methods in the sql::Driver
class.
The non-static connect()
methods in the sql::Driver
class have the following prototypes:
Connection* connect(const SQLString& url, Properties& props);
Connection* connect(const SQLString& host, const SQLString& user, const SQLString& pwd);
Connection* connect(const Properties& props);
The non-static connect()
methods in the sql::Driver
class:
Require an instance of the
sql::Driver
class to establish a connection.Return
nullptr
as theConnection*
value when an error occurs, so applications should check the return value before use.
For example:
// Instantiate Driver
sql::Driver* driver = sql::mariadb::get_driver_instance();
// Configure Connection, including an optional initial database name "places":
sql::SQLString url("jdbc:mariadb://example.skysql.com:5009/places");
// Use a properties map for the other connection options
sql::Properties properties({
{"user", "db_user"},
{"password", "db_user_password"},
{"autocommit", false},
{"useTls", true},
{"tlsCert", "classpath:static/skysql_chain.pem"},
});
// Establish Connection
// Use a smart pointer for extra safety
std::unique_ptr<sql::Connection> conn(driver->connect(url, properties));
if (!conn) {
cerr << "Invalid database connection" << endl;
exit (EXIT_FAILURE);
}
sql::DriverManager::getConnection()
MariaDB Connector/C++ can connect using the static getConnection()
methods in the sql::DriverManager
class.
The static getConnection()
methods in the sql::DriverManager
class have the following prototypes:
static Connection* getConnection(const SQLString& url);
static Connection* getConnection(const SQLString& url, Properties& props);
static Connection* getConnection(const SQLString& url, const SQLString& user, const SQLString& pwd);
The static getConnection()
methods in the sql::DriverManager
class:
Do not require an instance of the
sql::DriverManager
class to establish a connection, because they are static.Throw an exception when an error occurs, so applications should use
try { .. } catch ( .. ) { .. }
to catch the exception.
For example:
try {
// Configure Connection, including an optional initial database name "places":
sql::SQLString url("jdbc:mariadb://example.skysql.com:5009/places");
// Use a properties map for the other connection options
sql::Properties properties({
{"user", "db_user"},
{"password", "db_user_password"},
{"autocommit", false},
{"useTls", true},
{"tlsCert", "classpath:static/skysql_chain.pem"},
});
// Establish Connection
// Use a smart pointer for extra safety
std::unique_ptr<sql::Connection> conn(DriverManager::getConnection(url, properties));
} catch (...) {
cerr << "Invalid database connection" << endl;
exit (EXIT_FAILURE);
}
Code Example: Connecting
The following code demonstrates how to connect using the example database and user account:
// Includes
#include <iostream>
#include <mariadb/conncpp.hpp>
// Main Process
int main(int argc, char **argv)
{
try {
// Instantiate Driver
sql::Driver* driver = sql::mariadb::get_driver_instance();
// Configure Connection, including initial database name "test":
sql::SQLString url("jdbc:mariadb://example.skysql.com:5009/test");
// Use a properties map for the other connection options
sql::Properties properties({
{"user", "db_user"},
{"password", "db_user_password"},
{"autocommit", false},
{"useTls", true},
{"tlsCert", "classpath:static/skysql_chain.pem"},
});
// Establish Connection
// Use a smart pointer for extra safety
std::unique_ptr<sql::Connection> conn(driver->connect(url, properties));
// Use Connection
// ...
// Close Connection
conn->close();
}
// Catch Exceptions
catch (sql::SQLException& e) {
std::cerr << "Error Connecting to the database: "
<< e.what() << std::endl;
// Exit (Failed)
return 1;
}
// Exit (Success)
return 0;
}
Last updated
Was this helpful?