Connect with MariaDB Connector/C++

MariaDB Connector/C++ enables C++ applications to establish client connections to MariaDB database products over TLS.

Connection URL Syntax

MariaDB Connector/C++ supports two different formats for connection URLs, the JDBC syntax and the compatibility syntax.

JDBC Syntax

MariaDB Connector/C++ supports a connection URL syntax similar to JDBC.

The JDBC syntax for connection URLs is:

jdbc:mariadb://<hostDescription>/[<database>] [?<key1>=<value1>[&<key2>=<value2>]]

The connection URL:

• Requires jdbc:mariadb:// as the protocol component.

• Requires the host description in the hostDescription field.

• Accepts an optional database name. If no database is provided, the connection will not select a database.

• Accepts optional connection parameters in key=value format.

Some example connection URLs using the JDBC syntax:

• jdbc:mariadb:192.0.2.1/

• jdbc:mariadb:192.0.2.1/?user=db_user&password=db_user_password

• jdbc:mariadb:192.0.2.1/database?user=db_user&password=db_user_password

• jdbc:mariadb:192.0.2.1:3307/database?user=db_user&password=db_user_password

• jdbc:mariadb:mariadb.example.com/database?user=db_user&password=db_user_password

• jdbc:mariadb:mariadb.example.com:3307/database?user=db_user&password=db_user_password

• jdbc:mariadb:localhost/database?localSocket=/var/lib/mysql/mysql.sock&user=db_user&password=db_user_password

Compatibility Syntax

MariaDB Connector/C++ supports a connection URL syntax for compatibility with MySQL Connector/C++.

The compatibility syntax for connection URLs is only supported for the sql::Driver::connect() connection method.

The compatibility syntax for connection URLs is:

(tcp|unix|pipe)://<hostDescription>[/]

The connection URL:

• Requires tcp: as the protocol component to connect via TCP/IP.

• Requires unix: as the protocol component to connect via Unix socket file. The hostDescription field should be set to localhost, and the localSocket connection parameter should be set in the properties when you call the sql::Driver::connect() connection method.

• Requires pipe:// as the protocol component to connect via Windows named pipe. The hostDescription field should be set to localhost, and the pipe connection parameter should be set in the properties when you call the sql::Driver::connect() connection method.

• Requires the host description in the hostDescription field.

Some example connection URLs using the compatibility syntax:

• tcp:192.0.2.1/

• tcp:192.0.2.1:3307/

• tcp:mariadb.example.com/

• tcp:mariadb.example.com:3307/

• unix:localhost/

• pipe:localhost/

Host Description

The host description syntax for MariaDB Connector/C++ is:

<host>[:<portNumber>]

The host description:

• Requires the host field to set the destination host to connect.

• Accepts the host field as a host name, IPv4 address, or IPv6 address to connect via TCP/IP.

• Accepts the host field as localhost to connect via Unix socket file, when the localSocket connection parameter is also set.

• Accepts an optional portNumber field to set the TCP/IP port. If it is not provided, the TCP port 3306 is used by default.

Some example host descriptions:

• 192.0.2.1

• 192.0.2.1:3307

• mariadb.example.com

• mariadb.example.com:3307

jdbc:mariadb://192.0.2.1:3306/database?user=db_user&password=db_user_password

Optional Connection Parameters

MariaDB Connector/C++ accepts optional connection parameters in multiple contexts for both connection methods:

• They can be specified in a connection URL with JDBC syntax.

• They can be specified in a Properties object.

MariaDB Connector/C++ supports several optional connection parameters:

Connection Methods

Two categories of methods are available to 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.

• Accept both forms of connection URL syntax.

• Provide two prototypes that do not use connection URLs at all.

• Return nullptr as the Connection* 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
// The URL or TCP connection string format is
// ``jdbc:mariadb://host:port/database``.
sql::SQLString url("jdbc:mariadb://192.0.2.1:3306/test");

// Use a properties map for the other connection options
sql::Properties properties({
      {"user", "db_user"},
      {"password", "db_user_password"},
   });

// 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.

• Accept only the JDBC syntax for connection URLs.

• Throw an exception when an error occurs, so applications should use try { .. } catch ( .. ) { .. } to catch the exception.

For example:

 try {
    // Configure Connection
    // The URL or TCP connection string format is
    // ``jdbc:mariadb://host:port/database``.
    sql::SQLString url("jdbc:mariadb://192.0.2.1:3306/test");

    // Use a properties map for the other connection options
    sql::Properties properties({
          {"user", "db_user"},
          {"password", "db_user_password"},
       });

    // 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: Connect

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
      // The URL or TCP connection string format is
      // ``jdbc:mariadb://host:port/database``.
      sql::SQLString url("jdbc:mariadb://192.0.2.1:3306/test");

      // Use a properties map for the other connection options
      sql::Properties properties({
            {"user", "db_user"},
            {"password", "db_user_password"},
         });

      // 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;
}

Code Example: TLS

The following `code` demonstrates how to connect with TLS (Transport Layer Security, the successor to SSL) for 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
      // The URL or TCP connection string format is
      // ``jdbc:mariadb://host:port/database``.
      sql::SQLString url("jdbc:mariadb://192.0.2.1:3306/test");

      // Use a properties map for the user name and password
      //The ``useTls`` option enables TLS
      //The ``tlsCA`` option specifies path to a PEM file that contains a X509 certificate for trusted Certificate Authorities (CAs).
      sql::Properties properties({
            {"user", "db_user"},
            {"password", "db_user_password"},
            {"useTls", "true"},
            {"tlsCA", "tls-ca-root.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;
}