Setup

插件是一个 PHP 的扩展, 可以查看 installation instructions 学习如何安装 » PECL/mysqlnd_ms 扩展。

编译或配置 PHP MySQL 扩展 (API) (mysqli、 PDO_MYSQL、 mysql)，也就是你打算使用的、支持 mysqlnd 的库。 PECL/mysqlnd_ms 是一个 mysqlnd 库的插件。使用任意 PHP MySQL 扩展时，要使用 mysqlnd 必须使用该插件。

然后，使用 mysqlnd_ms.enable 在 PHP 配置文件中装载和激活插件。

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

插件使用他自己的配置文件。使用 PHP 指令 mysqlnd_ms.config_file 定义插件配置文件的完整路径。 该文件必须能被 PHP 读取(比如 web 服务器的用户)。 请注意，从 1.4.0 版本开始配置文件变量使用 mysqlnd_ms.config_file, 以前的 mysqlnd_ms.ini_file 不再使用。 使用旧的、不再有效的指令是一个很常见的错误。

在 mysqlnd_ms.config_file 指定的目录中，创建保存插件的配置文件。

插件的 配置文件 基于 JSON 格式。 配置写在一个或者多个章节中。每个章节都包含一个名称，例如： myapp。 每个章节包含自己的配置信息。

一个章节的配置中，至少要包含 MySQL 主从复制中的 master 服务器和相关 slave 服务器。 每个章节只能使用一个 master 服务器。 目前还不能完全支持多 master(Multi-master)的设置。 master 用于设定 MySQL master 服务器的 hostname、port 或 socket。 而 MySQL slave 服务器信息使用 slave 来设定。

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

必须配置 MySQL slave 服务器列表，当然它也可以是空的列表。我们建议至少配置一个 slave 服务器。

服务器列表可以使用 匿名或者非匿名语法。 非匿名列表包含一个别名，例如 master_0 可用于上面的例子。 在这里，将使用更详细的非匿名语法。

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

如果这里至少有两个服务器，插件可以负载均衡、切换连接。切换链接并不总是透明的，在某些具体条件下会导致问题。本参考中包含 连接池和切换， 事务处理， 故障转移 负载均衡 和 读写分离。稍后在本指南中将具体描述更多潜在的陷阱。

应用需要处理连接切换过程中潜在的问题，配置一个 master 和至少一个 slave，这样就可以切换，因此能发现相关问题。

MySQL 主从同步并不需要你配置 master 和 slave。 为了测试的目的，你可以使用单个 MySQL 服务器，让插件认为是 master 和 slave 服务器，就像以下的设置。这样可以帮助你在连接切换中检测到很多潜在问题。 不过，这样的设置不容易发生因为主从同步延迟而导致的问题。

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

插件将尝试通知你不合理的配置. 从 1.5.0 版本开始, 下列情况它抛出一个 PHP warning, 配置文件不可读; 空配置或者 JSON 配置语法错误. 通过 PHP 本身的配置，可能这些报警信息 会被放置在某些错误 LOG 文件当中。在验证完毕后，通过配置文件中有效的章节，连接会被建立。 设置 mysqlnd_ms.force_config_usage 可以帮助你进行 DEBUG。可以参考 配置文件 DEBUG 说明.