MySQL 连接器/C++ 1.1 开发人员指南  /  第 10 章连接器/C++ 连接选项

第 10 章连接器/C++ 连接选项

要从连接器/C++ 应用程序连接到 MySQL 服务器，请使用该类的 connect()方法 MySQL_Driver。该 connect()方法有两个调用序列：

  • 一个调用序列采用指示如何连接到 MySQL 服务器的参数，以及要使用的 MySQL 帐户的用户名和密码： 

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

    例子： 

    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");

    这种语法对于简单的连接很方便。

  • 另一种语法采用选项映射，其中包含用于建立连接的连接属性： 

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

    此语法对于需要指定第一个语法允许的三个选项以外的选项的连接很有用。要使用选项映射，请使用所需的连接属性对其进行初始化，然后将映射传递给 connect()调用。

    例子： 

    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);

该hostName参数可以是主机名、IP 地址或 URL。

对于hostName指定为 URL 的值，格式以传输协议开头，协议确定 URL 其余部分的语法：

  • tcp://...

    此 URL 格式建立 TCP/IP 连接，可用于所有平台。该格式允许指定主机名或 IP 地址、TCP/IP 端口号和默认数据库。包含所有这些项目的 URL 的语法如下所示： 

    tcp://host:port/db

    URL的和 部分是可选的。该部分可以包含在和 字符中，这对于指定 IPv6 地址非常有用，例如包含字符的 字符，否则将被解释为开始 说明符。 :port/dbhost[]::1::port

    此 URL 使用默认端口号连接到本地主机，而不选择默认数据库： 

    tcp://127.0.0.1

    此 URL 连接到端口 13306 上的指定主机并选择 employees作为默认数据库： 

    tcp://host1.example.com:13306/employees

    ::1此 URL 使用IPv6 地址 连接到本地主机上的端口 3307 。URL 在地址周围使用[and来消除URL 的主机和端口部分中的字符的歧义： ]:

    tcp://[::1]:3307

  • pipe://pipe_name

    此 URL 格式允许使用命名管道连接到 Windows 系统上的本地主机。该 pipe_name值是命名管道名称，就像在 Windows 上运行的 mysql和 mysqladmin--socket 等 MySQL 客户端的选项一样（请参阅使用命令选项连接到 MySQL 服务器）。

  • unix://path_name

    此 URL 格式允许使用 Unix 域套接字文件连接到 Unix 和类 Unix 系统上的本地主机。该 path_name值是套接字文件路径名，就像 在 Unix 上运行的 mysql和 mysqladmin--socket等 MySQL 客户端的选项一样（请参阅使用命令选项连接到 MySQL 服务器）。

对于connect()采用选项映射参数的语法，Connector/C++ 支持下表中描述的连接属性。

笔记

其中许多属性对应于 mysql_options()、 mysql_options4()或 mysql_real_connect(), C API 函数的参数。对于此类属性，此处的描述很简短。有关详细信息，请参阅这些功能的说明。参见mysql_options()、 mysql_options4()和 mysql_real_connect()。

  • characterSetResults

    此选项设置 character_set_results会话的系统变量。该值是一个字符串。

  • charsetDir

    包含字符集定义文件的目录的路径名。此选项对应于 C API 函数的MYSQL_SET_CHARSET_DIR选项 。mysql_options()该值是一个字符串。

    此选项是在 Connector/C++ 1.1.5 中添加的。

  • CLIENT_COMPRESS

    是否在客户端/服务器协议中使用压缩。此选项对应于C API 函数client_flag参数的 同名标志 。mysql_real_connect()该值是一个布尔值。

  • CLIENT_FOUND_ROWS

    是否返回找到（匹配）的行数，而不是更改的行数。此选项对应于C API 函数client_flag参数的同名标志。mysql_real_connect()该值是一个布尔值。

  • CLIENT_IGNORE_SIGPIPE

    是否阻止libmysqlclient客户端库安装SIGPIPE信号处理程序。此选项对应于C API 函数client_flag参数的 同名标志。mysql_real_connect()该值是一个布尔值。

  • CLIENT_IGNORE_SPACE

    函数名后是否允许有空格。此选项对应于C API 函数client_flag参数的 同名标志 。mysql_real_connect()该值是一个布尔值。

  • CLIENT_INTERACTIVE

    在关闭连接之前 是否允许 interactive_timeout几秒钟的不活动（而不是 几秒钟）。此选项对应于C API 函数参数的wait_timeout同名标志。该值是一个布尔值。 client_flagmysql_real_connect()

  • CLIENT_LOCAL_FILES

    是否启用 LOAD DATA LOCAL INFILE处理。此选项对应于C API 函数client_flag参数的同名标志。mysql_real_connect()该值是一个布尔值。

  • CLIENT_MULTI_STATEMENTS

    客户端是否可以在单个字符串中发送多个语句（由;字符分隔）。此选项对应于C API 函数client_flag参数的 同名标志 。mysql_real_connect()该值是一个布尔值。

    笔记

    没有CLIENT_MULTI_RESULTS连接选项。Connector/C++ 为所有连接启用该标志。

  • CLIENT_NO_SCHEMA

    是否禁止 db_name.tbl_name.col_name语法。此选项对应于C API 函数client_flag参数的 同名标志 。mysql_real_connect()该值是一个布尔值。

  • defaultAuth

    要使用的身份验证插件的名称。此选项对应于C API 函数的MYSQL_DEFAULT_AUTH选项。mysql_options()该值是一个字符串。

    此选项是在 Connector/C++ 1.1.5 中添加的。

  • defaultPreparedStatementResultType

    执行语句的结果集类型，用于 MySQL_Connection::prepareStatement()定义结果集是否可滚动。允许的值为 sql::ResultSet::TYPE_FORWARD_ONLY和 sql::ResultSet::TYPE_SCROLL_INSENSITIVE。sql::ResultSet::TYPE_SCROLL_SENSITIVE不支持 该 类型。

  • defaultStatementResultType

    执行语句的结果集类型，用于 MySQL_Connection::createStatement()定义结果集是否可滚动。允许的值为 sql::ResultSet::TYPE_FORWARD_ONLY和 sql::ResultSet::TYPE_SCROLL_INSENSITIVE。sql::ResultSet::TYPE_SCROLL_SENSITIVE不支持 该 类型。

  • hostName

    这与三参数语法具有相同的含义和 connect()语法。如本节前面所述，该值可以是主机名、IP 地址或 URL。

  • OPT_CAN_HANDLE_EXPIRED_PASSWORDS

    客户端是否可以处理过期密码。此选项对应于 C API 函数的MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS选项。mysql_options()该值是一个布尔值。

    有关用法示例，请参阅 第 6.7 节 “连接到密码已过期的帐户”。

    此选项是在 Connector/C++ 1.1.2 中添加的。

  • OPT_CHARSET_NAME

    用作默认字符集的字符集的名称。此选项对应于 C API 函数的MYSQL_SET_CHARSET_NAME选项 。mysql_options()该值是一个字符串。

  • OPT_CONNECT_ATTR_ADD

    要添加到当前连接属性集以在连接时传递给服务器的键值对。此选项对应于 C API 函数的MYSQL_OPT_CONNECT_ATTR_ADD 选项。mysql_options4()该值是一个std::map< sql::SQLString, sql::SQLString >值。

    此选项是在 Connector/C++ 1.1.4 中添加的。

  • OPT_CONNECT_ATTR_DELETE

    要从当前连接属性集中删除的键值对的键名，以在连接时传递给服务器。此选项对应于 C API 函数的MYSQL_OPT_CONNECT_ATTR_DELETE选项 。mysql_options()该值是一个std::list< sql::SQLString >值。

    此选项是在 Connector/C++ 1.1.5 中添加的。

  • OPT_CONNECT_ATTR_RESET

    重置（清除）当前连接属性集以在连接时传递给服务器。此选项对应于 C API 函数 的MYSQL_OPT_CONNECT_ATTR_RESET选项 。mysql_options()

    此选项是在 Connector/C++ 1.1.5 中添加的。

  • OPT_CONNECT_TIMEOUT

    以秒为单位的连接超时。此选项对应于 C API 函数的MYSQL_OPT_CONNECT_TIMEOUT选项 。mysql_options()该值是一个无符号整数。

  • OPT_ENABLE_CLEARTEXT_PLUGIN

    启用mysql_clear_password明文身份验证插件。此选项对应于 C API 函数的MYSQL_ENABLE_CLEARTEXT_PLUGIN选项 。mysql_options()该值是一个布尔值。

    此选项是在 Connector/C++ 1.1.3 中添加的。

  • OPT_GET_SERVER_PUBLIC_KEY

    对于使用旧协议（即，不是使用 X DevAPI 或 X DevAPI for C）、Connector/C++ 建立的与服务器的连接，从服务器请求 RSA 公钥。对于使用caching_sha2_password或 sha256_password身份验证插件的帐户，此密钥可在禁用 TLS 的情况下用于基于 RSA 密钥对的密码交换的连接过程中使用。此选项对应于 C API 函数的MYSQL_OPT_GET_SERVER_PUBLIC_KEY选项。mysql_options()该值是一个布尔值。

    此功能需要 MySQL 8.0 GA 服务器，并且仅支持使用 OpenSSL 构建的连接器/C++。

    此选项是在 Connector/C++ 1.1.11 中添加的。

  • OPT_LOCAL_INFILE

    是否启用 LOAD DATA LOCAL INFILE语句。此选项对应于 C API 函数的MYSQL_OPT_LOCAL_INFILE选项 。mysql_options()该值是一个无符号整数。

    此选项是在 Connector/C++ 1.1.5 中添加的。

  • OPT_NAMED_PIPE

    如果服务器允许命名管道连接，则使用命名管道连接到 Windows 上的 MySQL 服务器。此选项对应于C API 函数的MYSQL_OPT_NAMED_PIPE 选项。mysql_options()该值未使用。

  • OPT_READ_TIMEOUT

    每次尝试从服务器读取的超时时间（以秒为单位）。此选项对应于 C API 函数的MYSQL_OPT_READ_TIMEOUT选项 。mysql_options()该值是一个无符号整数。

  • OPT_RECONNECT

    如果发现连接丢失，启用或禁用自动重新连接到服务器。此选项对应于C API 函数的MYSQL_OPT_RECONNECT选项 。mysql_options()该值是一个布尔值。默认为假。

  • OPT_REPORT_DATA_TRUNCATION

    error使用结构成员 为准备好的语句启用或禁用数据截断错误报告MYSQL_BIND。此选项对应于 C API 函数的MYSQL_REPORT_DATA_TRUNCATION选项 。mysql_options()该值是一个布尔值。

  • OPT_TLS_VERSION

    指定加密连接允许的协议。选项值是包含一个或多个协议名称的逗号分隔列表的字符串。例子： 

    connection_properties["OPT_TLS_VERSION"] = sql::SQLString("TLSv1.1,TLSv1.2");

    允许的值取决于用于编译 MySQL 的 SSL 库：TLSv1, TLSv1.1, TLSv1.2如果使用 OpenSSL； TLSv1以及TLSv1.1是否使用了 yaSSL。默认是允许所有可用的协议。

    有关 MySQL 中加密协议的更多信息，请参阅 加密连接 TLS 协议和密码。

    此选项是在 Connector/C++ 1.1.8 中添加的。

  • OPT_WRITE_TIMEOUT

    每次尝试写入服务器的超时秒数。此选项对应于 C API 函数的MYSQL_OPT_WRITE_TIMEOUT选项 。mysql_options()该值是一个无符号整数。

  • password

    客户端 MySQL 帐户的密码。此选项对应于C API 函数的passwd参数 。mysql_real_connect()该值是一个字符串。

  • pipe

    Windows 系统上到本地主机的命名管道连接的命名管道的名称。该值是一个字符串。

  • pluginDir

    在其中查找客户端插件的目录。此选项对应于C API 函数的MYSQL_PLUGIN_DIR选项。mysql_options()该值是一个字符串。

    此选项是在 Connector/C++ 1.1.5 中添加的。

  • port

    TCP/IP 连接的端口号。此选项对应于C API 函数的port参数 。mysql_real_connect()该值是一个无符号整数。

  • postInit

    此选项类似于preInit，但语句在驱动程序初始化后执行。该值是一个字符串。

    此选项是在 Connector/C++ 1.1.2 中添加的。

  • preInit

    包含要在驱动程序初始化之前执行的语句的字符串。此选项对应于 C API 函数的MYSQL_INIT_COMMAND选项 。mysql_options()该值是一个字符串。

    有关显示使用此选项重置过期密码的示例，请参阅 第 6.7 节，“连接到具有过期密码的帐户”。

    此选项是在 Connector/C++ 1.1.2 中添加的。

  • readDefaultFile

    从命名的选项文件而不是从 my.cnf. 此选项对应于 C API 函数的MYSQL_READ_DEFAULT_FILE选项 。mysql_options()该值是一个字符串。

    此选项是在 Connector/C++ 1.1.5 中添加的。

  • readDefaultGroup

    从指定的组 my.cnf或指定的文件中 读取选项readDefaultFile。此选项对应于C API 函数的MYSQL_READ_DEFAULT_GROUP选项 。mysql_options()该值是一个字符串。

    此选项是在 Connector/C++ 1.1.5 中添加的。

  • rsaKey

    包含服务器 RSA 公钥的文件的路径名。此选项对应于 C API 函数的MYSQL_SERVER_PUBLIC_KEY选项 。mysql_options()该值是一个字符串。

  • schema

    默认数据库名称。此选项对应于 C API 函数的db参数 。mysql_real_connect()该值是一个字符串。

  • socket

    Unix 域套接字文件的名称，用于到 Unix 和类 Unix 系统上的本地主机的套接字文件连接。此选项对应于C API 函数的socket参数。mysql_real_connect()该值是一个字符串。

  • sslCA

    包含可信 SSL CA 列表的 PEM 格式文件的路径。此选项对应于 C API 函数的MYSQL_OPT_SSL_CA选项 。mysql_options()该值是一个字符串。

  • sslCAPath

    包含 PEM 格式的可信 SSL CA 证书的目录的路径。此选项对应于 C API 函数的MYSQL_OPT_SSL_CAPATH选项 。mysql_options()该值是一个字符串。

  • sslCert

    用于建立安全连接的 PEM 格式的 SSL 证书文件的名称。此选项对应于 C API 函数的MYSQL_OPT_SSL_CERT选项 。mysql_options()该值是一个字符串。

  • sslCipher

    SSL 加密的允许密码列表。此选项对应于C API 函数的MYSQL_OPT_SSL_CIPHER 选项。mysql_options()该值是一个字符串。

  • sslCRL

    包含 PEM 格式的证书吊销列表的文件的路径。此选项对应于 C API 函数的MYSQL_OPT_SSL_CRL选项 。mysql_options()该值是一个字符串。

    此选项是在 Connector/C++ 1.1.4 中添加的。

  • sslCRLPath

    包含 PEM 格式的证书吊销列表的文件所在目录的路径。此选项对应于C API 函数的MYSQL_OPT_SSL_CRLPATH 选项。mysql_options()该值是一个字符串。

    此选项是在 Connector/C++ 1.1.4 中添加的。

  • sslEnforce

    是否要求连接使用 SSL。此选项对应于C API 函数的MYSQL_OPT_SSL_ENFORCE 选项。mysql_options()该值是一个布尔值。

  • sslKey

    用于建立安全连接的 PEM 格式的 SSL 密钥文件的名称。此选项对应于 C API 函数的MYSQL_OPT_SSL_KEY选项 。mysql_options()该值是一个字符串。

  • sslVerify

    启用或禁用根据连接到服务器时使用的主机名验证其证书中服务器的公用名值。此选项对应于 C API 函数的MYSQL_OPT_SSL_VERIFY_SERVER_CERT选项。mysql_options()该值是一个布尔值。

    此选项是在 Connector/C++ 1.1.4 中添加的。

  • useLegacyAuth

    是否允许连接到不支持 MySQL 4.1.1 及更高版本中使用的密码散列的服务器。该选项对应于C API函数的MYSQL_SECURE_AUTH选项mysql_options()，只是意义与 useLegacyAuth逻辑相反 MYSQL_SECURE_AUTH。例如，要禁用安全身份验证，请传递useLegacyAuth true 值。该值是一个布尔值。

    此选项是在 Connector/C++ 1.1.4 中添加的。

  • userName

    要使用的 MySQL 帐户的用户名。此选项对应于C API 函数的user参数 。mysql_real_connect()该值是一个字符串。