使用重定向连接到 Azure Database for MariaDBConnect to Azure Database for MariaDB with redirection

本主题介绍了如何使用重定向模式将应用程序连接到 Azure Database for MariaDB 服务器。This topic explains how to connect an application your Azure Database for MariaDB server with redirection mode. 重定向是为了减小客户端应用程序与 MariaDB 服务器之间的网络延迟,因为它允许应用程序直接连接到后端服务器节点。Redirection aims to reduce network latency between client applications and MariaDB servers by allowing applications to connect directly to backend server nodes.

准备阶段Before you begin

登录到 Azure 门户Sign in to the Azure portal. 使用引擎版本 10.2 或 10.3 创建 Azure Database for MariaDB 服务器。Create an Azure Database for MariaDB server with engine version 10.2 or 10.3.

有关详细信息,请参阅如何使用 Azure 门户Azure CLI 创建 Azure Database for MariaDB 服务器。For details, refer to how to create an Azure Database for MariaDB server using the Azure portal or Azure CLI.

启动重定向Enable redirection

在 Azure Database for MariaDB 服务器中,将 redirect_enabled 参数配置为 ON 以允许与重定向模式建立连接。On your Azure Database for MariaDB server, configure the redirect_enabled parameter to ON to allow connections with redirection mode. 要更新该服务器参数,请使用 Azure 门户Azure CLITo update this server parameter, use the Azure portal or Azure CLI.

PHPPHP

PHP 应用程序中的重定向支持是通过 Microsoft 开发的 mysqlnd_azure 扩展提供的。Support for redirection in PHP applications is available through the mysqlnd_azure extension, developed by Microsoft.

可以通过 PECL 将 mysqlnd_azure 扩展添加到 PHP 应用程序,我们强烈建议通过官方发布的 PECL 包来安装和配置该扩展。The mysqlnd_azure extension is available to add to PHP applications through PECL and it is highly recommended to install and configure the extension through the officially published PECL package.

重要

PHP mysqlnd_azure 扩展对重定向的支持目前以预览版提供。Support for redirection in the PHP mysqlnd_azure extension is currently in preview.

重定向逻辑Redirection logic

重要

从版本 1.1.0 开始,重定向逻辑/行为已更新,建议使用版本 1.1.0+。Redirection logic/behavior beginning version 1.1.0 was updated and it is recommended to use version 1.1.0+.

重定向行为由 mysqlnd_azure.enableRedirect 的值决定。The redirection behavior is determined by the value of mysqlnd_azure.enableRedirect. 下表概述了从版本 1.1.0+ 开始,基于此参数值的重定向行为。The table below outlines the behavior of redirection based on the value of this parameter beginning in version 1.1.0+.

如果使用的是旧版 mysqlnd_azure 扩展(版本 1.0.0-1.0.3),则重定向行为由 mysqlnd_azure.enabled 的值决定。If you are using an older version of the mysqlnd_azure extension (version 1.0.0-1.0.3), the redirection behavior is determined by the value of mysqlnd_azure.enabled. 有效值为 off(行为与下表中所述的行为类似)和 on(行为类似于下表中的 preferred)。The valid values are off (acts similarly as the behavior outlined in the table below) and on (acts like preferred in the table below).

mysqlnd_azure enableRedirect 值mysqlnd_azure.enableRedirect value 行为Behavior
off0off or 0 不会使用重定向。Redirection will not be used.
on1on or 1 - 如果连接未在驱动程序端使用 SSL,则不会建立连接。- If the connection does not use SSL on the driver side, no connection will be made. 将返回以下错误:“mysqlnd_azure.enableRedirect 为 on,但连接字符串中未设置 SSL 选项。仅在使用了 SSL 的情况下才支持重定向。”The following error will be returned: "mysqlnd_azure.enableRedirect is on, but SSL option is not set in connection string. Redirection is only possible with SSL."
- 如果在驱动程序端使用了 SSL,但服务器不支持重定向,则第一个连接将中止并返回以下错误:“由于 MariaDB 服务器上未启用重定向或者网络数据包不符合重定向协议,连接已中止。”- If SSL is used on the driver side, but redirection is not supported on the server, the first connection is aborted and the following error is returned: "Connection aborted because redirection is not enabled on the MariaDB server or the network package doesn't meet redirection protocol."
- 如果 MariaDB 服务器支持重定向,但重定向的连接出于任何原因而失败,则还会中止第一个代理连接。- If the MariaDB server supports redirection, but the redirected connection failed for any reason, also abort the first proxy connection. 返回重定向连接错误。Return the error of the redirected connection.
preferred2preferred or 2
(默认值)(default value)
- mysqlnd_azure 将尽可能使用重定向。- mysqlnd_azure will use redirection if possible.
- 如果连接未在驱动程序端使用 SSL,则服务器不支持重定向,或者重定向的连接由于任何非致命原因而无法连接,而代理连接仍然有效,则服务器将回退到第一个代理连接。- If the connection does not use SSL on the driver side, the server does not support redirection, or the redirected connection fails to connect for any non-fatal reason while the proxy connection is still a valid one, it will fall back to the first proxy connection.

本文档的后续部分将概述如何使用 PECL 安装 mysqlnd_azure 扩展并设置此参数的值。The subsequent sections of the document will outline how to install the mysqlnd_azure extension using PECL and set the value of this parameter.

Ubuntu LinuxUbuntu Linux

先决条件Prerequisites

  • PHP 版本 7.2.15+ 和 7.3.2+PHP versions 7.2.15+ and 7.3.2+
  • PHP PEARPHP PEAR
  • php-mysqlphp-mysql
  • Azure Database for MariaDB 服务器Azure Database for MariaDB server
  1. 使用 PECL 安装 mysqlnd_azureInstall mysqlnd_azure with PECL. 建议使用版本 1.1.0+。It is recommended to use version 1.1.0+.

    sudo pecl install mysqlnd_azure
    
  2. 运行以下命令找到扩展目录 (extension_dir):Locate the extension directory (extension_dir) by running the below:

    php -i | grep "extension_dir"
    
  3. 将目录更改为返回的文件夹,并确保 mysqlnd_azure.so 位于此文件夹中。Change directories to the returned folder and ensure mysqlnd_azure.so is located in this folder.

  4. 运行以下命令找到 .ini 文件所在的文件夹:Locate the folder for .ini files by running the below:

    php -i | grep "dir for additional .ini files"
    
  5. 将目录更改为此返回的文件夹。Change directories to this returned folder.

  6. mysqlnd_azure 创建新的 .ini 文件。Create a new .ini file for mysqlnd_azure. 确保名称的字母表顺序在 mysqnld 的字母顺序后面,因为模块是根据 ini 文件的名称顺序加载的。Make sure the alphabet order of the name is after that of mysqnld, since the modules are loaded according to the name order of the ini files. 例如,如果 mysqlnd .ini 命名为 10-mysqlnd.ini,请将 mysqlnd ini 命名为 20-mysqlnd-azure.iniFor example, if mysqlnd .ini is named 10-mysqlnd.ini, name the mysqlnd ini as 20-mysqlnd-azure.ini.

  7. 在新的 .ini 文件中,添加以下行以启用重定向。Within the new .ini file, add the following lines to enable redirection.

    extension=mysqlnd_azure
    mysqlnd_azure.enableRedirect = on/off/preferred
    

WindowsWindows

先决条件Prerequisites

  • PHP 版本 7.2.15+ 和 7.3.2+PHP versions 7.2.15+ and 7.3.2+
  • php-mysqlphp-mysql
  • Azure Database for MariaDB 服务器Azure Database for MariaDB server
  1. 运行以下命令来确定运行的是 x64 还是 x86 版本的 PHP:Determine if you are running a x64 or x86 version of PHP by running the following command:

    php -i | findstr "Thread"
    
  2. PECL 中下载与你的 PHP 版本匹配的相应 x64 或 x86 版 mysqlnd_azure DLL。Download the corresponding x64 or x86 version of the mysqlnd_azure DLL from PECL that matches your version of PHP. 建议使用版本 1.1.0+。It is recommended to use version 1.1.0+.

  3. 解压缩 zip 文件,并找到名为 php_mysqlnd_azure.dll 的 DLL。Extract the zip file and find the DLL named php_mysqlnd_azure.dll.

  4. 运行以下命令找到扩展目录 (extension_dir):Locate the extension directory (extension_dir) by running the below command:

    php -i | find "extension_dir"
    
  5. php_mysqlnd_azure.dll 文件复制到步骤 4 返回的目录中。Copy the php_mysqlnd_azure.dll file into the directory returned in step 4.

  6. 使用以下命令找到包含 php.ini 文件的 PHP 文件夹:Locate the PHP folder containing the php.ini file using the following command:

    php -i | find "Loaded Configuration File"
    
  7. 修改 php.ini 文件,并添加以下额外的行来启用重定向。Modify the php.ini file and add the following extra lines to enable redirection.

    在“Dynamic Extensions”部分下:Under the Dynamic Extensions section:

    extension=mysqlnd_azure
    

    在“Module Settings”部分下:Under the Module Settings section:

    [mysqlnd_azure]
    mysqlnd_azure.enableRedirect = on/off/preferred
    

确认重定向Confirm redirection

还可以使用以下示例 PHP 代码来确认是否已配置重定向。You can also confirm redirection is configured with the below sample PHP code. 创建名为 mysqlConnect.php 的 PHP 文件并粘贴以下代码。Create a PHP file called mysqlConnect.php and paste the below code. 使用你自己的值更新服务器名称、用户名和密码。Update the server name, username, and password with your own.

<?php
$host = '<yourservername>.mariadb.database.chinacloudapi.cn';
$username = '<yourusername>@<yourservername>';
$password = '<yourpassword>';
$db_name = 'testdb';
 echo "mysqlnd_azure.enableRedirect: ", ini_get("mysqlnd_azure.enableRedirect"), "\n";
 $db = mysqli_init();
 //The connection must be configured with SSL for redirection test
 $link = mysqli_real_connect ($db, $host, $username, $password, $db_name, 3306, NULL, MYSQLI_CLIENT_SSL);
 if (!$link) {
    die ('Connect error (' . mysqli_connect_errno() . '): ' . mysqli_connect_error() . "\n");
 }
 else {
   echo $db->host_info, "\n"; //if redirection succeeds, the host_info will differ from the hostname you used used to connect
   $res = $db->query('SHOW TABLES;'); //test query with the connection
   print_r ($res);
   $db->close();
 }
?>

后续步骤Next steps

有关连接字符串的详细信息,请参阅连接字符串For more information about connection strings, see Connection Strings.