4.2.2.2 使用选项文件

大多数 MySQL 程序可以从 选项文件（有时称为 配置文件 ）读取启动选项。选项文件提供了一种方便的方式来指定常用选项，这样每次运行程序时就不需要在命令行中输入这些选项。

要确定程序是否读取选项文件，请使用--help选项调用它。（对于 mysqld ，请使用--verbose和--help。）如果程序读取选项文件，则帮助消息将指示它查找哪些文件以及识别哪些选项组。

注意
以--no-defaults选项启动的 MySQL 程序不会读取.mylogin.cnf以外的选项文件。
在禁用persisted_globals_load系统变量的情况下启动的服务器不会读取mysqld-auto.cnf。

许多选项文件都是可使用任何文本编辑器创建的纯文本文件。例外情况包括：

• 包含登录路径选项的.mylogin.cnf文件。这是一个由 mysql_config_editor 实用程序创建的加密文件。请参见 第4.6.7节 “mysql_config_editor - mysql 配置实用程序” 。“登录路径”是一个选项组，只允许某些选项：host，user，password，port和socket。客户端程序使用--login-path选项指定要从.mylogin.cnf读取的登录路径。
• 要指定备用登录路径文件名，请设置MYSQL_TEST_LOGIN_FILE环境变量。mysql-test-run.pl 测试实用程序使用该变量，但 mysql_config_editor 和 mysql 客户端（如 mysql、mysqladmin 等）也可以识别该变量。
• 数据目录中的mysqld-auto.cnf文件。此 JSON 格式文件包含持久化的系统变量设置。它由服务器在执行SET PERSIST或SET PERSIST_ONLY语句时创建。参见 第5.1.9.3节 “持久系统变量” 。mysqld-auto.cnf的管理应该留给服务器，而不是手动执行。
• 选项文件处理顺序
• 选项文件语法
• 选项文件包含项

选项文件处理顺序

MySQL按照以下讨论中描述的顺序查找选项文件，并读取所有存在的文件。如果要使用的选项文件不存在，请使用刚才讨论的适当方法创建它。

注意
有关与 NDB 集群程序一起使用的选项文件的信息，请参阅 第 23.4 节 “NDB 群集的配置” 。

在 Windows 上，MySQL 程序按照指定的顺序从下表中显示的文件中读取启动选项（先读取先列出的文件，后读取的文件优先）。

表4.1 在 Windows 系统上读取的选项文件

文件名	目的
%WINDIR%\my.ini, %WINDIR%\my.cnf	全局选项
C:\my.ini, C:\my.cnf	全局选项
BASEDIR\my.ini, BASEDIR\my.cnf	全局选项
defaults-extra-file	--defaults-extra-file指定的文件（如果存在）
%APPDATA%\MySQL\.mylogin.cnf	登陆路径选项（仅限客户端）
DATADIR\mysqld-auto.cnf	使用SET PERSIST或SET PERSIST_ONLY持久化的系统变量（仅限服务器）

在上表中，%WINDIR% 表示 Windows 目录的位置。这通常是 C:\WINDOWS。使用以下命令从WINDIR 环境变量的值确定其确切位置：

C:\> echo %WINDIR%

%APPDATA% 表示 Windows 应用程序数据目录的值。使用以下命令根据 APPDATA 环境变量的值确定其确切位置：

C:\> echo %APPDATA%

BASEDIR 表示 MySQL 基本安装目录。当使用 MySQL 安装程序安装 MySQL 8.0 时，通常是C:\PROGRAMDIR\MySQL\MySQL Server 8.0，其中 PROGRAMDIR 表示程序目录（通常是 Windows 英文版的 Program Files ）。请参阅 第2.3.3节 “MySQL Windows 安装程序” 。

在 Unix 和类 Unix 系统上，MySQL 程序按照指定的顺序从下表中显示的文件中读取启动选项（先读取先列出的文件，后读取的文件优先）。

注意
在 Unix 平台上，MySQL 忽略全局可写的配置文件。这是一种安全措施。

表4.2 在 Unix 和类 Unix 系统上读取的选项文件

文件名	目的
/etc/my.cnf	全局选项
/etc/mysql/my.cnf	全局选项
SYSCONFDIR/my.cnf	全局选项
$MYSQL_HOME/my.cnf	服务器指定选项（仅限服务器）
defaults-extra-file	--defaults-extra-file指定的文件（如果存在）
~/.my.cnf	用户特定选项
~/.mylogin.cnf	登陆路径选项（仅限客户端）
DATADIR/mysqld-auto.cnf	使用SET PERSIST或SET PERSIST_ONLY持久化的系统变量（仅限服务器）

在上表中，~ 表示当前用户的主目录（值$home）。
SYSCONFDIR 表示在构建 MySQL 时使用SYSCONFDIR选项为 CMake 指定的目录。默认情况下，这是位于编译后的安装目录下的etc目录。

MYSQL_HOME是一个环境变量，包含特定于服务器的my.cnf文件所在目录的路径。如果未设置MYSQL_HOME，并且使用 mysqld_safe 程序启动服务器，mysqld_safe 会将其设置为 BASEDIR，即 MYSQL 基本安装目录。
DATADIR 表示 MySQL 数据目录。正如用来查找mysqld-auto.cnf的，它的默认值是编译 MySQL 时内置的数据目录位置，但可以通过--datadir进行更改。该--datadir由选项文件或命令行选项指定，然后再处理mysqld-auto.cnf。

如果找到给定选项的多个实例，则最后一个实例优先，但有一个例外：对于 mysqld，--user选项的第一个实例用作安全预防措施，以防止在命令行上覆盖选项文件中指定的用户。

选项文件语法

以下选项文件语法说明适用于手动编辑的文件。这不包括.mylogin.cnf（使用 mysql_config_editor 创建并加密）和服务器以 JSON 格式创建的mysqld-auto.cnf。

在运行 MySQL 程序时，命令行上可能给出的任何长选项也可以在选项文件中给出。要获取程序的可用选项列表，请使用--help选项运行该程序。（对于 mysqld，请使用--verbose和--help。）

在选项文件中指定选项的语法类似于命令行语法（请参阅 第4.2.2.1节 “在命令行上使用选项”）。但是，在选项文件中，可以省略选项名称中前导的两个破折号，并且每行只能指定一个选项。例如，命令行上的--quick和--host=localhost应在选项文件的单独行中指定为quick和host=localhost。要在选项文件中指定形式为 --loose-opt_name 的选项，请将其写为 loose-opt_name 。

忽略选项文件中的空行。非空行可以采用以下任何形式：

• #comment, ;comment
  注释行以#或；开头；。#注释也可以从行的中间开始。
• [group]
  group是要为其设置选项的程序或组的名称。在组行之后，任何选项设置行都将应用于命名组，直到给出选项文件或另一组行的结尾。选项组名称不区分大小写。
• opt_name
  这相当于命令行上的--opt_name。
• opt_name=value
  这相当于命令行上的--opt_name=value。在选项文件中，=字符周围可以有空格，这在命令行中是不正确的。如果该值包含#注释字符，该值可以可选地用单引号或双引号括起来，这很有用。

将自动从选项名称和值中删除前导空格和尾随空格。

您可以在选项值中使用转义序列\b、\t、\n、\r、\\和\s来表示退格、制表符、换行符、回车符、反斜杠和空格字符。在选项文件中，这些转义规则适用：

• 反斜杠后跟有效的转义序列字符将转换为序列所表示的字符。例如，\s转换为空格。
• 未后跟有效转义序列字符的反斜杠保持不变。例如，\S保持原样。
  前面的规则意味着文字反斜杠可以作为\给出，或者如果后面没有有效的转义序列字符，则可以作为\给出。

选项文件中转义序列的规则与 SQL 语句中字符串文本中转义序列规则略有不同。在后一种情况下，如果“x”不是有效的转义序列字符，则**x*变为“x”而不是*x。参见 第9.1.1节 “字符串常量” 。

选项文件值的转义规则尤其适用于 Windows 路径名，这些路径名使用\作为路径名分隔符。Windows 路径名中的分隔符如果后跟转义序列字符，则必须写成\\。如果不是，则可以写成\\或\。或者，/可以在 Windows 路径名中使用，并被视为\。假设您希望在选项文件中指定C:\Program Files\MySQL\MySQL Server 8.0为基础目录。这可以通过多种方式实现。一些示例：

basedir="C:\Program Files\MySQL\MySQL Server 8.0"
basedir="C:\\Program Files\\MySQL\\MySQL Server 8.0"
basedir="C:/Program Files/MySQL/MySQL Server 8.0"
basedir=C:\\Program\sFiles\\MySQL\\MySQL\sServer\s8.0

如果选项组名称与程序名称相同，则组中的选项将专门应用于该程序。例如，[mysqld]和[mysql]组分别应用于 mysqld 服务器和 mysql客户端程序。

[client]选项组由 MySQL 发行版中提供的所有客户端程序读取（但不由 mysqld 读取）。要了解使用C API 的第三方客户端程序如何使用选项文件，请参阅C API 文档的 mysql_options() 部分。

[client]组允许您指定适用于所有客户端的选项。例如，[client]是用于指定连接到服务器的密码的适合的组。（但请确保选项文件只能由您自己访问，这样其他人就无法发现您的密码。）请确保不要将选项放在[client]组中，除非您使用的 所有 客户端程序都能识别该选项。如果您尝试运行无法理解该选项的程序，则会在显示错误消息后退出。

首先列出更通用的选项组，然后列出更具体的选项组。例如，[client]组更通用，因为它由所有客户端程序读取，而[mysqldump]组仅由 mysqldump 读取。稍后指定的选项会覆盖先前指定的选项，因此将选项组按[client]，[mysqldump]的顺序排列，可以使 mysqldump 指定的选项覆盖[client]选项。
以下是一个典型的全局选项文件：

[client]
port=3306
socket=/tmp/mysql.sock

[mysqld]
port=3306
socket=/tmp/mysql.sock
key_buffer_size=16M
max_allowed_packet=128M

[mysqldump]
quick

这是一个典型的用户选项文件：

[client]
# The following password is sent to all standard MySQL clients
password="my password"

[mysql]
no-auto-rehash
connect_timeout=2

要从特定的 MySQL 发布系列中创建仅由 mysqld 服务器读取的选项组，请使用名称为[mysqld-5.7]、[mysqld-8.0]等的组。以下组表示sql_mode设置仅适用于版本号为 8.0.x 的 MySQL 服务器：

[mysqld-8.0]
sql_mode=TRADITIONAL

选项文件包含项

可以在选项文件中使用!include以包含其他选项文件和!includedir可搜索特定目录中的选项文件。例如，要包含/home/mydir/myopt.cnf文件，请使用以下指令：

!include /home/mydir/myopt.cnf

要搜索/home/mydir目录并读取其中找到的选项文件，请使用以下指令：

!includedir /home/mydir

注意
使用 Unix 操作系统上的!includedir指令的文件名必须以 .cnf 结尾。在 Windows 上，该指令检查扩展名为 .ini 或 .cnf 的文件。

像其他选项文件一样编写被包含的选项文件的内容。也就是说，它应该包含一组选项，每个选项前面都有一行[group]，指示应用选项的程序。

在处理被包含的文件时，仅使用当前程序正在查找的组中的选项。其他组将被忽略。假设my.cnf文件包含以下行：

!include /home/mydir/myopt.cnf

然后假设/home/mydir/myopt.cnf 看起来像这样：

[mysqladmin]
force

[mysqld]
key_buffer_size=16M

如果my.cnf由 mysqld 处理，则只使用/home/mydir/myopt.cnf中的[mysqld]组。如果文件由 mysqladmin 处理，则只使用[mysqladmin]组。如果文件由任何其他程序处理，则不会使用/home/mydir/myopt.cnf中的选项。

这个!includedir指令的处理方式类似，只是读取指定目录中的所有选项文件。

如果选项文件包含!include或!includedir指令，每当处理该选项文件时，都会处理由这些指令所指定的文件，无论它们出现在文件中的哪个位置。

要使包含指令生效，文件路径不应在引号内指定，并且不应有转义序列。例如，my.ini中提供的以下语句读取选项文件myopts.ini：

!include C:/ProgramData/MySQL/MySQL Server/myopts.ini
!include C:\ProgramData\MySQL\MySQL Server\myopts.ini
!include C:\\ProgramData\\MySQL\\MySQL Server\\myopts.ini

在 Windows 上，如果include /path/to/extra.ini是文件中的最后一行，请确保在末尾附加新行；否则，将忽略该行。