6.1 MySQL AdminAPI

本节提供AdminAPI的概述,以及开始时需要了解的内容。

MySQL Shell包含AdminAPI,它可以通过dba全局变量及其相关方法。的dba变量的方法提供了部署、配置和管理InnoDB Cluster和InnoDB replicset的操作。例如,使用dba.createCluster ()方法创建InnoDB集群。此外,AdminAPI支持管理一些MySQL路由器相关的任务,例如创建和更新用户,使你能够集成你的InnoDB集群和InnoDB副本集。

MySQL Shell提供了两种脚本语言模式,JavaScript和Python,以及原生SQL模式。在本指南中,MySQL Shell主要以JavaScript模式使用。MySQL Shell启动时默认是JavaScript模式。通过发出命令切换模式\ jsfor JavaScript模式,和\ py对于Python模式。命令来确保您处于JavaScript模式\ js

重要的

MySQL Shell允许您通过套接字连接到服务器,但是AdminAPI需要到服务器实例的TCP连接。AdminAPI不支持基于套接字的连接。

本节假设您熟悉MySQL Shell,请参见MySQL 8.0外壳为进一步的信息。MySQL Shell还为AdminAPI提供了在线帮助。列出所有可用的dba命令,使用dba.help ()方法。对于特定方法的在线帮助,请使用通用格式object.help(“methodname”).例如:

mysql-js> dba.help('getCluster')从元数据存储中检索一个集群。语法dba。getCluster([name][, options]) WHERE name:指定要返回的集群名称的参数。options:带有额外选项的字典。为简单起见> <

除了这个文档,在MySQL Shell 10bet官方网站JavaScript API参考或MySQL Shell Python API参考中有所有AdminAPI方法的开发人员文档连接器和api

本节适用于使用InnoDB Cluster或InnoDB replicset,包括:

部署场景

AdminAPI支持以下部署场景:

  • 生产部署:如果希望使用完整的生产环境,则需要配置所需的计算机数量,然后将服务器实例部署到这些计算机上。

  • 沙箱部署:如果您希望在提交完整的生产部署之前测试部署,提供的沙箱特性使您能够在本地机器上快速设置测试环境。沙盒服务器实例是用所需的配置创建的,您可以通过实验来熟悉所使用的技术。

    重要的

    沙盒部署不适合在完整的生产环境中使用。

安装的组件

如何安装AdminAPI所需的软件组件取决于您打算使用的部署类型。对于生产部署,将组件安装到每台计算机上。生产部署使用运行MySQL服务器实例的多个远程主机,因此需要使用SSH或Windows远程桌面等工具连接到每台机器,以执行安装组件等任务。对于沙盒部署,将组件安装到一台机器上。沙盒部署是本地的单个机器,因此只需在本地机器上执行一次安装。安装方式有以下几种:

请参考以下文档下载并安装组件。10bet官方网站

重要的

总是使用匹配版本的组件,例如运行MySQL Shell 8.0.27来管理运行MySQL 8.0.27和MySQL Router 8.0.27的实例。

一旦您安装了所需的软件,选择遵循其中的任何一个第6.2节,“MySQL InnoDB集群”第6.3节,“MySQL InnoDB复制集”

使用实例运行MySQL 5.7

本文档假设10bet官方网站您正在使用MySQL实例运行最新版本的MySQL 8和MySQL Shell 8。AdminAPI还支持使用运行MySQL 5.7的实例,但是所描述的许多特性都需要运行MySQL 8的实例。对于运行MySQL 5.7的实例,存在以下差异:

  • 运行MySQL 5.7的实例不支持设置保存,所以它们不能远程配置,或自动配置,不像运行MySQL 8的实例。相反,在配置MySQL 5.7实例时,每次都必须连接到实例并使用dba.configureLocalInstance ()操作。当实例选项文件在本地可用时,该操作将设置持久化到实例选项文件。看到保存设置

  • 运行MySQL 5.7的实例不支持自动节点配置,因此在将它们加入集群之前,必须手动将它们与其他集群实例同步。这意味着要么依赖Group Replication的分布式恢复(这需要启用gtid的二进制日志,并且在有大量事务要恢复时可能需要很长时间的等待),要么使用MySQL Enterprise Backup等工具手动复制数据。在8.0版本中增加了MySQL Clone插件,AdminAPI可以自动提供实例。当您添加一个支持MySQL Clone的8.0版本实例时,AdminAPI会自动选择最好的方式将连接实例与现有实例同步。例如,如果集群包含大量事务,则使用MySQL Clone直接恢复数据,然后使用分布式恢复同步集群在克隆操作期间处理的任何事务。您可以直接从MySQL Shell监控操作的进度,不需要其他工具。这使得添加实例来扩展InnoDB集群和提高高可用性的机会等任务变得毫不费力。看到第6.2.2.2节“使用InnoDB集群克隆MySQL”

  • 运行MySQL 5.7的实例不兼容InnoDB副本集。看到第6.3节,“MySQL InnoDB复制集”

  • 在使用MySQL 5.7服务器时,InnoDB集群的拓扑结构(无论是单主模式还是多主模式)都不能动态更改。看到修改集群拓扑

  • 运行MySQL 5.7的实例与并行复制应用程序不兼容。看到配置并行复制应用程序

  • 运行MySQL 5.7的实例不支持autoRejoinTries而且exitStateAction选项,这些选项配置实例尝试重新加入集群的次数以及实例离开时发生的情况。看到配置实例的自动重新连接

  • 运行MySQL 5.7的实例不支持一致性选择。看到故障转移配置的一致性

  • 运行MySQL 5.7的实例不支持expelTimeout选项,该选项配置集群在驱逐与其他实例失去联系的实例之前等待的时间。

要使用这些特性,请将您的实例升级到MySQL 8。

配置主机名

在生产部署中,您使用的实例运行在不同的机器上,因此每台机器必须具有唯一的主机名,并且能够解析运行服务器实例的其他机器的主机名。如果不是这样,你可以:

  • 配置每台机器将另一台机器的IP映射到一个主机名。有关详细信息,请参阅操作系统文档。10bet官方网站这是推荐的解决方案。

  • 建立一个DNS服务

  • 配置report_host将每个实例的MySQL配置中的变量设置为一个合适的外部可达地址

AdminAPI支持使用IP地址而不是主机名。从MySQL Shell 8.0.18, AdminAPI支持IPv6地址,如果MySQL服务器的目标版本高于8.0.13。在使用MySQL Shell 8.0.18或更高版本时,如果所有集群实例都运行8.0.14或更高版本,那么您可以使用IPv6或主机名来解析为实例连接字符串的IPv6地址,并带有选项,例如localAddressgroupSeeds而且ipAllowlist.有关使用IPv6的更多信息,请参见支持IPv6和混合IPv6和IPv4组.以前的版本只支持IPv4地址。

要验证MySQL服务器的主机名是否正确配置,执行以下查询,查看实例如何将自己的地址报告给其他服务器,并尝试使用返回的地址从其他主机连接到该MySQL服务器:

选择合并(@@report_host @@hostname);

指定实例

使用AdminAPI的一个核心概念是理解到MySQL实例的连接,这些实例组成了你的InnoDB集群或InnoDB副本集。在管理时连接到实例的需求以及实例本身之间的连接的需求如下:

  • 只支持TCP/IP连接,不支持使用Unix套接字或命名管道。InnoDB Cluster和InnoDB replicset主要用于局域网,不建议在广域网上运行。

  • 只支持经典的MySQL协议连接,不支持X协议。

    提示

    您的应用程序可以使用X协议,这个要求是为了使用AdminAPI进行管理操作。

MySQL Shell使您能够使用各种api,并支持指定连接使用类似uri的字符串或键值对连接到服务器.可以使用类似uri的字符串或键-值对指定连接。的额外的连接参数在AdminAPI中不支持。本文档演示10bet官方网站了使用类似uri的连接字符串的AdminAPI。例如,以用户身份连接myuser到MySQL服务器实例www.example.com,在端口3306使用连接字符串:

myuser@www.example.com: 3306

要将此连接字符串与AdminAPI操作一起使用,例如dba.configureInstance (),您需要确保连接字符串被解释为字符串,例如在连接字符串周围使用单引号(')或双引号(")。如果你正在使用AdminAPI的JavaScript实现问题:

MySQL JS > dba.configureInstance('myuser@www.example.com3306”)

假设您正在默认交互模式下运行MySQL Shell,系统会提示您输入密码。AdminAPI支持MySQL Shell的第4.4节,“可插入密码存储”,一旦您存储了用于连接到实例的密码,就不再提示您输入该密码。

保存设置

AdminAPI命令用于InnoDB Cluster、InnoDB replicset和它们的服务器实例修改MySQL实例上的配置。根据MySQL Shell连接到实例的方式和安装在实例上的MySQL版本,这些配置更改可以自动持久化到实例中。将设置持久化到实例可确保在实例重启后保留配置更改,有关背景信息,请参阅设置保存.这对于可靠的使用是必不可少的,例如,如果设置没有持久化,那么已经添加到集群的实例在重新启动后就不会重新加入集群,因为配置更改丢失了。

满足以下要求的实例支持自动持久化配置更改:

不满足这些要求的实例不支持自动持久化配置更改,当AdminAPI操作导致要持久化的实例设置更改时,您会收到以下警告:

警告:在实例'localhost:3320'成员更改不能持久,因为MySQL版本5.7.21不支持SET PERSIST命令(MySQL版本>= 8.0.5需要)。请使用。configureLocalInstance命令在本地保存更改。

当AdminAPI命令针对MySQL Shell当前运行的MySQL实例(换句话说就是本地实例)发出时,MySQL Shell将配置更改直接保存到该实例。在支持自动持久化配置更改的本地实例上,配置更改将持久化到实例的mysqld-auto.cnf文件和配置更改不需要任何其他步骤。在不支持自动持久化配置更改的本地实例上,您需要在本地进行更改,参见配置实例,dba.configureLocalInstance ()

在对远程实例(换句话说,不是MySQL Shell当前运行的实例)运行时,如果实例支持自动持久化配置更改,AdminAPI命令将持久化配置更改到实例mysql-auto.conf选择文件。如果远程实例不支持自动持久化配置更改,AdminAPI命令就不能自动配置实例的选项文件。这意味着AdminAPI命令可以从实例中读取信息,例如显示当前配置,但是对配置的更改不能持久化到实例的选项文件中。在这种情况下,您需要在本地持久化更改,参见配置实例,dba.configureLocalInstance ()

检索处理程序对象

当你使用AdminAPI时,你使用一个代表InnoDB集群或InnoDB副本集的处理程序对象。将该对象分配给一个变量,然后使用可用的操作来监视和管理InnoDB集群或InnoDB副本集。为了能够检索处理程序对象,你建立一个连接到一个属于InnoDB集群或InnoDB副本集的实例。例如,当您使用dba.createCluster (),操作返回a集群对象,该对象可赋值给变量。您可以使用该对象与集群一起工作,例如添加实例或检查集群的状态。如果您希望在稍后的日期再次检索集群,例如在重新启动MySQL Shell之后,请使用dba.getCluster ([的名字]、[选项])函数。例如:

mysql-js> var cluster1 = dba.getCluster()

同样,使用dba.getReplicaSet ()检索一个InnoDB副本集。例如:

mysql-js> var replicaset1 = dba. getreplicset ()

如果不指定的名字然后返回默认对象。默认情况下,MySQL Shell在检索处理程序时尝试连接到主实例。设置connectToPrimary选项来配置此行为。如果connectToPrimary真正的如果激活的全局MySQL Shell会话不是一个主实例,MySQL Shell查询的是主实例。如果集群中没有仲裁,则操作失败。如果connectToPrimary,检索到的对象使用活动会话,换句话说,与MySQL Shell当前全局会话相同的实例。如果connectToPrimaryMySQL Shell如何处理connectToPrimary作为真正的,并回落到connectToPrimary

要强制连接到辅助实例,请建立到辅助实例的连接并使用connectToPrimary选择通过发行:

Mysql-js > shell.connect(secondary_member) Mysql-js > var cluster1 = dba。getCluster (testCluster {connectToPrimary:假})
提示

记住,辅助实例具有super_read_only =对,因此您不能向它们写入更改。

创建用于管理的用户帐户

用于管理实例的用户帐户不一定是root帐户,但是除了MySQL管理员的完全权限外,还需要为该用户分配元数据表的完全读写权限(超级GRANT选项创建下降等等)。在此过程中,用户icadmin是在InnoDB集群的例子中显示的,和rsadmin在InnoDB副本集的例子。

重要的

在所有实例中,管理员的用户名和密码必须相同。

在8.0.20及更高版本中,使用setupAdminAccount (用户创建或升级一个MySQL用户帐户,该帐户具有管理InnoDB集群或InnoDB副本集所需的权限。使用setupAdminAccount ()操作时,您必须以MySQL用户的身份连接,并具有创建用户的权限,例如root用户。的setupAdminAccount (用户操作还可以使您升级现有MySQL帐户所需的权限dba.upgradeMetadata ()操作。

强制用户参数是您想要创建或升级用于管理该帐户的MySQL帐户的名称。控件接受的用户名的格式setupAdminAccount ()操作遵循标准的MySQL帐户名格式,参见指定帐户名称.用户参数格式为用户名(@宿主在哪里宿主是可选的,如果没有提供它,它默认为通配符。

例如,创建一个名为icadmin来管理一个分配给变量的InnoDB集群myCluster问题:

mysql-js >myCluster.setupAdminAccount ('icadmin新帐号icadmin@%密码丢失。请提供一个。新密码:********确认密码:********创建用户“icadmin@%”。设置用户密码。用户“icadmin@%”创建成功。

如果您已经有一个管理用户,例如使用8.0.20之前的版本创建的更新选择与setupAdminAccount ()操作升级现有用户的权限。这在升级期间是相关的,以确保管理用户是兼容的。例如,升级用户名为icadmin问题:

mysql-js >myCluster.setupAdminAccount ('icadmin', {'update':1})正在更新用户icadmin@%。帐号“icadmin@%”更新成功。

在8.0.20之前的版本中,创建用于管理的用户的首选方法是使用clusterAdmin选择与dba.configureInstance ()操作。的clusterAdmin选项必须与MySQL Shell连接一起使用,该连接基于一个拥有创建具有适当权限的用户的权限的用户,在本例中使用root用户。例如:

mysql-js > dba。configureInstance (root@ic-1:3306, {clusterAdmin:“‘icadmin @ ic - 1%”});

控件接受的用户名的格式setupAdminAccount ()操作和clusterAdmin选项遵循标准的MySQL帐户名格式,参见指定帐户名称

如果只需要读取操作(例如用于监视目的),则可以使用权限更受限的帐户。看到配置AdminAPI用户

详细的日志

在使用生产部署时,为MySQL Shell配置详细日志记录是很有用的。例如,当你准备服务器实例作为InnoDB Cluster的一部分工作时,日志中的信息可以帮助你发现和解决可能发生的任何问题。要使用详细日志级别启动MySQL Shell,请使用——进行日志级别选择:

壳> mysqlsh——进行日志级别= DEBUG3

DEBUG3建议设置为级别,参见——进行日志级别为更多的信息。当DEBUG3MySQL Shell日志文件包含Debug: execute_sql(…)其中包含作为AdminAPI调用的一部分执行的SQL查询。MySQL Shell生成的日志文件位于~ / .mysqlsh / mysqlsh.log在基于unix的系统;在微软Windows系统中,它位于MySQL % APPDATA % \ \ mysqlsh \ mysqlsh.log.看到第9章,MySQL Shell日志和调试为更多的信息。

除了启用MySQL Shell日志级别,您还可以配置AdminAPI在发出每个命令后在MySQL Shell中提供的输出数量。启用AdminAPI的输出量,在MySQL Shell问题:

mysql-js > dba.verbose = 2

这将支持AdminAPI调用的最大输出。现有的产出水平如下:

  • 默认为0或OFF。这提供了最小的输出,在不排除故障时是推荐的级别。

  • 1或ON将每次调用的详细输出添加到AdminAPI。

  • 2将调试输出添加到详细输出中,提供关于对AdminAPI的每次调用所执行内容的完整信息。

MySQL Shell可以选择记录AdminAPI操作使用的SQL语句(沙盒操作除外),也可以在执行时在终端中显示它们。要配置MySQL Shell来完成此操作,请参见第9.4节“AdminAPI操作日志记录”

发现主

当你使用单主InnoDB集群或InnoDB副本集时,你需要连接到主实例执行管理任务,这样配置更改就可以写入元数据。要查找当前主节点,您可以:

  • 使用——redirect-primary选项,以确保目标服务器是InnoDB集群或InnoDB副本集的一部分。如果目标实例不是主实例,MySQL Shell会找到主实例并连接到它。

  • 使用shell.connectToPrimary ([实例密码])操作(在8.0.20版本中添加),它检查目标实例是否属于集群或副本集。如果是,MySQL Shell将打开一个新的会话到主会话,将活动的全局MySQL Shell会话设置为已建立的会话并返回它。

    如果一个实例,则该操作尝试使用活动的全局MySQL Shell会话。如果一个实例如果没有提供且没有活动的全局MySQL Shell会话,则抛出异常。如果目标实例不属于集群或副本集,则操作失败并报错。

  • 使用状态操作,在结果中找到主节点,并手动连接到该实例。

脚本AdminAPI

除了本节演示的交互模式外,MySQL Shell还支持在批处理模式.这使您能够使用AdminAPI和JavaScript或Python编写的脚本自动处理过程,这些脚本可以使用MySQL Shell的——文件选择。例如:

壳> mysqlsh——文件setup-innodb-cluster.js
请注意

在脚本文件名之后指定的任何命令行选项都传递给脚本和MySQL壳。方法可以访问这些选项os.argv数组,或者sys.argv在Python中数组。在这两种情况下,数组中提取的第一个选项是脚本名。

示例脚本文件的内容如下所示:

print('InnoDB集群沙箱设置\n');打印 ('==================================\ n ');print('用3个MySQL Server沙箱实例建立MySQL InnoDB集群,\n');Print('安装在~/mysql-sandboxes中,运行在3310,3320和3330端口上。\n\n');var dbPass = shell。prompt('Please enter a password for MySQL root account: ', {type:"password"});try {print('\n部署沙箱实例');{密码:dbPass} dba.deploySandboxInstance (3310);打印('。');{密码:dbPass} dba.deploySandboxInstance (3320); print('.'); dba.deploySandboxInstance(3330, {password: dbPass}); print('.\nSandbox instances deployed successfully.\n\n'); print('Setting up InnoDB Cluster...\n'); shell.connect('root@localhost:3310', dbPass); var cluster = dba.createCluster("prodCluster"); print('Adding instances to the Cluster.'); cluster.addInstance({user: "root", host: "localhost", port: 3320, password: dbPass}); print('.'); cluster.addInstance({user: "root", host: "localhost", port: 3330, password: dbPass}); print('.\nInstances successfully added to the Cluster.'); print('\nInnoDB Cluster deployed successfully.\n'); } catch(e) { print('\nThe InnoDB Cluster could not be created.\n\nError: ' + + e.message + '\n'); }

AdminAPI也得到MySQL Shell的支持第5.8节,“API命令行集成”.这使您能够轻松地将AdminAPI集成到您的环境中。例如,使用1234端口上监听的沙箱实例来检查一个InnoDB集群的状态:

$ mysqlsh root@localhost:1234——集群状态

这映射到MySQL Shell中的等价命令:

mysql-js > cluster.status ()