mysqlnd-ms-php-quickstart-php-configuration-5

  • Quickstart and
    Examples
  • Setup

  • Setup
  • Setup

    Setup

    The plugin is implemented as a PHP extension. See
    also the installation instructions to install the » PECL/mysqlnd_ms extension.

    Compile or configure the PHP MySQL extension (API)
    (mysqli, PDO_MYSQL, mysql) that you plan to use with
    support for the mysqlnd library. PECL/mysqlnd_ms is a plugin for the
    mysqlnd library. To use the plugin with any of the PHP MySQL
    extensions, the extension has to use the mysqlnd library.

    Then, load the extension into PHP and activate the
    plugin in the PHP configuration file using the PHP configuration
    directive named mysqlnd_ms.enable.

    Example #1 Enabling the plugin (php.ini)

    mysqlnd_ms.enable=1
    mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini
    

    The plugin uses its own configuration file. Use the
    PHP configuration directive mysqlnd_ms.config_file to set the full file path to the
    plugin-specific configuration file. This file must be readable by
    PHP (e.g., the web server user). Please note, the configuration
    directive mysqlnd_ms.config_file superseeds mysqlnd_ms.ini_file since 1.4.0. It is a common pitfall
    to use the old, no longer available configuration directive.

    Create a plugin-specific configuration file. Save
    the file to the path set by the PHP configuration directive
    mysqlnd_ms.config_file.

    The plugins configuration
    file
    is JSON based. It is divided
    into one or more sections. Each section has a name, for example,
    myapp. Every section makes its own set of configuration
    settings.

    A section must, at a minimum, list the MySQL
    replication master server, and set a list of slaves. The plugin
    supports using only one master server per section. Multi-master
    MySQL replication setups are not yet fully supported. Use the
    configuration setting master to set the hostname, and the port or socket
    of the MySQL master server. MySQL slave servers are configured
    using the slave keyword.

    Example #2 Minimal plugin-specific configuration file
    (mysqlnd_ms_plugin.ini)

    {
        "myapp": {
            "master": {
                "master_0": {
                    "host": "localhost"
                }
            },
            "slave": [
    
            ]
        }
    }
    

    Configuring a MySQL slave server list is required,
    although it may contain an empty list. It is recommended to always
    configure at least one slave server.

    Server lists can use anonymous or non-anonymous syntax. Non-anonymous
    lists include alias names for the servers, such as
    master_0 for the master in the above example. The
    quickstart uses the more verbose non-anonymous syntax.

    Example #3 Recommended minimal plugin-specific config
    (mysqlnd_ms_plugin.ini)

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

    If there are at least two servers in total, the
    plugin can start to load balance and switch connections. Switching
    connections is not always transparent and can cause issues in
    certain cases. The reference sections about connection pooling and
    switching
    , transaction handling, fail over load balancing and read-write splitting all
    provide more details. And potential pitfalls are described later in
    this guide.

    It is the responsibility of the application to
    handle potential issues caused by connection switches, by
    configuring a master with at least one slave server, which allows
    switching to work therefore related problems can be found.

    The MySQL master and MySQL slave servers, which you
    configure, do not need to be part of MySQL replication setup. For
    testing purpose you can use single MySQL server and make it known
    to the plugin as a master and slave server as shown below. This
    could help you to detect many potential issues with connection
    switches. However, such a setup will not be prone to the issues
    caused by replication lag.

    Example #4 Using one server as a master and as a slave
    (testing only!)

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

    The plugin attempts to notify you of invalid
    configurations. Since 1.5.0 it will throw a warning during PHP
    startup if the configuration file cannot be read, is empty or
    parsing the JSON failed. Depending on your PHP settings those
    errors may appear in some log files only. Further validation is
    done when a connection is to be established and the configuration
    file is searched for valid sections. Setting mysqlnd_ms.force_config_usage may help debugging a
    faulty setup. Please, see also configuration file debugging notes.