Docker mysql クイックリファレンス 日本語訳

[Docker Hub の mysql のクイックリファレンス](https://hub.docker.com/_/mysql) の日本語訳。

# MySQL とは?

MySQL は世界で最も人気のあるオープンソースデータベースです。
実証済みのパフォーマンス、信頼性、使いやすさを備えた MySQL は、個人のプロジェクトや Web サイト、 e コマースや情報サービスなど、全範囲をカバーする Web ベースのアプリケーションの主要なデータベースの選択肢になりました。
Facebook、Twitter、YouTube、Yahoo! などの Web プロパティなどでも使用されています。
MySQL Server およびその他の MySQL 製品の詳細および関連するダウンロードについては www.mysql.com にアクセスしてください。

# イメージの使い方
## mysql サーバーインスタンスの開始

MySQL インスタンスの開始は簡単です。

```bash
$ docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag
```

``some-mysql`` はコンテナに割り当てる名前、 ``my-secret-pw`` は MySQL root ユーザーに設定するパスワード、 ``tag`` は必要な MySQL バージョンを指定するタグです。
関連するタグについては、上記のリストを参照してください。
MySQL コマンドラインクライアントから MySQL に接続します。
次のコマンドは、別の mysql コンテナインスタンスを起動し、元の mysql コンテナに対して mysql コマンドラインクライアントを実行して、データベースインスタンスに対して SQL ステートメントを実行できるようにします。

```bash
$ docker run -it --network some-network --rm mysql mysql -hsome-mysql -uexample-user -p
```

``some-mysql`` は、元の mysql コンテナ(Docker ネットワークに接続されている ``some-network`` )の名前です。
このイメージは Docker 以外のインスタンスまたはリモートインスタンスのクライアントとしても使用できます。

```bash
$ docker run -it --rm mysql mysql -hsome.mysql.host -usome-mysql-user -p
```

MySQL コマンドラインクライアントの詳細については MySQL のドキュメントを参照してください。

## docker stack deploy または docker-compose を介した使用法

```bash:stack.yml記述例
# Use root/example as user/password credentials
version: '3.1'

services:

  db:
    image: mysql
    command: --default-authentication-plugin=mysql_native_password
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: example

  adminer:
    image: adminer
    restart: always
    ports:
      - 8080:8080
```

``docker stack deploy -c stack.yml mysql`` (または ``docker-compose -f stack.yml up``)を実行し、完全に初期化されるのを待って http://swarm-ip:8080, http://localhost:8080, または http://host-ip:8080 へアクセスします。

## コンテナシェルへのアクセスと MySQL ログの表示

``docker exec`` コマンドを使用すると Docker コンテナ内でコマンドを実行できます。
次のコマンドラインは mysql コンテナ内に bash シェルを提供します。

```bash
$ docker exec -it some-mysql bash
```

ログは Docker のコンテナログから入手できます。

```
$ docker logs some-mysql
```

## カスタム MySQL 構成ファイルの使用

MySQL のデフォルト設定は ``/etc/mysql/my.cnf`` にあります。
これには ``/etc/mysql/conf.d`` や ``/etc/mysql/mysql.conf.d`` などの追加のディレクトリが含まれている場合があります。
詳細については mysql イメージ内の関連するファイルとディレクトリを調べてください。
``/my/custom/config-file.cnf`` がカスタム構成ファイルのパスと名前である場合、次のように mysql コンテナーを開始できます(このコマンドでは、カスタム構成ファイルのディレクトリー・パスのみが使用されることに注意してください)。

```bash
$ docker run --name some-mysql -v /my/custom:/etc/mysql/conf.d -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag
```

これにより MySQL インスタンスが ``/etc/mysql/my.cnf`` と ``/etc/mysql/conf.d/config-file.cnf`` の起動設定を組み合わせて使用​​し、後者の設定が優先される新しいコンテナ some-mysql が起動します。 

## cnf ファイルを使用しない設定方法

多くの構成オプションをフラグとして mysqld に渡すことができます。これにより ``cnf`` ファイルを必要とせずにコンテナーをカスタマイズできる柔軟性が得られます。
たとえば、すべてのテーブルのデフォルトのエンコーディングと照合順序を変更して UTF-8(utf8mb4)を使用する場合は、次のコマンドを実行するだけです。

```bash
$ docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
```

利用可能なオプションの完全なリストを確認したい場合は以下を実行してください。

```bash
$ docker run -it --rm mysql:tag --verbose --help
```

# 環境変数

mysql イメージを起動するときに ``docker run`` コマンドラインで 1 つ以上の環境変数を渡すことにより、 MySQL インスタンスの構成を調整できます。
すでにデータベースが含まれているデータディレクトリでコンテナを起動した場合、以下の変数はいずれも効果がないことに注意してください。
既存のデータベースは、コンテナの起動時に常に変更されません。
MySQL 自体が尊重する環境変数(特にこのイメージと一緒に使用すると問題を引き起こすことが知られている ``MYSQL_HOST`` のような変数)のドキュメントについては、https://dev.mysql.com/doc/refman/5.7/en/environment-variables.html も参照してください。

## MYSQL_ROOT_PASSWORD

この変数は必須であり MySQL ルートスーパーユーザーアカウントに設定されるパスワードを指定します。
上記の例では ``my-secret-pw`` に設定されています。

## MYSQL_DATABASE

この変数はオプションです。
イメージの起動時に作成されるデータベースの名前を指定できます。
ユーザー / パスワードが指定された場合(以下を参照)、そのユーザーには、このデータベースへのスーパーユーザーアクセス( ``GRANT ALL`` に対応)が付与されます。

## MYSQL_USER, MYSQL_PASSWORD

これらの変数はオプションです。
新しいユーザーを作成し、そのユーザーのパスワードを設定するために組み合わせて使用​​されます。
このユーザーには [MYSQL_DATABASE](#mysql_database) 変数で指定されたデータベースに対するスーパーユーザー権限(上記を参照)が付与されます。
ユーザーを作成するには、両方の変数が必要です。
ルートスーパーユーザーを作成するためにこの仕組みを使用する必要はないことに注意してください。
ルートスーパーユーザーは、デフォルトで [MYSQL_ROOT_PASSWORD](#mysql_root_password) 変数で指定されたパスワードで作成されます。

## MYSQL_ALLOW_EMPTY_PASSWORD

これはオプションの変数です。
``yes`` のように空でない値に設定するとパスワードなしの root ユーザーでコンテナーを開始できます。

注: この変数を ``yes`` に設定することは、何をしているのかを本当に理解していない限りお勧めしません。
これにより MySQL インスタンスが完全に保護されなくなり、誰でも完全なスーパーユーザーアクセスを取得できるようになります。

## MYSQL_RANDOM_ROOT_PASSWORD

これはオプションの変数です。
( ``pwgen`` を使用して) root ユーザーのランダムな初期パスワードを生成するには ``yes`` などの空でない値に設定します。
生成された root パスワードは stdout に出力されます( ``GENERATED ROOT PASSWORD: ......`` )。

## MYSQL_ONETIME_PASSWORD

初期化が完了すると root ユーザー( [MYSQL_USER](#mysql_user-mysql_password) で指定されたユーザーではない)を期限切れとして設定し、最初のログイン時にパスワードの変更を強制します。
空でない値があると、この設定がアクティブになります。

注: この機能は MySQL 5.6 以降でのみサポートされています。
MySQL 5.5 でこのオプションを使用すると、初期化中にエラーが送出されます。

## MYSQL_INITDB_SKIP_TZINFO

デフォルトでは、エントリポイントスクリプトは ``CONVERT_TZ()`` 関数に必要なタイムゾーンデータを自動的にロードします。
不要な場合、空でない値を指定するとタイムゾーンの読み込みが無効になります。

## Docker Secrets

環境変数を介して機密情報を渡す代わりに、前述の環境変数に ``_FILE``を追加して、初期化スクリプトがコンテナ内に存在するファイルからそれらの変数の値をロードするようにすることができます。
特にこれは ``/run/secrets/<secret_name>`` ファイルに保存されている Docker シークレットからパスワードをロードするために使用できます。
例えば:

```bash
$ docker run --name some-mysql -e MYSQL_ROOT_PASSWORD_FILE=/run/secrets/mysql-root -d mysql:tag
```

現在、これは以下の変数でのみサポートされています。

* [MYSQL_ROOT_PASSWORD](#mysql_root_password)
* MYSQL_ROOT_HOST
* [MYSQL_DATABASE](#mysql_database)
* [MYSQL_USER](#mysql_user-mysql_password)
* [MYSQL_PASSWORD](#mysql_user-mysql_password)

# 新しいインスタンスの初期化

コンテナが初めて起動されると、指定された名前の新しいデータベースが作成され、指定された構成変数で初期化されます。
さらに ``/docker-entrypoint-initdb.d`` にある拡張子 ``.sh`` 、 ``.sql`` 、および ``.sql.gz`` のファイルを実行します。
ファイルはアルファベット順に実行されます。
SQL ダンプをそのディレクトリにマウントし、提供されたデータを含むカスタムイメージを提供することで、 mysql サービスに簡単にデータを取り込むことができます。
SQL ファイルは、デフォルトで [MYSQL_DATABASE](#mysql_database) 変数で指定されたデータベースにインポートされます。

# データの保存場所

重要な注意: Docker コンテナで実行されるアプリケーションが使用するデータを保存する方法はいくつかあります。
mysql イメージのユーザーは、次のような利用可能なオプションに慣れることをお勧めします。

Docker に独自の内部ボリューム管理を使用してホストシステム上のディスクにデータベースファイルを書き込むことにより、データベースデータのストレージを管理させます。
これはデフォルトであり、ユーザーにとって簡単でかなり透過的です。
欠点はホストシステム上で直接実行されるツールやアプリケーション、つまりコンテナの外部ではファイルを見つけるのが難しい場合があることです。
ホストシステム(コンテナの外側)にデータディレクトリを作成し、これをコンテナの内側から見えるディレクトリにマウントします。
これにより、データベースファイルがホストシステムの既知の場所に配置され、ホストシステム上のツールやアプリケーションがファイルに簡単にアクセスできるようになります。
欠点はユーザーがディレクトリが存在することを確認する必要があることと、ホストシステムのディレクトリ権限およびその他のセキュリティメカニズムが正しく設定されていることを確認する必要があることです。

Docker のドキュメントは、さまざまなストレージオプションとバリエーションを理解するための良い出発点であり、この分野で議論し、アドバイスを提供するブログやフォーラムの投稿が複数あります。
上記の後者のオプションの基本的な手順をここで簡単に示します。

ホストシステムの適切なボリュームに ``/my/own/datadir`` のようなデータディレクトリを作成します。
次のように mysql コンテナを起動します。

```bash
$ docker run --name some-mysql -v /my/own/datadir:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag
```

コマンドの ``-v /my/own/datadir:/var/lib/mysql`` の部分は、基礎となるホストシステムから ``/my/own/datadir`` ディレクトリをコンテナ内の ``/var/lib/mysql`` としてマウントします。
MySQL はデフォルトでデータファイルを書き込みます。
MySQL の初期化が完了するまで接続はありません。
コンテナの起動時に初期化されたデータベースがない場合は、デフォルトのデータベースが作成されます。
これは予想される動作ですが、初期化が完了するまで着信接続を受け入れないことを意味します。
これにより、複数のコンテナーを同時に起動する docker-compose などの自動化ツールを使用するときに問題が発生する可能性があります。
MySQL に接続しようとしているアプリケーションが MySQL のダウンタイムを処理しない場合、または MySQL が正常に起動するのを待っている場合は、サービスが開始する前に接続と再試行のループを設定する必要があります。
公式イメージでのそのような実装の例については WordPress または Bonita を参照してください。

# 既存のデータベースに対する使用法

すでにデータベースが含まれているデータディレクトリ(具体的には ``mysql`` サブディレクトリ)で mysql コンテナインスタンスを起動する場合は、実行コマンドラインから ``$MYSQL_ROOT_PASSWORD`` 変数を省略してください。
上記変数を指定した場合でも無視され、既存のデータベースは変更されません。

# 任意のユーザーとして実行する方法

ディレクトリの権限がすでに適切に設定されていることがわかっている場合(上記のように既存のデータベースに対して実行する場合など)、または特定の UID/GID を使用して mysqld を実行する必要がある場合は、 ``--user`` を使用してこのイメージを呼び出すことができます。
目的の接続/構成を実現するには、任意の値(root/0 以外)に設定します。

```bash
$ mkdir data
$ ls -lnd data
drwxr-xr-x 2 1000 1000 4096 Aug 27 15:54 data
$ docker run -v "$PWD/data":/var/lib/mysql --user 1000:1000 --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag
```

# データベースダンプの作成

通常のツールのほとんどは機能しますが、 mysqld サーバーにアクセスできるようにするために、使用法が少し複雑になる場合があります。
これを確認する簡単な方法は ``docker exec`` を使用して、次のように同じコンテナーからツールを実行することです。

```bash
$ docker exec some-mysql sh -c 'exec mysqldump --all-databases -uroot -p"$MYSQL_ROOT_PASSWORD"' > /some/path/on/your/host/all-databases.sql
```

# ダンプファイルからのデータリストア

データの復元用。
次のように ``-i`` フラグを指定して ``docker exec`` コマンドを使用できます。

```bash
$ docker exec -i some-mysql sh -c 'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD"' < /some/path/on/your/host/all-databases.sql
```

# ライセンス

このイメージに含まれているソフトウェアのライセンス情報を表示します。
すべての Docker イメージと同様に、これらには他のライセンスの下にある可能性のある他のソフトウェア(ベースディストリビューションの Bash など、プラ​​イマリソフトウェアに含まれている直接的または間接的な依存関係)も含まれている可能性があります。
自動検出できたいくつかの追加のライセンス情報は repo-info リポジトリの ``mysql/`` ディレクトリにある可能性があります。
ビルド済みのイメージの使用に関しては、このイメージの使用がそれに含まれるすべてのソフトウェアの関連するライセンスに準拠していることを確認するのは、イメージユーザーの責任です。