Chapter 10 Connector/C++ Connection Options

To connect to a MySQL server from Connector/C++ applications, use the connect() method of the MySQL_Driver class. The connect() method has two calling sequences:

One calling sequence takes arguments indicating how to connect to the MySQL server, and the user name and password of the MySQL account to use:

sql::Connection * MySQL_Driver::connect(const sql::SQLString& hostName,
                                        const sql::SQLString& userName,
                                        const sql::SQLString& password)

Example:

sql::mysql::MySQL_Driver *driver;
sql::Connection *con;

driver = sql::mysql::MySQL_Driver::get_mysql_driver_instance();
con = driver->connect("tcp://127.0.0.1:3306", "root", "rootpass");

This syntax is convenient for simple connections.

The other syntax takes an option map that contains the connection properties to use for establishing the connection:

sql::Connection * MySQL_Driver::connect(sql::ConnectOptionsMap & properties)

This syntax is useful for connections that require specifying options other than the three permitted by the first syntax. To use an option map, initialize it with the required connection properties, then pass the map to the connect() call.

Example:

sql::mysql::MySQL_Driver *driver;
sql::Connection *con;
sql::ConnectOptionsMap connection_properties;

connection_properties["hostName"] = hostName;
connection_properties["userName"] = userName;
connection_properties["password"] = password;
connection_properties["schema"] = "information_schema";
connection_properties["port"] = 13306;
connection_properties["OPT_RECONNECT"] = true;

driver = sql::mysql::MySQL_Driver::get_mysql_driver_instance();
con = driver->connect(connection_properties);

The hostName parameter can be a host name, IP address, or URL.

For a hostName value specified as a URL, the format begins with a transport protocol and the protocol determines the syntax of the remaining part of the URL:

tcp://...
This URL format establishes a TCP/IP connection and is usable on all platforms. The format permits specification of host hame or IP address, TCP/IP port number, and default database. The syntax for a URL that includes all those items looks like this:
```
tcp://host:port/db
```
The :port and /db parts of the URL are optional. The host part may be enclosed within [ and ] characters, which is useful for specifying IPv6 addresses such as ::1 that contain the : character that otherwise would be interpreted as beginning a :port specifier.
This URL connects to the local host using the default port number and without selecting a default database:
```
tcp://127.0.0.1
```
This URL connects to the named host on port 13306 and selects employees as the default database:
```
tcp://host1.example.com:13306/employees
```
This URL connects to port 3307 on the local host, using the ::1 IPv6 address. The URL uses [ and ] around the address to disambiguate the : characters in the host and port parts of the URL:
```
tcp://[::1]:3307
```
pipe://pipe_name
This URL format enables use of named pipes for connections to the local host on Windows systems. The pipe_name value is the named pipe name, just as for the --socket option of MySQL clients such as mysql and mysqladmin running on Windows (see Connecting to the MySQL Server Using Command Options).
unix://path_name
This URL format enables use of Unix domain socket files for connections to the local host on Unix and Unix-like systems. The path_name value is the socket file path name, just as for the --socket option of MySQL clients such as mysql and mysqladmin running on Unix (see Connecting to the MySQL Server Using Command Options).

For the connect() syntax that takes an option map argument, Connector/C++ supports the connection properties described in the following list.

Note

Many of these properties correspond to arguments for the mysql_options(), mysql_options4(), or mysql_real_connect(), C API function. For such properties, the descriptions here are brief. For more information, refer to the descriptions for those functions. See mysql_options(), mysql_options4(), and mysql_real_connect().

characterSetResults
This option sets the character_set_results system variable for the session. The value is a string.
charsetDir
The path name to the directory that contains character set definition files. This option corresponds to the MYSQL_SET_CHARSET_DIR option for the mysql_options() C API function. The value is a string.
This option was added in Connector/C++ 1.1.5.
CLIENT_COMPRESS
Whether to use compression in the client/server protocol. This option corresponds to the flag of the same name for the client_flag argument of the mysql_real_connect() C API function. The value is a boolean.
CLIENT_FOUND_ROWS
Whether to return the number of found (matched) rows, not the number of changed rows. This option corresponds to the flag of the same name for the client_flag argument of the mysql_real_connect() C API function. The value is a boolean.
CLIENT_IGNORE_SIGPIPE
Whether to prevent the libmysqlclient client library from installing a SIGPIPE signal handler. This option corresponds to the flag of the same name for the client_flag argument of the mysql_real_connect() C API function. The value is a boolean.
CLIENT_IGNORE_SPACE
Whether to permit spaces after function names. This option corresponds to the flag of the same name for the client_flag argument of the mysql_real_connect() C API function. The value is a boolean.
CLIENT_INTERACTIVE
Whether to permit interactive_timeout seconds of inactivity (rather than wait_timeout seconds) before closing the connection. This option corresponds to the flag of the same name for the client_flag argument of the mysql_real_connect() C API function. The value is a boolean.
CLIENT_LOCAL_FILES
Whether to enable LOAD DATA LOCAL INFILE handling. This option corresponds to the flag of the same name for the client_flag argument of the mysql_real_connect() C API function. The value is a boolean.
CLIENT_MULTI_STATEMENTS
Whether the client may send multiple statements in a single string (separated by ; characters). This option corresponds to the flag of the same name for the client_flag argument of the mysql_real_connect() C API function. The value is a boolean.
Note
There is no CLIENT_MULTI_RESULTS connection option. Connector/C++ enables that flag for all connections.
CLIENT_NO_SCHEMA
Whether to prohibit db_name.tbl_name.col_name syntax. This option corresponds to the flag of the same name for the client_flag argument of the mysql_real_connect() C API function. The value is a boolean.
defaultAuth
The name of the authentication plugin to use. This option corresponds to the MYSQL_DEFAULT_AUTH option for the mysql_options() C API function. The value is a string.
This option was added in Connector/C++ 1.1.5.
defaultPreparedStatementResultType
The result set type for statements executed using MySQL_Connection::prepareStatement() to define whether result sets are scrollable. Permitted values are sql::ResultSet::TYPE_FORWARD_ONLY and sql::ResultSet::TYPE_SCROLL_INSENSITIVE. The sql::ResultSet::TYPE_SCROLL_SENSITIVE type is not supported.
defaultStatementResultType
The result set type for statements executed using MySQL_Connection::createStatement() to define whether result sets are scrollable. Permitted values are sql::ResultSet::TYPE_FORWARD_ONLY and sql::ResultSet::TYPE_SCROLL_INSENSITIVE. The sql::ResultSet::TYPE_SCROLL_SENSITIVE type is not supported.
hostName
This has the same meaning and syntax as for the three-argument connect() syntax. The value can be a host name, IP address, or URL, as described earlier in this section.
OPT_CAN_HANDLE_EXPIRED_PASSWORDS
Whether the client can handle expired passwords. This option corresponds to the MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS option for the mysql_options() C API function. The value is a boolean.
For a usage example, see Section 6.7, “Connecting to an Account with an Expired Password”.
This option was added in Connector/C++ 1.1.2.
OPT_CHARSET_NAME
The name of the character set to use as the default character set. This option corresponds to the MYSQL_SET_CHARSET_NAME option for the mysql_options() C API function. The value is a string.
OPT_CONNECT_ATTR_ADD
Key-value pairs to add to the current set of connection attributes to pass to the server at connect time. This option corresponds to the MYSQL_OPT_CONNECT_ATTR_ADD option for the mysql_options4() C API function. The value is a std::map< sql::SQLString, sql::SQLString > value.
This option was added in Connector/C++ 1.1.4.
OPT_CONNECT_ATTR_DELETE
Key names for key-value pairs to delete from the current set of connection attributes to pass to the server at connect time. This option corresponds to the MYSQL_OPT_CONNECT_ATTR_DELETE option for the mysql_options() C API function. The value is a std::list< sql::SQLString > value.
This option was added in Connector/C++ 1.1.5.
OPT_CONNECT_ATTR_RESET
Resets (clears) the current set of connection attributes to pass to the server at connect time. This option corresponds to the MYSQL_OPT_CONNECT_ATTR_RESET option for the mysql_options() C API function.
This option was added in Connector/C++ 1.1.5.
OPT_CONNECT_TIMEOUT
The connect timeout in seconds. This option corresponds to the MYSQL_OPT_CONNECT_TIMEOUT option for the mysql_options() C API function. The value is an unsigned integer.
OPT_ENABLE_CLEARTEXT_PLUGIN
Enable the mysql_clear_password cleartext authentication plugin. This option corresponds to the MYSQL_ENABLE_CLEARTEXT_PLUGIN option for the mysql_options() C API function. The value is a boolean.
This option was added in Connector/C++ 1.1.3.
OPT_GET_SERVER_PUBLIC_KEY
For connections to the server made using the legacy protocol (that is, not made using X DevAPI or X DevAPI for C), Connector/C++, request the RSA public key from the server. For accounts that use the caching_sha2_password or sha256_password authentication plugin, this key can be used during the connection process for RSA key-pair based password exchange with TLS disabled. This option corresponds to the MYSQL_OPT_GET_SERVER_PUBLIC_KEY option for the mysql_options() C API function. The value is a boolean.
This capability requires a MySQL 8.0 GA server, and is supported only for Connector/C++ built using OpenSSL.
This option was added in Connector/C++ 1.1.11.
OPT_LOCAL_INFILE
Whether to enable the LOAD DATA LOCAL INFILE statement. This option corresponds to the MYSQL_OPT_LOCAL_INFILE option for the mysql_options() C API function. The value is an unsigned integer.
This option was added in Connector/C++ 1.1.5.
OPT_NAMED_PIPE
Use a named pipe to connect to the MySQL server on Windows, if the server permits named-pipe connections. This option corresponds to the MYSQL_OPT_NAMED_PIPE option for the mysql_options() C API function. The value is unused.
OPT_READ_TIMEOUT
The timeout in seconds for each attempt to read from the server. This option corresponds to the MYSQL_OPT_READ_TIMEOUT option for the mysql_options() C API function. The value is an unsigned integer.
OPT_RECONNECT
Enable or disable automatic reconnection to the server if the connection is found to have been lost. This option corresponds to the MYSQL_OPT_RECONNECT option for the mysql_options() C API function. The value is a boolean. The default is false.
OPT_REPORT_DATA_TRUNCATION
Enable or disable reporting of data truncation errors for prepared statements using the error member of MYSQL_BIND structures. This option corresponds to the MYSQL_REPORT_DATA_TRUNCATION option for the mysql_options() C API function. The value is a boolean.
OPT_TLS_VERSION
Specify the protocols permitted for encrypted connections. The option value is string containing a comma-separated list of one or more protocol names. Example:
```
connection_properties["OPT_TLS_VERSION"] = sql::SQLString("TLSv1.1,TLSv1.2");
```
The permitted values depend on the SSL library used to compile MySQL: TLSv1, TLSv1.1, TLSv1.2 if OpenSSL was used; TLSv1 and TLSv1.1 if yaSSL was used. The default is to permit all available protocols.
For more information about encryption protocols in MySQL, see Encrypted Connection TLS Protocols and Ciphers.
This option was added in Connector/C++ 1.1.8.
OPT_WRITE_TIMEOUT
The timeout in seconds for each attempt to write to the server. This option corresponds to the MYSQL_OPT_WRITE_TIMEOUT option for the mysql_options() C API function. The value is an unsigned integer.
password
The password for the client MySQL account. This option corresponds to the passwd argument of the mysql_real_connect() C API function. The value is a string.
pipe
The name of the named pipe for a named-pipe connection to the local host on Windows systems. The value is a string.
pluginDir
The directory in which to look for client plugins. This option corresponds to the MYSQL_PLUGIN_DIR option for the mysql_options() C API function. The value is a string.
This option was added in Connector/C++ 1.1.5.
port
The port number for TCP/IP connections. This option corresponds to the port argument of the mysql_real_connect() C API function. The value is an unsigned integer.
postInit
This option is similar to preInit, but the statements are executed after driver initialization. The value is a string.
This option was added in Connector/C++ 1.1.2.
preInit
A string containing statements to execute before driver initialization. This option corresponds to the MYSQL_INIT_COMMAND option for the mysql_options() C API function. The value is a string.
For an example showing the use of this option to reset an expired password, see Section 6.7, “Connecting to an Account with an Expired Password”.
This option was added in Connector/C++ 1.1.2.
readDefaultFile
Read options from the named option file instead of from my.cnf. This option corresponds to the MYSQL_READ_DEFAULT_FILE option for the mysql_options() C API function. The value is a string.
This option was added in Connector/C++ 1.1.5.
readDefaultGroup
Read options from the named group from my.cnf or the file specified with readDefaultFile. This option corresponds to the MYSQL_READ_DEFAULT_GROUP option for the mysql_options() C API function. The value is a string.
This option was added in Connector/C++ 1.1.5.
rsaKey
The path name to a file containing the server RSA public key. This option corresponds to the MYSQL_SERVER_PUBLIC_KEY option for the mysql_options() C API function. The value is a string.
schema
The default database name. This option corresponds to the db argument of the mysql_real_connect() C API function. The value is a string.
socket
The name of a Unix domain socket file for a socket-file connection to the local host on Unix and Unix-like systems. This option corresponds to the socket argument of the mysql_real_connect() C API function. The value is a string.
sslCA
The path to a file in PEM format that contains a list of trusted SSL CAs. This option corresponds to the MYSQL_OPT_SSL_CA option for the mysql_options() C API function. The value is a string.
sslCAPath
The path to a directory that contains trusted SSL CA certificates in PEM format. This option corresponds to the MYSQL_OPT_SSL_CAPATH option for the mysql_options() C API function. The value is a string.
sslCert
The name of an SSL certificate file in PEM format to use for establishing a secure connection. This option corresponds to the MYSQL_OPT_SSL_CERT option for the mysql_options() C API function. The value is a string.
sslCipher
The list of permissible ciphers for SSL encryption. This option corresponds to the MYSQL_OPT_SSL_CIPHER option for the mysql_options() C API function. The value is a string.
sslCRL
The path to a file containing certificate revocation lists in PEM format. This option corresponds to the MYSQL_OPT_SSL_CRL option for the mysql_options() C API function. The value is a string.
This option was added in Connector/C++ 1.1.4.
sslCRLPath
The path to a directory that contains files containing certificate revocation lists in PEM format. This option corresponds to the MYSQL_OPT_SSL_CRLPATH option for the mysql_options() C API function. The value is a string.
This option was added in Connector/C++ 1.1.4.
sslEnforce
Whether to require the connection to use SSL. This option corresponds to the MYSQL_OPT_SSL_ENFORCE option for the mysql_options() C API function. The value is a boolean.
sslKey
The name of an SSL key file in PEM format to use for establishing a secure connection. This option corresponds to the MYSQL_OPT_SSL_KEY option for the mysql_options() C API function. The value is a string.
sslVerify
Enable or disable verification of the server's Common Name value in its certificate against the host name used when connecting to the server. This option corresponds to the MYSQL_OPT_SSL_VERIFY_SERVER_CERT option for the mysql_options() C API function. The value is a boolean.
This option was added in Connector/C++ 1.1.4.
useLegacyAuth
Whether to permit connections to a server that does not support the password hashing used in MySQL 4.1.1 and later. This option corresponds to the MYSQL_SECURE_AUTH option for the mysql_options() C API function, except that the sense of useLegacyAuth is logically opposite that of MYSQL_SECURE_AUTH. For example, to disable secure authentication, pass a useLegacyAuth value of true. The value is a boolean.
This option was added in Connector/C++ 1.1.4.
userName
The user name for the MySQL account to use. This option corresponds to the user argument of the mysql_real_connect() C API function. The value is a string.