Connect to Azure Database for MariaDB with redirection

• 06/08/2020
• 4 minutes to read

In this article

This topic explains how to connect an application your Azure Database for MariaDB server with redirection mode. 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

Sign in to the Azure portal. Create an Azure Database for MariaDB server with engine version 10.2 or 10.3.

For details, refer to how to create an Azure Database for MariaDB server using the Azure portal or Azure CLI.

Enable redirection

On your Azure Database for MariaDB server, configure the redirect_enabled parameter to ON to allow connections with redirection mode. To update this server parameter, use the Azure portal or Azure CLI.

Support for redirection in PHP applications is available through the mysqlnd_azure extension, developed by Microsoft.

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.

Redirection logic

The redirection behavior is determined by the value of mysqlnd_azure.enableRedirect. The table below outlines the behavior of redirection based on the value of this parameter beginning in version 1.1.0+.

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. The valid values are off (acts similarly as the behavior outlined in the table below) and on (acts like preferred in the table below).

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 Linux

Prerequisites

• PHP versions 7.2.15+ and 7.3.2+
• PHP PEAR
• php-mysql
• Azure Database for MariaDB server

1. Install mysqlnd_azure with PECL. It is recommended to use version 1.1.0+.

   sudo pecl install mysqlnd_azure
   

2. Locate the extension directory (extension_dir) by running the below:

   php -i | grep "extension_dir"
   

3. Change directories to the returned folder and ensure mysqlnd_azure.so is located in this folder.

4. 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. Create a new .ini file for mysqlnd_azure. 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. For example, if mysqlnd .ini is named 10-mysqlnd.ini, name the mysqlnd ini as 20-mysqlnd-azure.ini.

7. Within the new .ini file, add the following lines to enable redirection.

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

Windows

Prerequisites

• PHP versions 7.2.15+ and 7.3.2+
• php-mysql
• Azure Database for MariaDB server

1. Determine if you are running a x64 or x86 version of PHP by running the following command:

   php -i | findstr "Thread"
   

2. Download the corresponding x64 or x86 version of the mysqlnd_azure DLL from PECL that matches your version of PHP. It is recommended to use version 1.1.0+.

3. Extract the zip file and find the DLL named php_mysqlnd_azure.dll.

4. Locate the extension directory (extension_dir) by running the below command:

   php -i | find "extension_dir"
   

5. Copy the php_mysqlnd_azure.dll file into the directory returned in step 4.

6. Locate the PHP folder containing the php.ini file using the following command:

   php -i | find "Loaded Configuration File"
   

7. Modify the php.ini file and add the following extra lines to enable redirection.

   Under the Dynamic Extensions section:

   extension=mysqlnd_azure
   

   Under the Module Settings section:

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

Confirm redirection

You can also confirm redirection is configured with the below sample PHP code. 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.azure.com';
$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.