MySQL Connector/C++ Release Notes

3.16 Changes in MySQL Connector/C++ 8.0.22 (2020-10-19, General Availability)

Compilation Notes

  • Connector/C++ now can be compiled using MinGW on Windows. Thanks to Eric Beuque for the contribution. Note that this enables building on MinGW but does not make MinGW an officially supported platform for Connector/C++. (Bug #31636723, Bug #100248)

Connection Management Notes

  • For connections made using X Plugin, Connector/C++ now enables specifying the compression algorithms to be used for connections that use compression. Connection URIs and SessionSettings objects permit explicitly specifying the preferred algorithms:

    • URI strings permit a compression-algorithms option. The value is an algorithm name, or a list of one or more comma-separated algorithms specified as an array. Examples: 

      mysqlx://user:password@host:port/db?compression-algorithms=lz4
mysqlx://user:password@host:port/db?compression-algorithms=[lz4,zstd_stream]

    • SessionSettings objects permit a SessionOption::COMPRESSION_ALGORITHMS option. The value is a list of one or more comma-separated algorithms. Examples: 

      mysqlx::Session sess(SessionOption::USER, "user_name",
                     SessionOption::PWD, "password",
                     SessionOption::COMPRESSION_ALGORITHMS, "lz4");
mysqlx::Session sess(SessionOption::USER, "user_name",
                     SessionOption::PWD, "password",
                     SessionOption::COMPRESSION_ALGORITHMS, "lz4,zstd_stream");

      Alternatively, the algorithms value can be given as a container: 

      std::list<std::string> algorithms = {"lz4","zstd_stream"};
mysqlx::Session sess(SessionOption::USER, "user_name",
                     SessionOption::PWD, "password",
                     SessionOption::COMPRESSION_ALGORITHMS, algorithms);

    • For X DevAPI for C, there is a new MYSQLX_OPT_COMPRESSION_ALGORITHMS option and corresponding OPT_COMPRESSION_ALGORITHMS helper macro.

      URI mode follows X DevAPI URI mode: 

      mysqlx_session_t *sess = mysqlx_get_session_from_url(
  "mysqlx://user:password@host:port/db?compression-algorithms=[lz4,zstd_stream]",
   &error);

      Option mode follows the string format used for SessionOption: 

      mysqlx_session_option_set(opt,
          OPT_HOST("host_name"), 
          OPT_USER("user"),
          OPT_PWD("password"),
          OPT_COMPRESSION_ALGORITHMS("lz4,zstd_stream"),
          PARAM_END));

    These rules apply:

    • Permitted algorithm names are zstd_stream, lz4_message, and deflate_stream, and their aliases zstd, lz4, and deflate. Names are case-insensitive. Unknown names are ignored.

    • Compression algorithms options permit multiple algorithms, which should be listed in priority order. Options that specify multiple algorithms can mix full algorithm names and aliases.

    • If no compression algorithms option is specified, the default is zstd_stream,lz4_message,deflate_stream.

    • The actual algorithm used is the first of those listed in the compression algorithms option that is also permitted on the server side. However, the option for compression algorithms is subject to the compression mode:

      • If the compression mode is disabled, the compression algorithms option is ignored.

      • If the compression mode is preferred but no listed algorithm is permitted on the server side, the connection is uncompressed.

      • If the compression mode is required but no listed algorithm is permitted on the server side, an error occurs.

    See also Connection Compression with X Plugin. (WL #13908, WL #13947)

Legacy (JDBC API) Notes

  • For applications that use the legacy JDBC API (that is, not X DevAPI or X DevAPI for C), Connector/C++ binary distributions now include the libraries that provide the client-side LDAP authentication plugins, as well as any dependent libraries required by the plugins. This enables Connector/C++ application programs to connect to MySQL servers using simple LDAP authentication, or SASL LDAP authentication using the SCRAM-SHA-1 authentication method.

    Note

    LDAP authentication requires use of a server from a MySQL Enterprise Edition distribution. For more information about the LDAP authentication plugins, see LDAP Pluggable Authentication.

    If Connector/C++ was installed from a compressed tar file or Zip archive, the application program will need to set the OPT_PLUGIN_DIR connection option to the appropriate directory so that the bundled plugin library can be found. (Alternatively, copy the required plugin library to the default directory expected by the client library.)

    Example: 

    sql::ConnectOptionsMap connection_properties;

// To use simple LDAP authentication ...

connection_properties["userName"] = "simple_ldap_user_name";
connection_properties["password"] = "simple_ldap_password";
connection_properties[OPT_ENABLE_CLEARTEXT_PLUGIN]=true;

// To use SASL LDAP authentication using SCRAM-SHA-1 ...

connection_properties["userName"] = "sasl_ldap_user_name";
connection_properties["password"] = "sasl_ldap_scram_password";

// Needed if Connector/C++ was installed from tar file or Zip archive ...

connection_properties[OPT_PLUGIN_DIR] = "${INSTALL_DIR}/lib{64}/plugin";

auto *driver = get_driver_instance();
auto *con = driver->connect(connection_properties);

// Execute statements ...

con->close();

    (WL #14113)

  • For applications that use the legacy JDBC API (that is, not X DevAPI or X DevAPI for C), LOCAL data loading capability for the LOAD DATA statement previously could be controlled on the client side only by enabling it for all files accessible to the client, or by disabling it altogether. The new OPT_LOAD_DATA_LOCAL_DIR option enables restricting LOCAL data loading to files located in a designated directory. For example, to set the value at connect time: 

    sql::ConnectOptionsMap opt;
opt[OPT_HOSTNAME] = "localhost";
opt[OPT_LOAD_DATA_LOCAL_DIR] = "/tmp";

sql::Connection *conn = driver->connect(opt);

    OPT_LOAD_DATA_LOCAL_DIR can also be set after connect time: 

    sql::ConnectOptionsMap opt;
opt[OPT_HOSTNAME] = "localhost";

sql::Connection *conn = driver->connect(opt);

//.... some queries / inserts / updates

std::string path= "/tmp";
conn->setClientOption(OPT_LOAD_DATA_LOCAL_DIR, path);

// LOAD LOCAL DATA DIR
...

//Disable LOCAL INFILE by setting to null
conn->setClientOption(OPT_LOAD_DATA_LOCAL_DIR, nullptr);

    The OPT_LOAD_DATA_LOCAL_DIR option maps onto the MYSQL_OPT_LOAD_DATA_LOCAL_DIR option for the mysql_options() C API function. For more information, see Security Considerations for LOAD DATA LOCAL. (WL #13884)

Bugs Fixed

  • String decoding failed for utf-8 strings that began with a \xEF byte-order mark. (Bug #31656092, Bug #100292)

  • With the CLIENT_MULTI_FLAG option enabled, executing multiple statements in a batch caused the next query to fail with a Commands out of sync error. (Bug #31399362)

  • For connections made using X Plugin, connections over Unix socket files did not work. (Bug #31329938)

  • For connections made using X Plugin, the default compression mode was DISABLED rather than PREFERRED. (Bug #31173447)

MySQL Documentation Library