MySQLリファレンス｜「オプションファイルの使用」

2020年10月16日 14:32

MySQL 8.0リファレンスマニュアル「4.2.2.2 Using Option Files」の私家版和訳です。

こちらも先日の記事「MySQLの設定ファイル「my.cnf」は、どこに置く？」関連です。

my.cnfの具体的な構文だったり、オプション値とオプショングループの処理順番だったり、他の構成ファイルのインクルードだったりを、押さえておかないと…ってことで、私家版和訳してみました。

以下、本文です。

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、mysqladmin等のMySQLクライアントでも認識されます。
・ディレクトリ「data」内のファイル「mysqld-auto.cnf」…このJSON形式のファイルには、永続化されたシステム変数の設定が保存されています。これはステートメント「SET PERSIST」やステートメント「SET PERSIST_ONLY」の実行時に、サーバーによって生成されます。項5.1.9.3「永続化されたシステム変数」を参照してください。「mysqld-auto.cnf」の管理はサーバーに任せ、手動では管理しないでください。

オプションファイルの処理順序

MySQLは、以下の議論で説明されている順番でオプションファイルを探し、存在するものを全て読み取ります。使用したいオプションファイルが存在しない場合は、説明するように適切な方法で作成してください。

注：NDBクラスタプログラムで使用されるオプションファイルについては、項22.3 「NDBクラスターの構成」を参照してください。

Windowsでは、MySQLプログラムは、次の表に示すファイルから指定された順序で起動オプションを読み取ります（最初にリストアップされたファイルが先に読み取られ、後に読み取られたファイルが優先されます）。

表4.1 Windowsシステムで読み取られるオプションファイル

ファイル名：目的
1.　「%WINDIR%\my.ini」、「%WINDIR%\my.cnf」：グローバルオプション
2.　「C:\my.ini」、「C:\my.cnf」：グローバルオプション
3.　「BASEDIR\my.ini」、「BASEDIR\my.cnf」：グローバルオプション
4.　「defaults-extra-file」：（指定されてる場合）「--defaults-extra-file」で指定されたファイル
5.　「%APPDATA%\MySQL\.mylogin.cnf」：（クライアントのみ）ログインパス・オプション
6.　「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 8.0がMySQL Installerを使用してインストールされている場合、これは典型的には「C:\PROGRAMDIR\MySQL\MySQL 8.0 Server」で、「PROGRAMDIR」はプログラムのディレクトリ（英語版Windowsの場合、通常「Program Files」）を表します。項2.3.3 「Windows向けMySQL Installer」を参照してください。

「DATADIR」は、MySQLデータのディレクトリを表します。「mysqld-auto.cnf」の検索に用いられる場合、そのデフォルト値は、MySQLコンパイル時にビルトインされたデータディレクトリの場所だが、「mysqld-auto.cnf」が処理される前に、オプションファイル或いはコマンドライン・オプションとして「--datadir」を指定する事で、変更できます。

Unix及びUnixライクなシステムでは、MySQLプログラムは、次の表に示すファイルから指定された順序で起動オプションを読み取ります（最初にリストアップされたファイルが先に読み取られ、後に読み取られたファイルが優先されます）

注：Unixプラットフォームでは、MySQLは誰でも書き込み可能な構成ファイルを無視します。これはセキュリティ対策として意図的に行われています。

表4.2 Unix及びUnixライクなシステムで読み取られるオプションファイル

ファイル名：目的
1.　「/etc/my.cnf」：グローバルオプション
2.　「/etc/mysql/my.cnf」：グローバルオプション
3.　「SYSCONFDIR/my.cnf」：グローバルオプション
4.　「$MYSQL_HOME/my.cnf」：（サーバーのみ）サーバー固有のオプション
5.　「defaults-extra-file」：（指定されてる場合）「--defaults-extra-file」で指定されたファイル
6.　「~/.my.cnf」：ユーザー固有のオプション
7.　「~/.mylogin.cnf」：（クライアントのみ）ユーザー固有のログインパス・オプション
8.　「DATADIR/mysqld-auto.cnf」：（サーバーのみ）「SET PERSIST」または「SET PERSIST_ONLY」で永続化されたシステム変数

上記の表では、「~」は、カレント・ユーザーのホーム・ディレクトリ（「$HOME」の値）を表します。

「SYSCONFDIR」は、MySQLのビルド時に、CMakeに対してオプション「SYSCONFDIR」で指定されたディレクトリを表します。デフォルトでは、これはコンパイル済のインストール先ディレクトリ内のディレクトリ「etc」です。

「MYSQL_HOME」は、サーバー固有のファイル「my.cnf」が存在するディレクトリへのパスを含む環境変数です。「MYSQL_HOME」未設定でmysqld_safeプログラムを使用してサーバーを起動すると、mysqld_safeは、MySQLのベースとなるインストール先ディレクトリ、「BASEDIR」に設定します。

与えられたオプションの複数のインスタンスが見つかった場合、1つの例外を除いて最後のインスタンスが優先されます：mysqldの場合、オプションファイル内で指定されたユーザーがコマンドラインでオーバーライドされないように、オプション「--user」の最初のインスタンスがセキュリティ対策として使用されます。

オプションファイルの構文

以下のオプションファイルの構文に関する説明は、手動で編集するファイルに適用されます。これは、mysql_config_editorを用いて暗号化されて生成される「.mylogin.cnf」と、サーバーがJSONフォーマットで生成する「mysqld-auto.cnf」を除きます。

MySQLプログラムの実行時にコマンドラインで指定できる長いオプションは、オプションファイルでも指定できます。プログラムで利用可能なオプションのリストを取得するには、オプション「--help」を指定して実行します（mysqldでは、オプション「--verbose」と「--help」を使用）。

オプションファイル内でオプションを指定する為の構文は、コマンドライン構文に似ています（項4.2.2.1 「コマンドラインでオプションを使用する」を参照）。但し、オプションファイルでは、オプション名の先頭の２つのダッシュを省略し、1行に1つのオプションのみを指定します。例えば、コマンドラインの「--quick」と「--host=localhost」は、オプションファイルの別々の行で「quick」と「host=localhost」のように、指定する必要があります。オプションファイル内で「--loose-オプション名」形式のオプションを指定するには、「loose-オプション名」と記述します。

オプションファイル内で空行は無視されます。空ではない行は、以下のいずれかの形式を採ります：

・「#コメント」、「;コメント」…コメント行は「#」または「;」で始まります。「#」コメントは、行の途中から始めることもできます。
・「[グループ]」…グループは、オプションを設定したいプログラムまたはグループの名前です。グループ行以降は、オプションファイルの終端または別のグループ行が指定される迄、オプション設定行は、指定グループに適用されます。オプショングループ名は大文字小文字を区別しません。
・「オプション名」…これは、コマンドラインの「--オプション名」と同等です。
・「オプション名=値」…これは、コマンドラインの「--オプション名=値」と同等です。オプションファイルでは「=」文字の前後にスペースを挟めるが、コマンドラインでは真ではありません。値は、引用符または二重引用符で囲めるが、これは値に「#」コメント文字が含まれている場合に便利です。

先頭と末尾のスペースは、オプション名と値から、自動的に削除されます。

オプション値では、エスケープシーケンスを用いて、「\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を使用するサードパーティのクライアントプログラムが、オプションファイルを使用する方法を理解するには、mysql_options()のC APIドキュメントを参照してください。

グループ「[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]
# 以下のパスワードは、全ての標準MySQLクライアントに送られる
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

MySQLは、ディレクトリ内のオプションファイルの読み取り順については、保証していません。

注：Unixオペレーティングシステム上では、ディレクティブ「!includeir」を用いて検出されインクルードされるファイルは、すべてファイル名が「.cnf」で終わる必要があります。Windowsでは、このディレクティブは、拡張子が「.ini」または「.cnf」であるファイルをチェックします。

他のオプションファイルのように、インクルードされたオプションファイルの内容を、記述します。つまり、オプショングループが含まれている必要があり、各グループの前には、オプションが適用されるプログラムを示す「[グループ]」行があります。

インクルードされたファイルが処理される間は、現在のプログラムが探しているグループ内のオプションのみが使用されます。それ以外のグループは無視されます。ファイル「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]」のみが使用されます。そのファイル「/home/mydir/myopt.cnf」がmysqladminによって処理される場合、グループ「[mysqladmin]」のみが使用されます。ファイル「/home/mydir/myopt.cnf」が他のプログラムによって処理される場合、「/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」がファイルの最後の行である場合は、ファイル終端に改行文字が追加されていることを確認してください；そうでなければ、その行は無視されます。