Instalación/Configuración
PHP Manual

Fichero de configuración del complemento (>=1.1.x)

Nota: Registro de cambios: Característica añadida en PECL/mysqlnd_ms 1.1.0-beta

La descripción de abajo se aplica a PECL/mysqlnd_ms >= 1.1.0-beta. No es válida para versiones anteriores.

El complemento usa su propio fichero de configuración. Éste guarda información sobre el servidor maestro de replicación MySQL, los servidores esclavos de replicación MySQL, la política de elección (equilibrado de carga), la estrategia de tolerancia a fallos, y el uso de conexiones retardadas.

El complemento carga su fichero de configuración al comienzo de una petición web. Entonces, es almacenado en la memoria caché y utilizado durante el resto de la petición web. De esta forma, no hay necesidad de reiniciar PHP después de utilizar el fichero de configuración. Los cambios de éste estarán activos casi instantáneamente.

La directiva de configuración de PHP mysqlnd_ms.ini_file se utiliza para establecer el fichero de configuración del complemento. Observe que dicha direcitiva no puede ser evaluada para cada petición web. Por lo tanto, el cambio del nombre del fichero de configuración del complemento o de su ubicación puede requerir el reinicio de PHP. Sin embargo, no es necesario tal reinicio para leer los cambios si se actualiza un fichero de configuración del complemento ya existente.

El uso y el análisis de JSON es eficiente, ya que con JSON es más sencillo expresar estructuras de datos jerárquicas que con el formato estándar de php.ini.

Ejemplo #1 Convertir un array de PHP (hash) al formato JSON

O alternativamente, un desarrollador puede preferir la sintaxis de arrays por estar más familiarizado con ella. Este ejemplo demuestra cómo un desarrolador podría convertir un array de PHP a JSON.

<?php
$config = array(
  "myapp" => array(
    "master" => array(
      "master_0" => array(
        "host"   => "localhost",
        "socket" => "/tmp/mysql.sock",
      ),
    ),
    "slave" => array(),
  ),
);

file_put_contents("mysqlnd_ms.ini", json_encode($config, JSON_PRETTY_PRINT));
printf("mysqlnd_ms.ini file created...\n");
printf("Dumping file contents...\n");
printf("%s\n", str_repeat("-", 80));
echo file_get_contents("mysqlnd_ms.ini");
printf("\n%s\n", str_repeat("-", 80));
?>

El resultado del ejemplo sería:

mysqlnd_ms.ini file created...
Dumping file contents...
--------------------------------------------------------------------------------
{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": [

        ]
    }
}
--------------------------------------------------------------------------------

Un fichero de configuración del complemento consta de una o más secciones. Éstas están representadas por las propiedades de nivel superior del objeto codificado en el fichero JSON. Las secciones también podrían llamarse nombres de configuración.

Las aplicciones hacen referencia a las secciones por su nombre. Las aplicaciones usan los nombres de las secciones como el parámetro 'host' (servidor) de los distintos métodos de conexión de las extensiones mysqli, mysql y PDO_MYSQL. Durante la conexión, el complemento de mysqlnd compara el nombre del equipo anfitrión con todos los nombres de las secciones del fichero de configuración del complemento. Si el nombre del equipo anfitrión y el nombre de la sección coinciden, el complemento cargará la configuración de esa sección.

Ejemplo #2 Ejemplo del uso de nombres de sección

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27"
            },
            "slave_1": {
                "host": "192.168.2.27",
                "port": 3306
            }
        }
    },
    "localhost": {
        "master": [
            {
                "host": "localhost",
                "socket": "\/path\/to\/mysql.sock"
            }
        ],
        "slave": [
            {
                "host": "192.168.3.24",
                "port": "3305"
            },
            {
                "host": "192.168.3.65",
                "port": "3309"
            }
        ]
    }
}
<?php
/* Todas las conexiones siguientes tendrán equilibrado de carga */
$mysqli = new mysqli("myapp", "nombre_usuario", "contraseña", "base_datos");
$pdo = new PDO('mysql:host=myapp;dbname=base_datos', 'nombre_usuario', 'contraseña');
$mysql = mysql_connect("myapp", "nombre_usuario", "contraseña");

$mysqli = new mysqli("localhost", "nombre_usuario", "contraseña", "base_datos");
?>

Los nombres de sección son cadenas de texto. Es válido usar nombres de sección como 192.168.2.1, 127.0.0.1 o localhost. Si, por ejemplo, una aplicación se conexta a localhost y existe una sección de configuración del complemento llamada localhost, la semántica de la operación de conexión se cambia. La aplicación ya no usará únicamente el servidor MySQL que se ejecuta en el equipo anfitrión localhost, sino que el complemento iniciará el equilibrado de carga de las consultas MySQL siguiendo las reglas de la sección de configuración localhost. De esta manera se puede realizar el equilibrado de carga de consultas desde una aplicación sin cambiar el código fuente de la misma. Recuerde que tal configuración puede no contribuir a la legibilidad global del código fuente de las aplicaciones. El uso de nombres de sección combinado con nombres de equipos anfitriones debería ser el último recurso.

Cada sección de configuración contiene, como mínimo, una lista de sevidores maestros y una lista de servidores esclavos. La lista de maestros se configura con la palabra clave master, mientras que la lista de esclavos se configura con la palabra clave slave. El no proporcionar una lista de esclavos resultará en un error fatal de nivel E_ERROR, aunque la lista de esclavos puede estar vacía. Es posible prohibir esclavos. Sin embargo, esto solo se recomienda para clústeres sincrónicos. Véanse también los clústeres admitidos. La parte principal de esta documentación se centra en el uso de clústeres de replicación MySQL asincrónicos.

Las listas de servidores maestros y esclavos se pueden indexar opcionalmente mediante nombres simbólicos para los servidores que describen. De forma alternativa, se puede utlizar un array con descripciones de los servidores esclavos y maestros.

Ejemplo #3 Lista de esclavos anónimos

"slave": [
    {
        "host": "192.168.3.24",
        "port": "3305"
    },
    {
        "host": "192.168.3.65",
        "port": "3309"
    }
]

Una lista de servidores anónimos está codificada por el tipo array de JSON. Opcionalmente, se pueden usar los nombres simbólicos para indexar los servidores esclavos o maestros de una lista de servidores, realizándolo mediante el tipo objeto de JSON.

Ejemplo #4 Lista de maestros usando nombres simbólicos

"master": {
    "master_0": {
        "host": "localhost"
    }
}

Se recomienda indexar las listas de servidores con nombres de servidores simbólicos. Los sobrenombres se mostrarán en los mensajes de error.

mysqlnd_ms preserva el orden de los servidores y lo toma en cuenta. Si, por ejemplo, se configura una estrategia de equilibrado de carga de rotación, la primera sentencia SELECT será ejecutada en el esclavo que aparece en primer lugar en la lista de servidores esclavos.

Un servidor configurado puede ser descrito con host, port, socket, db, user, password y connect_flags. Es obligatorio establecer el equipo anfitrión del servidor de la base de datos mediante la palabra clave host. Todos los demás ajustes son opcionales.

Ejemplo #5 Palabras clave para configurar un servidor

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "db_server_host",
                "port": "db_server_port",
                "socket": "db_server_socket",
                "db": "database_resp_schema",
                "user": "user",
                "password": "password",
                "connect_flags": 0
            }
        },
        "slave": {
            "slave_0": {
                "host": "db_server_host",
                "port": "db_server_port",
                "socket": "db_server_socket"
            }
        }
    }
}

Si se omite un ajuste, el complemento usará el valor proporcionado por la llamada a la API hecha por el usuario utilizada para abrir la conexión. Véase el ejemplo de uso de nombres de sección de arriba.

El formato del fichero de configuración ha sido cambiado en la versión 1.1.0-beta para permitir los filtros encadencados. Los filtros son los responsables de filtrar la lista de servidores configurados para identificar un servidor para que ejecute una sentencia dada. Los filtros se configuran con la palabra clave filter. Éstos son ejecutados por mysqlnd_ms en el orden en que aparecen. La definción de filtros es opcional. Una sección de configuración del fichero de configuración del complemento no necesita tener una entrada filters.

Los filtros reemplazan al ajuste pick[] de versiones anteriores. Los nuevos filtros random y roundrobin proporcionan la misma funcionalidad.

Ejemplo #6 El nuevo filtro roundrobin, funcionalidad antigua

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            },
            "slave_1": {
                "host": "192.168.78.137",
                "port": "3306"
            }
        },
        "filters": {
            "roundrobin": [

            ]
        }
    }
}

La función mysqlnd_ms_set_user_pick_server() ha sido eliminada. El establecimiento de una llamada de retorno ahora se realiza con el filtro user. Algunos filtros aceptan parámetros. El filtro user requiere y acepta el parámetro obligatorio callback para establecer la llamada de retorno que antes se establecía a través de la función mysqlnd_ms_set_user_pick_server().

Ejemplo #7 El filtro user reemplaza a mysqlnd_ms_set_user_pick_server()

"filters": {
    "user": {
        "callback": "pick_server"
    }
}

He aquí una breve explicación de las directivas de configuración que se pueden usar.

master array o object

Lista de los servidores maestros de replicación MySQL. La lista es del tipo array de JSON, para declarar una lista anónima de servidores, o del tipo objeto de JSON. Por favor, véanse los ejemplos de arriba.

Es obligatorio establecer al menos un servidor maestro. El complemento emitirá un error de tipo E_ERROR si el usuario no ha proporcionado una lista de servidores maestros en una sección de configuración. El error fatal puede ser (mysqlnd_ms) Section [master] doesn't exist for host [name_of_a_config_section] in %s on line %d ((mysqlnd_ms) La sección [master] no existe para el equipo anfitrión [nombre_de_una_sección_de_configurción] en %s en la línea %d).

Un servidor se describe con las palabras clave host, port, socket, db, user, password y connect_flags. Es obligatorio proporcionar al menos un valor para host. Si no se proporcionan cualesquiera de los otros valores, se tomarán de la llamada de conexión del usuario a la API, véase también: ejemplo de uso de nombres de sección.

Tabla de las palabras clave de configuración del servidor.

Palabra clave Descripción Versión
host

El equipo anfitrión servidor de las bases de datos. Es un ajuste obligatorio. Si no se proporcina causará un error de tipo E_RECOVERABLE_ERROR cuando el complemento intente conectarse al servidor. El mensaje de error puede ser (mysqlnd_ms) Cannot find [host] in [%s] section in config in %s on line %d ((mysqlnd_ms) No se pudo encontrar [host] en la sección [%s] de configuración en %s en la línea %d).

Desde 1.1.0.
port

El puerto TCP/IP del servidor de las bases de datos.

Desde 1.1.0.
socket

El socket de dominio Unix del servidor de las bases de datos.

Desde 1.1.0.
db

La base de datos (esquema).

Desde 1.1.0.
user

El usuario de la base de datos MySQL.

Desde 1.1.0.
password

La constraseña del usuario de la base de datos MySQL.

Desde 1.1.0.
connect_flags

Banderas de conexión.

Desde 1.1.0.

El complemento únicamente admite el uso de un servidor maestro. Existe un ajuste experimental para habilitar el soporte de múltiples maestros. Los detalles no están documentados. El ajuste sólo se menciona para desarrollo.

slave array o object

Lista de uno o más servidores esclavos de replicación MySQL. La sintaxis es idéntica a la de lo servidores maestros, véase master más arriba para más detalles.

El complemento admite el uso de uno o más servidores esclavos.

Es obligatorio establecer una lista de servidores esclavos. El complemento notificará un error de tipo E_ERROR si no se proporciona slave para una sección de configuración. El mensaje de error fatal puede ser (mysqlnd_ms) Section [slave] doesn't exist for host [%s] in %s on line %d ((mysqlnd_ms) La sección [slave] no existe para el equipo anfitrión [%s] en %s en la línea %d). Observe que es válido usar una lista de servidores esclavos vacía. Este error ha sido introducido para evitar que no se establezcan esclavos de forma accidental si se olvida el ajuste slave. Es posible configurar un único maestro si se utiliza una lista de servidores esclavos vacía.

Si se configura una lista de esclavos vacía y se intenta ejecutar una sentencia en un esclavo, el complemento podría emitir una advertencia como (mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. ((mysqlnd_ms) No se pudo encontrar la conexión esclava apropiada. 0 esclavos de donde elegir) durante la ejecución de la sentencia. Es posible que le siga otra advertencia, como (mysqlnd_ms) No connection selected by the last filter ((mysqlnd_ms) El último filtro no seleccionó ninguna conexión).

global_transaction_id_injection array o object

La configuración del identificador de transacciones global está relacionada tanto con el uso de la característica del ID de transacciones global interno del servidor como con la emulación en el lado del cliente.

Palabra clave Descripción Versión
fetch_last_gtid

Senetencia SQL para acceder al último identificador de transaccioens global. La sentencia SQL se ejecuta si el complemento necesita conocer el identificador de transacciones global más reciente. Este puede ser el caso cuando, por ejemplo, se comprueba el estado de un esclavo de Replicación MySQL. También se usa con mysqlnd_ms_get_last_gtid().

Desde 1.2.0.
check_for_gtid

Sentencia SQL para comprobar si una réplica ha replicado todas las transacciones hasta, e incluyendo a, la buscada. La sentencia SQL se ejecuta cuando se buscan réplicas que pueden ofrecer un nivel mayor de consistencia que la consistencia final. La sentencia puede contener el parámetro de sustitución #GTID, el cual es reemplazado con el identificador de transacciones global buscado por el complemento. Por favor, revise los ejemplos de la guía rápica.

Desde 1.2.0.
report_errors

Si se ha de emitir un error de tipo 'warning' si ocurriera un problema mientras se ejecuta cualquiera de las sentencias SQL configuradas.

Desde 1.2.0.
on_commit

(Solamente para la emulación del ID de transacciones global en el lado del cliente). Sentencia SQL a ejecutar cuando una transacción finaliza y acutaliza el número de secuencia del identificador de transacciones global en el maestro. Por favor, vea los ejemplo de la guía rápida.

Desde 1.2.0.
wait_for_gtid_timeout

Ordena al complemento que espere hasta wait_for_gtid_timeout segundos para que un esclavo se ponga al día cuando se busquen esclavos que puedan proporcionar la consistencia de sesión. Este ajuste limita el tiempo empleado en obtener el estados de los esclavos. Si dicha obtención toma mucho tiempo, el tiempo de espera total empleado puede exceder wait_for_gtid_timeout. El complemento llama a sleep(1) para dormir un segundo entre cada dos obtenciones.

El ajuste se puede usar junto con la emulación en el lado del cliente del complemento y la característica del identificador de transacciones global del lado del servidore de MySQL 5.6.

La espera de que un esclavo replique un GTID en particular necesario para la consistencia de sesión también signifiva estrangular el cliente. El estrangulamiento del cliente reduce indirectamente la carga de escrigura del maestro. A un sistema de replicación basado en copia primaria,, como la Replicación MySQL, se le da más tiempo para alcanzar un estado consistente. Esto puede ser útil, por ejemplo, para aumentar el número de copias de datos para consideraciones de alta disponibilidad, o para prevenir que el maestro sea sobrecargado.

Desde 1.4.0.
filters object

Lista de filtros. Un filtro es el responsable de filtrar la lista de servidores disponibles que puedan ejecutar una setentcia dada. Los filtros se pueden encadenar. Los filtros random y roundrobin reemplazan a la directiva pick[] usada en versiones anteriores para seleccionar una política de equilibrado de carga. El filtro user reemplaza a la función mysqlnd_ms_set_user_pick_server().

Los filtros pueden aceptar parámetros para refinar sus acciones.

Si no está establecida una política de equilibrado de carga, el complemento asumirá el valor predeterminado random_once. La política random_once elige un servidor aleatorio al ejecutar la primera sentencia de solo lectura. Este servidor esclavo se usará para todas las sentencias de solo lectura hasta que finalice la ejecución del script de PHP. No se establece ninguna política de equilibrado de carga y, por lo tanto, toma lugar el valor predeterminado si ni random ni roundrobin son parte de la sección de configuración.

Si una cadena de filtros es configurada de modo que la salida de un filtro que no produzca más de un servidor sea usada como entrada para otro filtro al que se le debería proporcionar más de un servidor, el complemento podría emitir una advertencia sobre una conexión abierta. La advertencia podría ser: (mysqlnd_ms) Error while creating filter '%s' . Non-multi filter '%s' already created. Stopping in %s on line %d ((mysqlnd_ms) Error al crear el filtro '%s' . No se ha creado aún el filtro múltiple '%s'. Detenido en %s en la línea %d). Además, se puede establecer un error de código 2000, el estado sql HY000, y un mensaje de error similar a la advertencia, sobre el gestor de conexión.

Ejemplo #8 Secuencia de filtros inválida

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": [
            "roundrobin",
            "random"
        ]
    }
}
<?php
$enlace = new mysqli("myapp", "root", "", "test");
printf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error());
$enlace->query("SELECT 1 FROM DUAL");
?>

El resultado del ejemplo sería:

PHP Warning:  mysqli::mysqli(): (HY000/2000): (mysqlnd_ms) Error while creating filter 'random' . Non-multi filter 'roundrobin' already created. Stopping in filter_warning.php on line 1
[2000] (mysqlnd_ms) Error while creating filter 'random' . Non-multi filter 'roundrobin' already created. Stopping
PHP Warning:  mysqli::query(): Couldn't fetch mysqli in filter_warning.php on line 3

Filtro: random object

El filtro random introduce las políticas de equilibrado de carga "aleatoria" y "aleatoria una vez", establecidas a través de la directiva pick[] en versiones anteriores.

La política "aleatoria" eligirá un servidor aleatorio siempre que se vaya a ejecutar una sentencia de solo lectura. La estrategia "aleatoria una vez" elige un servidor esclavo aleatorio una vez y continuará usándolo para el resto de la petición web. "Aleatoria una vez" es la predeterminada, si el equilibrado de carga no está configurado a través de un filtro.

Si al filtro random no se le proporciona ningún argumento, permanecerá la política de equilibrado de carga aleatoria.

Ejemplo #9 Equilibrado de carga aleatorio con el filtro random

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            },
            "slave_1": {
                "host": "192.168.78.137",
                "port": "3306"
            }
        },
        "filters": [
            "random"
        ]
    }
}

Opcionalmente, se puede pasar el argumento sticky al filtro. Si se establece el parámetro sticky al string 1, el filtro seguirá la estrategia de equilibrado de carga "aleatoria una vez".

Ejemplo #10 Equilibrado de carga "aleatoria una vez" con el filtro random

{
    "filters": {
        "random": {
            "sticky": "1"
        }
    }
}

Los filtros random y roundrobin admiten el establecimiento de una prioridad, un peso para un servidor, desde PECL/mysqlnd_ms 1.4.0. Si se pasa el argumento weight al filtro, debe asginar un peso para todos los servidores. A los servidores se les debe proporcionar un sobrenombre en las listas de servidores slave y master respectivamente. El alias debe usarse para hacer referencia a servidores para asignarles una prioridad con weight.

Ejemplo #11 Error de referencia

[E_RECOVERABLE_ERROR] mysqli_real_connect(): (mysqlnd_ms) Unknown server 'slave3' in 'random' filter configuration. Stopping in %s on line %d

Usar un sobrenombre erróneo con weight podría resultar en un error similar al mostrado arriba.

Si se omite weight, el peso predeterminado de todos los servidores es uno.

Ejemplo #12 Asignar weight para el equilibrado de carga

{
   "myapp": {
       "master": {
           "master1":{
               "host":"localhost",
               "socket":"\/var\/run\/mysql\/mysql.sock"
           }
       },
       "slave": {
           "slave1": {
               "host":"192.168.2.28",
               "port":3306
           },
           "slave2": {
               "host":"192.168.2.29",
               "port":3306
           },
           "slave3": {
               "host":"192.0.43.10",
               "port":3306
           },
       },
       "filters": {
           "random": {
               "weights": {
                   "slave1":8,
                   "slave2":4,
                   "slave3":1,
                   "master1":1
               }
           }
       }
   }
}

Como promedio, un servidor al que se le asigne un peso de dos será seleccionado el doble que un servidor al que se la haya asignado un peso de uno. Se pueden asignar diferentes pesos para reflejar diferentes tipos de máquinas, para preferir coubicar esclavos que tienen una latencia de red baja o para configurar un servidor de tolerancia a fallos de emergencia. En este último caso, se podría asignar al servidor de emergencia un peso muy bajo en relación con los demás servidores. Por ejemplo, dada la configuración de arriba, slave3 obtendrá solamente el ocho por ciento de las peticiones como media. Mientras que slave1 y slave2 estén ejecutándose, se usarán con poca frecuencia, de forma similar a un servidor de tolerancia a fallos de emergencia. Si ocurre un fallo de slave1 y de slave2, el uso de slave3 aumenta. Por favor, revise las notas sobre la tolerancia a fallos antes de usar weight de esta manera.

El rango de valores válidos del peso es de 1 a 65535.

Los argumentos desconocidos son ingnorados. No se dan advertencias ni errores.

Espera uno o más servidores como entrada. Produce un servidor. Una secuencia de filtros como random, roundrobin, puede causar una advertencia y establecer un mensaje de error sobre el gestor de conexión cuando se ejecute una sentencia.

Listado de los argumentos del filtro.

Palabra clave Descripción Versión
sticky

Habilita o deshabilita la política de equilibrado de carga "aleatoria una vez". Véase más arriba.

Desde 1.2.0.
weight

Asigna un peso o prioridad de equilibrado de carga a un servidor. Por favor, véase la descripción de arriba.

Desde 1.4.0.
Filtro: roundrobin object

Si se utiliza el filtro roundrobin, el complemento iterará sobre la lista de servidores esclavos configurados para elegir un servidor para que ejecute una sentencia. Si el complemento alcanza el final de la lista, volverá al inicio de la misma y eligirá el primer servidor esclavo configurado.

Ejemplo #13 Filtro roundrobin

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": [
            "roundrobin"
        ]
    }
}

Espera uno o más servidores como entrada. Produce un servidor. Una secuencia de filtros como roundrobin, random, puede causar una advertencia y establecer un mensaje de error sobre el gestor de conexión cuando se ejecute una sentencia.

Listado de los argumentos del filtro.

Palabra clave Descripción Versión
weight

Asigna un peso o prioridad de equilibrado de carga a un servidor. Por favor, véase la descipción de arriba.

Desde 1.4.0.
Filtro: user object

El filtro user reemplaza a la función mysqlnd_ms_set_user_pick_server(), la cual ha sido eliminada en la versión 1.1.0-beta. El filtro establece una llamada de retorno para la división de lectura-escritura y la selección del servidor definidas por el usuario.

Las decisiones del mecanismo interno de división de consultas de lecura-escritura pueden ser sobrescritas de dos maneras. La más sencilla es anteponer a una consulta las sugerentecias SQL MYSQLND_MS_MASTER_SWITCH, MYSQLND_MS_SLAVE_SWITCH o MYSQLND_MS_LAST_USED_SWITCH. Al utilizar sugerencias SQL se puede controlar, por ejemplo, si una consulta debería ser enviada al servidor maestro de replicación MySQL o a uno de los servidores esclavos. Mediante la ayuda de sugenrencias SQL no es posible elegir un esclavo en particular para que ejecute una consulta.

Se puede obtener control total en la selección del servidor usando una función de llamada de retorno. Solamente se recomienda el uso de una llamada de retorno para usuarios expertos, ya que ésta ha de cubrir todos los casos que de otro modo manejaría el complemento.

El complemento invorcará a la función de llamada de retorno para seleccionar un servidor de las listas de servidores maestros y esclavos configurados. La función de llamada de retorno inspeccionará la consulta a ejecutar y eligirá un servidor para que ejecute dicha consulta, devolviendo el URI del equipo anfitrión, tal como lo encontró en la lista de maestros y esclavos.

Si las conexiones retardadas están habilitadas y la llamada de retorno elige un servidor esclavo para el que hasta ahora no se ha establecido una conexión, y el establecimiento de la conexión al esclavo falla, el complemento devolverá un error sobre la siguiente acción en la conexión fallida, por ejemplo, al ejecutar una consulta. Es responsabilidad del desarrollador de la aplicación manejar el error. Por ejemplo, la aplicación podría re-ejecutar la consulta para desencadenar una nueva selección de un servidor y una nueva invocación a la llamada de retorno. Si lo hace, la llamada de retorno debe asegurarse de seleccionar un esclavo diferente, o comprobar la disponibilidad del esclavo, antes de devolver el resultado al complemento para evitar un bucle infinito.

Ejemplo #14 Establecer una llamada de retorno

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": {
            "user": {
                "callback": "pick_server"
            }
        }
    }
}

Se espera que la llamada devuelva un equipo anfitrión donde ejecutar la consulta. El URI del equipo anfitrión se tomará de las listas de conexión maestras y esclavas pasadas a la función de llamada de retorno. Si ésta devuelve un valor que no se encuentra el las listas de conexión maestras ni en las esclavas, el complemento emitirá un error de tipo E_RECOVERABLE_ERROR. El error puede ser (mysqlnd_ms) User filter callback has returned an unknown server. The server 'server that is not in master or slave list' can neither be found in the master list nor in the slave list ((mysqlnd_ms) La llamada de retorno del filtro de usuario ha devuelto un servidor desconocido. El servidor 'servidor que no está en la lista de maestros o esclavos' no se puede encontrar en ni en la lista de maestros ni en la de esclavos). Si la aplicación captura el error para ignorarlo, los errores siguientes pueden ser establecidos en el gestor de conexión, por ejemplo, (mysqlnd_ms) No connection selected by the last filter ((mysqlnd_ms) El último filtro no seleccionó ninguna conexión) con el código de error 2000 y el estado sql HY000. Además se puede emitir una advertencia.

Si se hace referencia a una función inexistente como llamada de retorno, resultará en cualquier error de tipo E_RECOVERABLE_ERROR siempre que el complemento intente invocar a dicha función. El mensaje de error puede ser como: (mysqlnd_ms) Specified callback (pick_server) is not a valid callback ((mysqlnd_ms) La llamada de retorno (pick_server) no es una llamada de retorno válida). Si la aplicación captura el error para ignorarlo, los errores siguientes pueden ser establecidos en el gestor de conexión, por ejemplo, (mysqlnd_ms) Specified callback (pick_server) is not a valid callback con el código de error 2000 y el estado sql HY000. Admás se puede emitir una advertencia.

Los siguientes parámetros son pasados desde el complemento a la llamada de retorno.

Parámetro Descripción Versión
connected_host

El URI del servidor de las bases de datos conectado actualmente.

Desde 1.1.0.
query

La consulta de la sentencia para la cual un servidor necesita ser elegido.

Desde 1.1.0.
masters

La lista de servidores maestros de donde elegir. Observe que la lista de servidores maestros puede no ser idéntica a la lista de servidores maestros configurados si el filtro no es el primero en la cadena de filtros. Los filtros ejecutados anteriormente puede haber reducido la lista de maestros.

Desde 1.1.0.
slaves

La lista de servidores esclavos de donde elegir. Observe que la lista de servidores maestros puede no ser idéntica a la lista de servidores maestros configurados si el filtro no es el primero en la cadena de filtros. Los filtros ejecutados anteriormente puede haber reducido la lista de maestros.

Desde 1.1.0.
last_used_connection

El URI del servidor de la conexión usada donde ejecutar la sentencia anterior.

Desde 1.1.0.
in_transaction

Bandera booleana que indica si la sentencia es parte de una transacción abierta. Si el modo 'autocommit' está desactivado, se establecerá a TRUE. Si no, se establecerá a FALSE.

La detección de transacciones está basada en la monitorización de la llamada a set_autocommit de la biblioteca mysqlnd . La monitorización no era posible antes de PHP 5.4.0. Por favor, vea la argumentación de los conceptos sobre agrupación e intercambio de conexiones para más detalles.

Desde 1.1.0.

Ejemplo #15 Utilizar una llamada de retorno

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            },
            "slave_1": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": {
            "user": {
                "callback": "pick_server"
            }
        }
    }
}
<?php
function pick_server($connected, $query, $masters, $slaves, $last_used_connection, $in_transaction)
{
 static $slave_idx = 0;
 static $num_slaves = NULL;
 if (is_null($num_slaves))
  $num_slaves = count($slaves);

 /* predeterminado: volver a la lógica interna del comlemento */
 $ret = NULL;

 printf("El usuario se ha conectado a '%s'...\n", $connected);
 printf("... decidiendo dónde ejecutar '%s'\n", $query);

 $where = mysqlnd_ms_query_is_select($query);
 switch ($where)
 {
  case MYSQLND_MS_QUERY_USE_MASTER:
   printf("... usando el maestro\n");
   $ret = $masters[0];
   break;
  case MYSQLND_MS_QUERY_USE_SLAVE:
   /* SELECT or SQL hint for using slave */
   if (stristr($query, "FROM table_on_slave_a_only"))
   {
    /* una tabla que está únicamente en el primer esclavo configurado  */
    printf("... detectado un acceso a la tabla únicamente disponible en el esclavo A\n");
    $ret = $slaves[0];
   }
   else
   {
    /* rotativo */
    printf("... alguna consulta de solo lectura para un esclavo\n");
    $ret = $slaves[$slave_idx++ % $num_slaves];
   }
   break;
  case MYSQLND_MS_QUERY_LAST_USED:
   printf("... usando el último esclavo utilizado\n");
   $ret = $last_used_connection;
   break;
 }

 printf("... ret = '%s'\n", $ret);
 return $ret;
}

$mysqli = new mysqli("myapp", "root", "", "test");

if (!($res = $mysqli->query("SELECT 1 FROM DUAL")))
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
 $res->close();

if (!($res = $mysqli->query("SELECT 2 FROM DUAL")))
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
 $res->close();


if (!($res = $mysqli->query("SELECT * FROM table_on_slave_a_only")))
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
 $res->close();

$mysqli->close();
?>

El resultado del ejemplo sería:

El usuario se ha conectado a 'myapp'...
... decidiendo dónde ejecutar 'SELECT 1 FROM DUAL'
... alguna consulta de solo lectura para un esclavo
... ret = 'tcp://192.168.2.27:3306'
El usuario se ha conectado a 'myapp'...
... decidiendo dónde ejecutar 'SELECT 2 FROM DUAL'
... alguna consulta de solo lectura para un esclavo
... ret = 'tcp://192.168.78.136:3306'
El usuario se ha conectado a 'myapp'...
... decidiendo dónde ejecutar 'SELECT * FROM table_on_slave_a_only'
... detectado un acceso a la tabla únicamente disponible en el esclavo A
... ret = 'tcp://192.168.2.27:3306'

Filtro: user_multi object

El filtro user_multi se diferencia de user en un único aspecto. De otro modo su sintaxix sería idéntica. El filtro user debe elegir y devolver exactamente un nodo para la ejecución de sentecias. Una cadena de filtros normalmente finaliza con un filtro que emite un único nodo. La cadena de filtros reduciría la lista de candidatos para la ejecución de sentencias a uno. Este es el caso, sólo queda un nodo, después de haber ejecutado el filtro user.

El filtro user_multi es un filtro múltiple. Devuelve una lista de servidors esclavos y una lista de servidores maestros. La lista necesita más filtración para identificar exactamente un nodo para la ejecución de sentencias. Un filtro múltiple normalmente se coloca al principio de la cadenda de filtros. El filtro quality_of_service es otro ejemplo de filtro múltiple.

El valor devuelto por la llamada de retorno establecido por user_multi debe ser un array con dos elementos. El primero contiene una lista de los servidores maestros seleccionados. El segundo contiene una lista de los servidores esclavos seleccionados. Las listas contendrán las claves de los servidores maestros y esclavos tal como se encontraron en las listas de esclavos y maestros pasadas a la llamada de retorno. El ejemplo de abajo devuelve listas de maestros y esclavos aleatorios extraídas de la entrada de la función.

Ejemplo #16 Devolver maestros y esclavos aleatorios

<?php
function pick_server($connected, $query, $masters, $slaves, $last_used_connection, $in_transaction)
{
  $maestros_elegidos = array()
  foreach ($masters as $clave => $valor) {
    if (mt_rand(0, 2) > 1)
      $maestros_elegidos[] = $key;
  }
  $esclavos_elegidos = array()
  foreach ($slaves as $clave => $valor) {
    if (mt_rand(0, 2) > 1)
      $esclavos_elegidos[] = $clave;
  }
  return array($maestros_elegidos, $esclavos_elegidos);
}
?>

El complemento emitirá un error de tipo E_RECOVERABLE si la llamada de retorno falla al devolver la lista de servidores. El error puede ser (mysqlnd_ms) User multi filter callback has not returned a list of servers to use. The callback must return an array in %s on line %d ((mysqlnd_ms) La llamada de retorno del filtro de usuario no ha devuelto una lista de servidores a usar. La llamada de retorno debe devolver un array en %s en la línea %d). En caso de que la lista de servidores no esté vacía pero contenga claves/ids de servidores no válidos, e lanzaráun error de tipo E_RECOVERABLE con un mensaje de error como (mysqlnd_ms) User multi filter callback has returned an invalid list of servers to use. Server id is negative in %s on line %d ((mysqlnd_ms) La llamada de retorno del filtro de usuario ha devuelto una lista de servidores a usar no válida. El id del servidor es negativo en %s en la línea %d), o similar.

La emisión de un error en caso de que la lista de esclavos o de maestros esté vacía depende de la configuración. Si se devuelve una lista de maestros vacía para una operación de escritura, es probable que el complemento emita una advertencia como (mysqlnd_ms) Couldn't find the appropriate master connection. 0 masters to choose from. Something is wrong in %s on line %d ((mysqlnd_ms) No se pudo encontrar la conexión maestra apropiada. 0 maestros donde elegir. Algo está mal en %s en la línea %d). Normalmente también es seguida de un error de tipo E_ERROR. En el caso de una operación de lectura con una lista de servidores vacía, el comportamiento depende de la configuración de la tolerancia a fallos. Si ésta está habilitada en el maestro, no debería aparecer ningún error. Si está desactivada en el maestro, el complemento emitirá una advertencia como (mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. Something is wrong in %s on line %d ((mysqlnd_ms) No se pudo encontrar la conexión esclava apropiada. 0 esclavos donde elegir. Algo está mal en %s en la línea %d).

Filtro: quality_of_service object

El filtro quality_of_service identifica nodos del clúster capaces de proporcionar una calidad de servicio en particular. Es un filtro múltiple que devuelve cero, uno o múltiples de los servidores que se le proporcionen. Por lo tanto, deben seguirle otros filtros para reducir el número de candidatos a uno para la ejecución de sentecnias.

El filtro quality_of_service ha sido introducido en la versión 1.2.0-alpha. En las serires 1.2, el filtro se centra en el aspecto de la consistencia de la calidad del servicio. Diferentes tipos de clústeres ofrecen diferentes consistencias de datos predeterminadas. Por ejemplo, un esclavo de replicación MySQL asíncrono ofrece consistencia final. El esclavo podría no proporcionar los datos solicitados debido a que no ha replicado la escritura, podría servir una base de datos antigua debido a su demora, o podría servir información actual. A menudo, esto es aceptable. En algunos casos son necesarios niveles de consistencia mayor para que la aplicación funcione correctamente. En tales casos, quality_of_service puede ignorar los nodos del clúster que no proporcionen la calidad de servicio necesaria.

El filtro quality_of_service puede ser reemplazado o creado en tiempo de ejecución. Una llamada exitosa a mysqlnd_ms_set_qos() elimina todas las entradas de los filtros qos existentes de la lista de filtros e instala uno nuevo al principo de la misma. Todas los ajustes que se pueden hacer a través de mysqlnd_ms_set_qos() también pueden realizarse en el fichero de configuración del complemento. Sin embargo, el uso de la función es de lejos el caso más común. En lugar de establecer los niveles de servicios de consistencia de sesión y de consistencia fuerte en el fichero de configuración del complemento, se recomienda definir solamente maestros, y no esclavos. Ambos niveles de servicio forzarán el uso de maestros solamente. Usar una lista de esclavos vacía abrevia el fichero de configuración, y así se mejora su legibilidad. El único nivel de servicio en el que existe un caso para la definición en el fichero de configuración del complemento es la combinación de consistencia final y demora máxima de esclavos.

Palabra clave Descripción Versión
eventual_consistency

Solicita la consistencia final. Permite el uso de todos los servidores maestros y esclavos. Los datos devueltos pueden o no ser actuales.

La consistencia final acepta el parámetro opcional age. Si se proporciona age, el complemento considerará para la lectura solamente los esclavos que la replicación MySQL notifique que tengan una demora menor o igual a age. La demora de replicación se mide usando SHOW SLAVE STATUS. Si el complemento falla al recuperar la demora de replicación, saltará el esclavo comprobado. Los detalles de implementación y algunos consejos se proporcionan en la sección de conceptos de calidad de servicio.

Por favor, observe que si una cadena de filtros genera un lista vacía de esclavos y se usa la directiva de configuración de PHP mysqlnd_ms.multi_master=0, el complemento podría emitir una advertencia.

Ejemplo #17 Límite global de la demora de los esclavos

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            },
            "slave_1": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": {
            "quality_of_service": {
                "eventual_consistency": {
                    "age":123
                }
            }
        }
    }
}

 Desde 1.2.0.
session_consistency

Solicita la consistencia de sesión (lectura de sus escrituras). Permite el uso de todos los maestros y todos los esclavos que están sincronizados con el maestro. Si no se proporcionan más parámetros, los esclavos son filtrados debido a que no existe una manera fiable de comprobar si un esclavo se a puesto al día con respecto al maestro o si está retrasado. Por favor, observe que si una cadena de filtros genera una lista de esclavos vacía y se usa la directiva de configuración de PHP mysqlnd_ms.multi_master=0, el complemento podría emitir una advertencia.

La solicitud temporal de la consistencia de sesión usando mysqlnd_ms_set_qos() es una alternativa a usar master_on_write. master_on_write probablemente envía más sentencias al maestro de las necesarias. La aplicación puede continuar la operación en un nivel de consistencia más bajo después de haber realizado algunas lecturas críticas.

Desde 1.1.0.
strong_consistency

Solitica la consistencia fuerte. Solamente serán usados los maestros.

Desde 1.2.0.
failover Hasta, e incluyendo 1.3.x: string. Desde 1.4.0: object.

Política de la tolerancia a fallos. Políticas admitidas: disabled (predeterminada), master, loop_before_master (desde 1.4.0).

Si no se establece ninguna política de tolerancia a fallos, el complemento no realizará ninguna tolerancia a fallos automática (failover=disabled). Siempre que el complemento falle al conectarse a un servidor, emitirá una advertencia y establecerá el código y el mensaje del error de conexión. A partir de entonces, es responsabilidad de la aplicación manejar el error y, por ejemplo, reenviar la última sentencia para provocar la selección de otro servidor.

Observe que la lógica de tolerancia a fallos automática se aplica al abrir conexiones solamente. Una vez que una conexión ha sido abierta, no se realizan intentos automáticos para reabrirla en caso de error. Si, por ejemplo, si la conexión a un servidor se cierra y el usuario intenta ejecutar una sentencia sobre dicha conexión, no se intentará la tolerancia a fallos automática. En su lugar se notificará un error.

Si se usa failover=master, el complemento implícitamente usará la tolerancia a fallos del maestro. Por favor, revise la documentación de conceptos para informarse sobre los problemas y riesgos potenciales del uso de failover=master.

Ejemplo #18 Tolerancia a fallos opcional en el maestro al fallar una conexión a un esclavo

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "failover": "master"
    }
}

Desde PECL/mysqlnd_ms 1.4.0 la palabra clave de la configuración de la tolerancia a fallos se refiere a un objeto.

Ejemplo #19 Nueva sintaxis desde 1.4.0

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "failover": {"strategy": "master" }
    }
}

Palabra clave Descripción Versión
strategy

Política de tolerancia a fallos. Valores posibles: disabled (predeterminado), master, loop_before_master

El valor disabled deshabilita la tolerancia a fallos automática.

Establecer master ordena al complemento a intentar conectarse a un maestro en caso de un error de conexión esclava. Si el intento de conexión maestra falla, el comlemento se saldrá del bucle de tolerancia a fallos y devolverá un error al usuario.

Si se usa loop_before_master y se realiza una petición a un esclavo, el complemento intentará conectarse a otro esclavo antes realizar la tolerancia a fallos en un maestro. Si se dan múltiples maestros y está habilitado el multimaestro, el complemento también iterará sobre la lista de maestros e intentará conectarse antes de devolver un error al usuario.

Desde 1.4.0.
remember_failed

Recuerda los fallos durante una petición web. Predeterminado: false.

Si se establece a true el complemento recordará los equipos anfitriones fallidos y los saltará en todos los equilibrados de carga futuros realizados para la duración de la petición web actual.

Desde 1.4.0. Característica experimental. La característica solamente está disponible junto con los filtros de equilibrado de carga random y roundrobin. Es posible que el funcionamiento y la sintaxis cambien en el futuro.
max_retries

Número máximo de intentos de conexión antes de saltarse un equipo anfitrión. Predeterminado: 0 (sin límite).

Este ajuste se usa para prevenir que los equipos anfitriones sean elegidos de la lista host si ocurre un primer fallo. Si se establece a n > 0, el complemento guardará el nodo en la lista de nodos incluso después de un intento de conexión fallido. El nodo no será eliminado inmediatamente de las lista de esclavos y maestros respectivamente después del primer fallo de conexión, pero en su lugar se intentará conectar hasta n veces en las rondas de equilibrado de carga futuras antes de ser eliminado.

Desde 1.4.0. Característica experimental. La característica solamente está disponible junto con los filtros de equilibrado de carga random y roundrobin. Es posible que el funcionamiento y la sintaxis cambien en el futuro.

Establecer failover a cualquier valor distinto de disabled, master o loop_before_master no emitirá ninguna advertencia o error.

lazy_connections bool

Controla el uso de conexiones retardadas. Las conexiones retardadas son conexiones que no se abren antes de que un cliente envíe la primera conexión. Las conexiones retardadas son las predeterminadas.

Se recomeinda encarecidamente usar conexiones retardadas. Éstas ayudan a mantener bajo el número de conexiones abiertas. Si se desabilitan las conexiones retardas y, por ejemplo, se configura un servidor maestro de replicación MySQL y dos esclavos de replicación MySQL, el complemento abrirá tres conexiones en la primera llamada a la función de conexión, aunque la aplicación podría usar solamente la conexión maestra.

Las conexiones retardadas revelan un riesgo si se realizan un gran uso de acciones que cambian el estado de una conexión. El complemento no resolverá todas las acciones de cambio de estado de todas las conexiones de la agrupación de conexiones. Las pocas acciones resueltas son aplicadas solamente a conexiones ya abiertas. Las conexiones retardadas abiertas en el futuro no son afectadas. Solamente algunos ajustes son "recordados" y aplicados cuando las conexiones retardadas son abiertas.

Ejemplo #20 Deshabilitar las conexiones retardadas

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "lazy_connections": 0
    }
}

Por favor, véase también server_charset para superar problemas potenciales con el escapado de cadenas de texto y con servidores que utilicen conjuntos de caracteres diferentes del predeterminado.

server_charset string

Este ajuste ha sido introducido en la versión 1.4.0. Se recomienda establecerlo si se van a usar conexiones retardadas.

El ajuste server_charset sirve para dos propósitos. Actúa como conjunto de caracteres alternativo para su uso con el escapado de cadenas de texo realizado antes de que se haya establecido una conexión, y ayuda a evitar problemas de escapado en entornos heterogéneos con servidores que utilizan diferentes conjuntos de caracteres predeterminados.

El escapado de cadenas de texto toma en cuenta el conjunto de caracteres de una conexión. El escapado de cadenas de texto no es posible antes de que una conexión haya sido abierta y se conozca el conjunto de caracteres de de la conexión. El uso de conexiones retardadas demora la apertura real de conexiones hasta que se envíe una sentencia.

Una aplicación que utilice conexiones retardadas puede intentar escapar una cadena de texto antes de nviar una setencia. De hecho, esto debería ser un caso común, ya que la sentencia podría contener la cadena de texto que va a ser escapada. Sin embargo, debido a la característica de conexiones retardadas, aún no se ha abierto ninguna conexión y el escapado falla. El complemento podría notificar un error de tipo E_WARNING y un mensaje como (mysqlnd_ms) string escaping doesn't work without established connection. Possible solution is to add server_charset to your configuration ((mysqlnd_ms) el escapado de cadenas de texto no funciona sin establecer una conexión. Una posible solución es añadir server_charset a la configuración) para informar del problema.

Establecer server_charset hace que el complemento use el conjunto de caracteres dado para el escapado de cadenas de texto realizado sobre gestores de conexines retardadas antes de establecer una conexión de red a MySQL. Además, el complemento forzará el uso del conjunto de caracteres cuando la conexión sea establecida.

El forzado del uso del conjunto de caracteres utilizado para el escapado se realiza para prevenir los problemas de usar un conjunto de caracteres diferente para el escapado que el usado después para la conexión. Esto tiene el benificio adicional de eliminar la necesidad de ajustar la configuración del conjunto de caracteres de todos los servidores usados. No importa cuál sea el conjunto de caracteres predeterminado de cualquier servidor, el complemento establecerá el configurado como el predeterminado.

El complemento no impide al usuario cambiar el conjunto de caracteres en cualquier momento mediante la llamada a set_charset() o las setencias SQL correspondientes. Por favor, observe que el uso de SQL no se recomienda ya que no puede ser monitorizado por el complemento. El usuario puede, por ejemplo, cambiar el conjunto de caracteres sobre un gestor de conexiones retaradadas después de escapar una cadena de texto y antes de abrir la conexión real. El conjunto de caracteres establecido por el usuario será usado para cualquier escapado subsiguiente antes de que se establezca la conexión. Ésta será establecida usando el conjunto de caracteres configurado, sin importar cuál es el conjunto de caracteres del servidor ni cuál ha establecido el usuario antes. Una vez que una conexión ha sido abierta, set_charset ya no tiene sentido.

Ejemplo #21 Escapado de cadenas de texto sobre un gestor de conexiones retardadas

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "lazy_connections": 1,
        "server_charset" : "utf8"
    }
}
<?php
$mysqli = new mysqli("myapp", "nombre_usuario", "contraseña", "base_datos");
$mysqli->real_escape("esto será escapado usando el ajuste server_charset - utf8");
$mysqli->set_charset("latin1");
$mysqli->real_escape("esto será escapado usando latin1");
/* conjunto de caracteres del servidor implícitamente establecido - conexión utf8 */
$mysqli->query("SELECT 'Esta conexión será fijada a server_charset durante su establecimiento' AS _msg FROM DUAL");
/* latin1 se usará de aquí en adelante */
$mysqli->set_charset("latin1");
?>

master_on_write bool

Si se establece, el complemento usará únicamente el servidor maestro después de que se haya ejecutado la primera sentencia en el maestro. Las aplicaciones aún pueden enviar sentencias a los esclavos usando sugerencias SQL para invalidar la decisión automática.

Este ajuste puede ser útil con la demora de replicación. Si una aplicación ejecuta un INSERT, el complemento usará, de manera predeterminada, el maestro para ejecutar todas las sentencias siguientes, incluidas las sentencias SELECT. Esto ayuda a evitar problemas con las lecturas desde los esclavos que no hayan replicado aún el INSERT.

Ejemplo #22 master_on_write para lecturas consistentes

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "master_on_write": 1
    }
}

Por favor, observe que el filtro quality_of_service fue introducido en la versión 1.2.0-alpha. Proporciona mayor control sobre, por ejemplo, la realización de la lectura se sus escrituras y ofrece funcionalidad adicional introduciendo los niveles de servicio.

trx_stickiness string

Política de adhesión de transacciones. Las políticas admitidas son: disabled (predeterminada), master.

Este ajuste requiere la versión 5.4.0 o posterior. Si se usa con una versión de PHP anterior a la 5.4.0, el complemetno emitirá una advertencia como (mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99 ((mysqlnd_ms) La estrategia trx_stickiness no está soportada antes de PHP 5.3.99).

Si no se establece ningun política de adhesión de transacciones o si se establece trx_stickiness=disabled, el complemento no considerará las transacciones. Por lo tanto, el complemento podrá realizar el equilibrado de carga de conexiones y el intercambio de conexiones en mitad de una trasacción. El complemento no es seguro con las transacciones. Se deben usar sugerencias SQL para evitar el intercambio de conexiones durante una transacción.

A partir de PHP 5.4.0, la bibliteca mysqlnd permite al complemento monitorizar el modo autocommit mediante las llamadas a la función set_autocommit() de la biblioteca. Si se establece set_stickiness=master y se deshabilita autocommit mediante una extensión de MySQL para PHP que invoque la llamada a la función interna set_autocommit() de la biblioteca mysqlnd, hará que el complemento considere el comienzo de una transacción. Luego, el complemento detiene el equilibrado de carga y dirige todas las setencias al servidor maestro hasta que autocommit sea habilitado. Por lo tanto, no son necesarias las sugerencias SQL.

Un ejemplo de una función de la API de MySQL para PHP que llama a la función interna set_autocommit() de la biblioteca mysqlnd es mysqli_autocommit().

Aunque se establezca ser_stickiness=master, el complemento no puede considerar los cambios del modo autocommit causados por setnencias SQL como SET AUTOCOMMIT=0.

Ejemplo #23 Utilizar el maestro para ejecutar transacciones

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "trx_stickiness": "master"
    }
}

Instalación/Configuración
PHP Manual