The source code here is a PHP extension implemented using mysqlnd plugin API (https://www.php.net/manual/en/mysqlnd.plugin.php), which provides redirection feature support. The extension is also available on PECL website at https://pecl.php.net/package/mysqlnd_azure.
Before 1.1.0, the option is with name mysqlnd_azure.enabled. Valid values are on/off, and the option "on" supports fallback logic. The detailed usage of the option enableRedirect is as follows:
(Version before 1.1.0. Config name: mysqlnd_azure.enabled. Valid value: on/off. Default value: off)
| off(0) | - It will not use redirection. |
| on(1) | - It will use redirection if possible (Connection is with SSL and Server supports/needs redirection). - If connection does not use SSL, or server does not support redirection, or redirected connection fails to connect for any non-fatal reason while the proxy connection is still a valid one, it will fallback to the first proxy connection. |
Since 1.1.0, the logic changes as follows:
(Version >= 1.1.0. Config name: mysqlnd_azure.enableRedirect. Valid value: on/off/preferred. Default value: preferred)
| off(0) | - Redirection will not be used. |
| on(1) | - If connection does not use SSL on the driver side, no connection will be made. 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." - 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 MySQL server or the network package doesn't meet redirection protocol." - If the MySQL server supports redirection, but the redirected connection failed for any reason, also abort the first proxy connection. Return the error of the redirected connection. |
| preferred(2) | - It will use redirection if possible. - 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 |
Extension name: mysqlnd_azure
Required PHP min version: PHP7.2.15+, PHP7.3.2+, PHP7.4.0+.
Valid version: The latest version is 1.1.1. Please check package.xml for changelog details. Following are some special notice for certain versions:
Following is a brief guide of how to install using pecl or build and test the extension from source.
The PECL link is available at https://pecl.php.net/package/mysqlnd_azure. Following steps assume that php and php-mysql have already been normally installed on each platform.
Example to install required tools for php7.3 on Ubuntu:
Example to install required tools for php7.3 on Redhat 7.4:
sudo pecl install mysqlnd_azure
For beta version like 1.0.3RC, please specify the version number, e.g. pecl install mysqlnd_azure-1.0.3RC
Download the corresponding dll package from the DLL link on https://pecl.php.net/package/mysqlnd_azure. Extract the zip file, find the dll file named with php_mysqlnd_azure.dll, and put it under extension_dir (Follow the configure step below to get the value).
You may use following command to check the thread safety setting of the php:
If you cannnot determine the x86/64 version of the php, you may use following script to figure out:
switch(PHP_INT_SIZE) {
case 4:
echo '32-bit version of PHP', "\n";
break;
case 8:
echo '64-bit version of PHP', "\n";
break;
default:
echo 'PHP_INT_SIZE is ' . PHP_INT_SIZE, "\n";
}The configuration step is same with that of build from source. Check content below for Linux or Windows platform.
Install phpize for build using following command
Ubuntu: apt-get install php7.x-dev
//use the version that corresponds to your PHP version, i.e. if you use PHP7.3, use php7.3-dev here
Redhat: yum install php7x-php-devel
//e.g. php72-php-devel. after install if you still cannot find phpize or php-config, you need to link phpize and php-config in order to make it work correctly:
ln -s /opt/remi/php72/root/bin/phpize /usr/bin/phpize
ln -s /opt/remi/php72/root/bin/php-config /usr/bin/php-config
//If you cannot find the package, there may be a need to renable related repository, e.g. enable REMI,EPEL using following command
rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
rpm -Uvh http://rpms.famillecollet.com/enterprise/remi-release-7.rpm
Then you can run make install to put the .so to your php so library. However this may not add the configuration file for you automatically. So the alternative way is using following steps:
There need more steps to build the extension under Windows, and it willl use the php-sdk-binary-tools developed for help. The detailed step is decribed on https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2. And it is repeated here:
If compiling PHP 7.2+: Install Visual Studio 2017 If compiling PHP 7.4+: Install Visual Studio 2019
If compiling PHP 7.2+ open either the “VS2017 x64 Native Tools Command Prompt” or the “VS2017 x86 Native Tools Command Prompt”.
Fetch the latest stable SDK tag from https://github.com/Microsoft/php-sdk-binary-tools The new PHP SDK is required, when building PHP 7.2+ Read the PHP SDK specific notes on the Github repository page
Run the phpsdk_buildtree batch script which will create the desired directory structure:
The phpsdk_buildtree script will create the path according to the currently VC++ version used and switch into the newly created directory. cd to C:\php-sdk\phpdev\vX##\x##, where: vX## is the compiler version you are using (eq vc14 or vs16) x## is your architecture (x86 or x64) For example: C:\php-sdk\phpdev\vc15\x64\ for PHP7.2+
Under the folder, git clone php source code from https://github.com/php/php-src.git Fecth the related version, e.g. PHP-7.2.20
cd to php-src directory
use the PHP SDK tools to fetch the suitable dependencies automatically for a valid branch by calling
Extract mysqlnd_azure code https://github.com/microsoft/mysqlnd_azure to the php-source-code-folder\ext\mysqlnd_azure(a new directory need to create), e.g. to C:\php-sdk\phpdev\vc15\x64\php-src\ext\mysqlnd_azure. Or create another folder with name "pecl" which is in parallel with php source, e.g. C:\php-sdk\phpdev\vc15\x64\pecl, and extract the code there in folder mysqlnd_azure. After this, the code directory should look like C:\php-sdk\phpdev\vc15\x64\php-src\ext\mysqlnd_azure, or C:\php-sdk\phpdev\vc15\x64\pecl\mysqlnd_azure
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, 'your-hostname-with-redirection-enabled', 'user@host', 'password', "db", 3306, NULL, MYSQLI_CLIENT_SSL);
if (!$link) {
die ('Connect error (' . mysqli_connect_errno() . '): ' . mysqli_connect_error() . "\n");
}
else {
echo $db->host_info, "\n"; //if redrection succeed, you will find the host_info differ from your-hostname used to connect
$res = $db->query('SHOW TABLES;'); //test query with the connection
print_r ($res);
$db->close();
}To troubleshoot issues when using this extension, you may follow the steps described in troubleshooting.md for initial troubleshooting.