• Quickstart and
  • Running statements

  • Running statements
  • Running statements

    Running statements

    The plugin can be used with any PHP MySQL extension
    (mysqli, mysql, and PDO_MYSQL) that is compiled
    to use the mysqlnd
    library. PECL/mysqlnd_ms plugs into the mysqlnd library. It does not
    change the API or behavior of those extensions.

    Whenever a connection to MySQL is being opened, the
    plugin compares the host parameter value of the connect call, with
    the section names from the plugin specific configuration file. If,
    for example, the plugin specific configuration file has a section
    myapp then the section should be referenced by opening a
    MySQL connection to the host myapp

    Example #1 Plugin specific configuration file

        "myapp": {
            "master": {
                "master_0": {
                    "host": "localhost",
                    "socket": "\/tmp\/mysql.sock"
            "slave": {
                "slave_0": {
                    "host": "",
                    "port": "3306"

    Example #2 Opening a load balanced

    /* Load balanced following "myapp" section rules from the plugins config file */
    $mysqli = new mysqli("myapp""username""password""database");
    $pdo = new PDO('mysql:host=myapp;dbname=database''username''password');
    $mysql mysql_connect("myapp""username""password");

    The connection examples above will be load
    balanced. The plugin will send read-only statements to the MySQL
    slave server with the IP and will listen on
    port 3306 for the MySQL client connection. All other
    statements will be directed to the MySQL master server running on
    the host localhost. If on Unix like operating systems, the
    master on localhost will be accepting MySQL client
    connections on the Unix domain socket /tmp/mysql.sock,
    while TCP/IP is the default port on Windows. The plugin will use
    the user name username and the password password
    to connect to any of the MySQL servers listed in the section
    myapp of the plugins configuration file. Upon connect, the
    plugin will select database as the current schemata.

    The username, password and schema name are taken
    from the connect API calls and used for all servers. In other
    words: you must use the same username and password for every MySQL
    server listed in a plugin configuration file section. The is not a
    general limitation. As of PECL/mysqlnd_ms 1.1.0, it is
    possible to set the username and password for any server in the plugins
    configuration file, to be used instead of the credentials passed to
    the API call.

    The plugin does not change the API for running
    statements. Read-write splitting works out of the box. The following
    example assumes that there is no significant replication lag
    between the master and the slave.

    Example #3 Executing statements

    /* Load balanced following "myapp" section rules from the plugins config file */
    $mysqli = new mysqli("myapp""username""password""database");
    if (
    mysqli_connect_errno()) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n"mysqli_connect_errno(), mysqli_connect_error()));

    /* Statements will be run on the master */
    if (!$mysqli->query("DROP TABLE IF EXISTS test")) {
    printf("[%d] %s\n"$mysqli->errno$mysqli->error);
    if (!
    $mysqli->query("CREATE TABLE test(id INT)")) {
    printf("[%d] %s\n"$mysqli->errno$mysqli->error);
    if (!
    $mysqli->query("INSERT INTO test(id) VALUES (1)")) {
    printf("[%d] %s\n"$mysqli->errno$mysqli->error);

    /* read-only: statement will be run on a slave */
    if (!($res $mysqli->query("SELECT id FROM test"))) {
    printf("[%d] %s\n"$mysqli->errno$mysqli->error);
    } else {
    $row $res->fetch_assoc();
    printf("Slave returns id = '%s'\n"$row['id']);

    The above example will output something similar to:

    Slave returns id = '1'