MySQL - MySQL Shell

概要

MySQL Shell (mysqlsh) は、MySQL用の高度なコマンドラインクライアントおよびコードエディタである。
従来のmysqlクライアントの後継として開発され、SQL、JavaScript、Pythonの3つの言語をサポートする対話型シェルおよびスクリプティング環境を提供する。

MySQL Shellは、MySQLサーバへの接続、クエリ実行、データベース管理に加えて、以下の高度な機能を備えている。
AdminAPIによるInnoDB Cluster、InnoDB ClusterSet、InnoDB ReplicaSetの管理、X DevAPIによるドキュメントストア操作、データのダンプ・復元ユーティリティ、アップグレードチェッカー、プラグインシステムによる機能拡張が可能である。

MySQL 8.0以降では、MySQL Shellが推奨される管理ツールとなっている。
従来のmysqlクライアントに比べて、対話的な操作性、自動補完機能、構文ハイライト、複数言語サポート、高度な管理APIの面で優れている。

MySQL Shellは、X Protocolとクラシック MySQL Protocolの両方をサポートする。
X Protocolは、MySQL 8.0で導入された新しいプロトコルであり、ドキュメントストア機能やRESTful操作を提供する。

主要な使用場面として、InnoDB Clusterの構築・運用管理、データベースの論理バックアップと復元、MySQL 5.7から8.0へのアップグレード準備、ドキュメント指向データベースとしてのMySQLの利用、スクリプトによる自動化処理がある。

MySQL Shell 8.0以降では、VS Code統合拡張機能 (MySQL Shell for VS Code) も提供されており、GUI環境でのMySQL管理も可能である。

動作環境は、Linux、Windows、MacOSをサポートし、MySQL 5.7以降のサーバに接続可能である。

インストール

Linux

RHEL

MySQL Yumリポジトリを追加してインストールする。

sudo dnf install https://dev.mysql.com/get/mysql80-community-release-el9-5.noarch.rpm
sudo dnf install mysql-shell

SUSE

MySQL公式リポジトリを追加してインストールする。

# リポジトリを追加
sudo zypper addrepo https://dev.mysql.com/get/mysql84-community-release-sl15-1.noarch.rpm

# リポジトリを更新
sudo zypper refresh

# MySQL Shellをインストール
sudo zypper install mysql-shell

Windows

• MSIインストーラを使用する方法
  1. MySQL公式Webサイト (https://dev.mysql.com/downloads/shell/) からMSIインストーラをダウンロードして実行する。
  2. インストールウィザードの指示に従って進める。
  3. デフォルトインストールパスは C:\Program Files\MySQL\MySQL Shell 8.0 である。
• ZIP形式パッケージを使用する方法
  1. MySQL公式WebサイトからZIPファイルをダウンロードする。
  2. 任意のディレクトリに解凍する。
  3. 解凍先の bin ディレクトリを環境変数PATHに追加する。

環境変数 PATH への追加方法を以下に示す。

 # PowerShellを管理者として実行
 
 # 環境変数PATHに追加
 [Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\MySQL\MySQL Shell 8.0\bin", [EnvironmentVariableTarget]::Machine)

MacOS

MacOS環境でのインストール方法を以下に示す。

• DMGファイルを使用する方法
  1. MySQL公式Webサイト (https://dev.mysql.com/downloads/shell/) からDMGファイルをダウンロードする。
  2. DMGファイルをマウントしてインストーラを実行する。
  3. インストールウィザードの指示に従って進める。
• Homebrewを使用する方法
  1. 以下に示すコマンドを実行する。

     brew install mysql-shell

インストールの確認

インストールが正常に完了したかを確認する方法を以下に示す。

# バージョン確認
mysqlsh --version

# 出力例
# mysqlsh   Ver 8.0.35 for Linux on x86_64 - for MySQL 8.0.35 (MySQL Community Server (GPL))

MySQL Shellの起動確認を以下に示す。

 # MySQL Shellを起動
 mysqlsh
 
 # 出力例
 # MySQL Shell 8.0.35
 #
 # Copyright (c) 2016, 2023, Oracle and/or its affiliates.
 # Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
 # Other names may be trademarks of their respective owners.
 #
 # Type '\help' or '\?' for help; '\quit' to exit.
 #  MySQL  JS >

プロンプトが表示されれば、インストールは成功している。
\quit または \q コマンドで終了できる。

接続と認証

MySQL Shellは、クラシックMySQL Protocol と X Protocolの2つの接続方式をサポートする。
接続方法は、URIスキームまたはコマンドラインオプションで指定する。

接続URI形式

MySQL Shellでは、標準的なURI形式で接続先を指定できる。

基本的なURI形式を以下に示す。

[scheme://][user[:[password]]@]host[:port][/schema][?attribute1=value1&attribute2=value2...]

下表に、各要素の説明を示す。

MySQL 接続URIの構成要素

要素	説明
scheme	mysqlx (X Protocol) または mysql (Classic Protocol)
user	MySQLユーザアカウント名
password	パスワード (セキュリティ上、URIに含めないことを推奨)
host	ホスト名またはIPアドレス
port	ポート番号 (X Protocol: 33060、Classic: 3306)
schema	接続後のデフォルトスキーマ
attribute	接続オプション (ssl-mode、compression等)

接続URI例を以下に示す。

 # X Protocol接続 (デフォルトポート33060)
 mysqlsh mysqlx://user_name@localhost:33060
 
 # Classic Protocol接続 (デフォルトポート3306)
 mysqlsh mysql://root@192.168.1.100:3306/mydb
 
 # スキーマ指定あり
 mysqlsh mysqlx://user@localhost:33060/testdb
 
 # SSL接続を強制
 mysqlsh mysqlx://user@localhost:33060/testdb?ssl-mode=REQUIRED
 
 # 複数の接続オプション指定
 mysqlsh mysqlx://user@localhost:33060?ssl-mode=REQUIRED&compression=zstd

パスワードをURIに含める場合 (非推奨) の例を以下に示す。

# パスワードをURIに含める (セキュリティリスクあり)
mysqlsh mysql://root:password@192.168.1.100:3306/mydb

ただし、セキュリティ上の理由から、パスワードは対話式で入力することを推奨する。

クラシックセッション (MySQL Protocol)

クラシックセッションは、従来のMySQL接続プロトコルを使用する。
SQL実行専用であり、X DevAPIは使用できない。

クラシックセッションでの接続方法を以下に示す。

# URI形式
mysqlsh mysql://user@localhost:3306

# コマンドラインオプション形式
mysqlsh --mysql -u user -h localhost -P 3306

# パスワードを対話式で入力
mysqlsh --mysql -u root -h localhost -p

対話型モードでの接続例を以下に示す。

# MySQL Shellを起動
mysqlsh

# 対話型モードで接続
MySQL  JS > \connect mysql://user@localhost:3306
Creating a Classic session to 'user@localhost:3306'
Please provide the password for 'user@localhost:3306': ****

クラシックセッションの特徴を以下に示す。

• 従来のMySQLプロトコル使用
• SQL文の実行のみサポート
• MySQL 5.7以前のサーバにも接続可能
• デフォルトポート

  3306

Xプロトコルセッション (X DevAPI)

Xプロトコルセッションは、MySQL X Pluginを使用した新しいプロトコルである。
SQL、JavaScript、Pythonでの実行が可能であり、ドキュメントストア機能もサポートする。

Xプロトコルセッションでの接続方法を以下に示す。

 # URI形式
 mysqlsh mysqlx://user@localhost:33060
 
 # コマンドラインオプション形式
 mysqlsh --mysqlx -u user -h localhost -P 33060
 
 # パスワードを対話式で入力
 mysqlsh --mysqlx -u root -h localhost -p

Xプロトコルセッションの特徴を以下に示す。

• 新しいMySQLプロトコル (MySQL X Plugin使用)
• SQL、JavaScript、Pythonで実行可能
• JSON/ドキュメントストア機能対応
• CRUD操作のAPI提供
• デフォルトポート: 33060

MySQL Serverで X Plugin が有効になっているかを確認する方法を以下に示す。

 -- X Pluginの状態確認
 SHOW PLUGINS;
 
 -- X Pluginがインストールされているか確認
 SELECT * FROM information_schema.PLUGINS WHERE PLUGIN_NAME = 'mysqlx';

X Pluginが無効の場合は、以下のコマンドで有効化する。

 -- X Pluginをインストール
 INSTALL PLUGIN mysqlx SONAME 'mysqlx.so';

なお、MySQL 8.0以降では、X Pluginはデフォルトで有効化されている。

接続オプション

下表に、MySQL Shellの接続時に使用可能な主要なコマンドラインオプションを示す。

接続関連オプション

オプション	短縮形	説明
--host	-h	ホスト名またはIPアドレス
--port	-P	ポート番号 (X Protocol: 33060、Classic: 3306)
--user	-u	ユーザ名
--password	-p	パスワード (値を指定しない場合は対話式入力)
--socket	-S	UNIXソケットファイルのパス
--ssl-mode		SSL接続モード (DISABLED、PREFERRED、REQUIRED、VERIFY_CA、VERIFY_IDENTITY)
--ssl-ca		CA証明書ファイルのパス
--ssl-cert		クライアント証明書ファイルのパス
--ssl-key		クライアント秘密鍵ファイルのパス
--get-server-public-key		サーバ公開鍵を取得
--auth-method		認証方法を指定
--mysql	-mc	クラシックセッションを使用
--mysqlx	-mx	Xプロトコルセッションを使用

• SSL接続の例

   # SSL接続を強制 (証明書検証あり)
   mysqlsh --ssl-mode=REQUIRED --ssl-ca=/path/to/ca.pem --ssl-cert=/path/to/client-cert.pem --ssl-key=/path/to/client-key.pem -u user -h localhost
   
   # URI形式でSSL接続を指定
   mysqlsh mysqlx://user@localhost:33060?ssl-mode=REQUIRED&ssl-ca=/path/to/ca.pem
  

  
  

• 認証方式の指定例

   # 認証方式を指定
   mysqlsh --auth-method=caching_sha2_password -u user -h localhost
  

接続の管理

対話型モード内での接続管理方法を以下に示す。

 # MySQL Shellを起動
 mysqlsh
 
 # MySQL Protocolで接続
 MySQL  JS > \connect mysql://user@localhost:3306
 
 # X Protocolで接続
 MySQL  JS > \connect mysqlx://user@localhost:33060
 
 # オプション付き接続
 MySQL  JS > \connect --mysql -u user -h localhost
 
 # セッション情報の確認
 MySQL  JS > \status
 
 # 接続を切断
 MySQL  JS > \disconnect

• JavaScriptモードでの接続管理

   // X Protocol接続
   shell.connect('mysqlx://user@localhost:33060')
   
   // Classic Protocol接続
   shell.connect('mysql://user@localhost:3306')
   
   // 現在のセッション情報を取得
   session
   
   // セッションを閉じる
   session.close()
  

  
  

• Pythonモードでの接続管理

   # X Protocol接続
   shell.connect('mysqlx://user@localhost:33060')
   
   # Classic Protocol接続
   shell.connect('mysql://user@localhost:3306')
   
   # 現在のセッション情報を取得
   session
   
   # セッションを閉じる
   session.close()
  

モードの切り替え

MySQL Shellは、SQLモード、JavaScriptモード、Pythonモードの3つの言語モードをサポートする。
モードの切り替えは、\sql、\js、\py コマンドで行う。

SQLモード

SQLモードは、SQL文を直接実行するモードである。
従来のmysqlクライアントと同様の操作が可能である。

• SQLモードへの切り替え方法

   # SQLモードに切り替え
   MySQL  JS > \sql
   Switching to SQL mode... Commands end with ;
   
   # プロンプトが変化する
   MySQL  SQL >
  

  
  

• SQLモードでのクエリ実行例

   MySQL  SQL > SHOW DATABASES;
   MySQL  SQL > USE mydb;
   MySQL  SQL > SELECT * FROM users LIMIT 10;
   MySQL  SQL > CREATE TABLE test (id INT PRIMARY KEY, name VARCHAR(100));
  

SQLモードの特徴を以下に示す。

• SQL文の直接実行
• セミコロン (;) で文を終了
• 複数行にわたるSQL文の実行が可能
• MySQL Serverへの直接クエリ実行

JavaScriptモード

JavaScriptモードは、JavaScript言語でMySQLを操作するモードである。
MySQL Shellのデフォルトモードである。

• JavaScriptモードへの切り替え方法

   # JavaScriptモードに切り替え
   MySQL  SQL > \js
   Switching to JavaScript mode...
   
   # プロンプトが変化する
   MySQL  JS >
  

  
  

• JavaScriptモードでの操作例

   // SQL実行
   session.runSql('SHOW DATABASES')
   
   // データベース操作
   db = session.getSchema('mydb')
   
   // テーブル操作
   table = db.getTable('users')
   result = table.select().limit(10).execute()
   
   // AdminAPI操作
   cluster = dba.getCluster()
   cluster.status()
  

JavaScriptモードの特徴を以下に示す。

• JavaScript言語の完全サポート
• AdminAPI、X DevAPI、ShellAPIの利用が可能
• オブジェクト指向のAPI
• スクリプトファイルの実行が可能

Pythonモード

Pythonモードは、Python言語でMySQLを操作するモードである。

• Pythonモードへの切り替え方法

   # Pythonモードに切り替え
   MySQL  JS > \py
   Switching to Python mode...
   
   # プロンプトが変化する
   MySQL  Py >
  

  
  

• Pythonモードでの操作例

   # SQL実行
   session.run_sql('SHOW DATABASES')
   
   # データベース操作
   db = session.get_schema('mydb')
   
   # テーブル操作
   table = db.get_table('users')
   result = table.select().limit(10).execute()
   
   # AdminAPI操作
   cluster = dba.get_cluster()
   cluster.status()
  

Pythonモードの特徴を以下に示す。

• Python言語の完全サポート
• AdminAPI、X DevAPI、ShellAPIの利用が可能
• Pythonライブラリとの統合が可能
• スクリプトファイルの実行が可能

デフォルトモードの設定

MySQL Shell起動時のデフォルトモードを変更する方法を以下に示す。

• コマンドラインオプションでモードを指定する方法

   # JavaScriptモードで起動
   mysqlsh --js
   
   # Pythonモードで起動
   mysqlsh --py
   
   # SQLモードで起動
   mysqlsh --sql
  

  
  

• 永続的にデフォルトモードを変更する方法

   // デフォルトモードをJavaScriptに設定
   shell.options.setPersist('defaultMode', 'js')
   
   // デフォルトモードをPythonに設定
   shell.options.setPersist('defaultMode', 'py')
   
   // デフォルトモードをSQLに設定
   shell.options.setPersist('defaultMode', 'sql')
  

設定は、~/.mysqlsh/mysqlsh.json (Linux / MacOS) または %APPDATA%\MySQL\mysqlsh\mysqlsh.json (Windows) に保存される。

基本操作

対話型シェルの使用

対話型シェルは、コマンドを1つずつ実行するモードである。

• MySQL Shellの起動方法

   # MySQL Shellを起動
   mysqlsh
   
   # 接続と同時に起動 (X Protocol)
   mysqlsh mysqlx://user@localhost:33060
   
   # 接続と同時に起動 (Classic Protocol)
   mysqlsh mysql://user@localhost:3306
   
   # SQLモードで起動
   mysqlsh --sql -u user -h localhost
  

  
  

• 対話型シェルでの基本コマンド

   # ヘルプ表示
   \help
   \?
   
   # 接続
   \connect mysql://user@localhost:3306
   
   # モード切り替え
   \sql
   \js
   \py
   
   # 接続状態確認
   \status
   
   # 切断
   \disconnect
   
   # 終了
   \quit
   \q
   \exit
  

バッチモード (スクリプト実行)

• スクリプトファイルを実行する方法

   # JavaScriptファイルを実行
   mysqlsh --file script.js
   
   # Pythonファイルを実行
   mysqlsh --file script.py
   
   # SQLファイルを実行
   mysqlsh --file script.sql
   
   # 標準入力からSQL実行
   mysqlsh --sql < query.sql
   
   # 接続先を指定してスクリプト実行
   mysqlsh mysql://user@localhost:3306 --file backup.js
  

  
  

• 対話型モード内でのスクリプト実行

   # JavaScriptファイルを実行
   MySQL  JS > \source /path/to/script.js
   
   # Pythonファイルを実行
   MySQL  Py > \source /path/to/script.py
   
   # SQLファイルを実行
   MySQL  SQL > \source /path/to/query.sql
  

コマンド履歴と自動補完

MySQL Shellは、コマンド履歴と自動補完機能を提供する。

コマンド履歴のナビゲーション方法を以下に示す。

• 矢印キー (上下) で過去のコマンドを呼び出し
• [Ctrl] + [R]キーで履歴の逆方向検索
• [Ctrl] + [S]キーで履歴の順方向検索

コマンド履歴は、以下のファイルに保存される。

• Linux / MacOS

  ~/.mysqlsh/mysqlsh_history

• Windows

  %APPDATA%\MySQL\mysqlsh\mysqlsh_history

• 自動補完の使用方法
  • Tabキーで補完候補を表示
  • スキーマ名、テーブル名、カラム名の補完
  • コマンド、関数名の補完

  
  

• 自動補完の設定変更を以下に示す。

   // 自動補完を無効化
   shell.options.set('autocomplete.nameCache', false)
   
   // 履歴自動保存を無効化
   shell.options.set('history.autoSave', false)
  

ヘルプシステム

MySQL Shellのヘルプシステムの使用方法を以下に示す。

 # 一般的なヘルプ表示
 \help
 \?
 
 # コマンド一覧表示
 \help commands
 
 # 特定の関数のヘルプ表示
 \help dba.createCluster
 
 # AdminAPIのヘルプ
 \help dba
 
 # X DevAPIのヘルプ
 \help mysqlx

JavaScriptモードでのヘルプ表示を以下に示す。

 // オブジェクトのヘルプ
 dba.help()
 
 // メソッドのヘルプ
 dba.help('createCluster')
 
 // シェルオブジェクトのヘルプ
 shell.help()

出力フォーマットの設定を以下に示す。

 // テーブル形式 (デフォルト)
 shell.options.set('resultFormat', 'table')
 
 // JSON形式
 shell.options.set('resultFormat', 'json')
 
 // JSON形式 (整形)
 shell.options.set('resultFormat', 'json/pretty')
 
 // タブ区切り形式
 shell.options.set('resultFormat', 'tabbed')
 
 // 縦形式
 shell.options.set('resultFormat', 'vertical')

AdminAPI

AdminAPIは、MySQL高可用性デプロイメントの管理を簡素化するAPI群である。
InnoDB Cluster、InnoDB ClusterSet、InnoDB ReplicaSetの構築・運用管理を自動化する。

AdminAPIとは

AdminAPIは、dba グローバルオブジェクトを通じて提供される。
主要な機能として、InnoDB Clusterの作成・管理、InnoDB ReplicaSetの作成・管理、InnoDB ClusterSetの作成・管理、サーバ設定の検証・調整がある。

下表に、AdminAPIの主要オブジェクトを示す。

AdminAPI の主要オブジェクト

オブジェクト	説明
dba	AdminAPIのエントリポイント
Cluster	InnoDB Clusterオブジェクト
ReplicaSet	InnoDB ReplicaSetオブジェクト
ClusterSet	InnoDB ClusterSetオブジェクト

InnoDB Cluster

InnoDB Clusterは、Group Replicationベースの高可用性ソリューションである。
自動フェイルオーバー、自動メンバー管理、読み書き分離をサポートする。

クラスタの作成

InnoDB Clusterを作成する手順を以下に示す。

 // サーバ設定の確認
 dba.checkInstanceConfiguration('user@host1:3306')
 
 // サーバ設定の調整 (必要な場合)
 dba.configureInstance('user@host1:3306')
 
 // クラスタの作成
 cluster = dba.createCluster('MyCluster')
 
 // クラスタの状態確認
 cluster.status()

クラスタ作成時のオプション指定例を以下に示す。

 // オプション指定
 cluster = dba.createCluster('MyCluster', {
    multiPrimary: false,
    force: false,
    adoptFromGR: false,
    memberWeight: 50,
    consistency: 'EVENTUAL',
    expelTimeout: 5
 })

下表に、主要なオプションの説明を示す。

dba.createCluster() オプション

オプション	説明
multiPrimary	マルチプライマリモード (デフォルト: false、シングルプライマリモード)
force	Group Replicationが既に実行中でも強制的にクラスタを作成
adoptFromGR	既存のGroup Replicationクラスタを採用
consistency	読み取り整合性レベル (EVENTUAL、BEFORE_ON_PRIMARY_FAILOVER、BEFORE、AFTER、BEFORE_AND_AFTER)
expelTimeout	メンバー除外タイムアウト (秒)

クラスタへのインスタンス追加

クラスタにインスタンスを追加する方法を以下に示す。

 // クラスタオブジェクトを取得
 cluster = dba.getCluster()
 
 // インスタンスを追加
 cluster.addInstance('user@host2:3306')
 
 // パスワード指定
 cluster.addInstance('user@host3:3306', {password: 'pass'})
 
 // クローン方式でリカバリ
 cluster.addInstance('user@host4:3306', {recoveryMethod: 'clone'})

インスタンス追加時のオプション指定例を以下に示す。

 cluster.addInstance('user@host2:3306', {
    password: 'pass',
    recoveryMethod: 'clone',
    waitRecovery: 3,
    label: 'secondary-1',
    memberWeight: 25,
    autoRejoinTries: 3
 })

下表に、主要なオプションの説明を示す。

cluster.addInstance() オプション

オプション	説明
recoveryMethod	リカバリ方式 (clone、incremental、auto)
waitRecovery	リカバリ完了を待つタイムアウト 0: 待たない 1〜3: 進捗表示レベル
label	インスタンスのラベル
autoRejoinTries	自動再参加の試行回数

クラスタのステータス確認

クラスタの状態を確認する方法を以下に示す。

 // クラスタオブジェクトを取得
 cluster = dba.getCluster()
 
 // ステータス確認
 cluster.status()
 
 // 詳細なステータス確認
 cluster.status({extended: 1})
 
 // さらに詳細なステータス確認
 cluster.status({extended: 2})

出力例を以下に示す。

 {
    "clusterName": "MyCluster",
    "defaultReplicaSet": {
       "name": "default",
       "primary": "host1:3306",
       "ssl": "REQUIRED",
       "status": "OK",
       "statusText": "Cluster is ONLINE and can tolerate up to ONE failure.",
       "topology": {
          "host1:3306": {
             "address": "host1:3306",
             "mode": "R/W",
             "readReplicas": {},
             "role": "HA",
             "status": "ONLINE"
          },
          "host2:3306": {
             "address": "host2:3306",
             "mode": "R/O",
             "readReplicas": {},
             "role": "HA",
             "status": "ONLINE"
          }
       }
    }
 }

ステータスの意味を以下に示す。

InnoDB Cluster インスタンスのステータス

ステータス	説明
ONLINE	インスタンスは正常に動作中
RECOVERING	インスタンスはリカバリ中
OFFLINE	インスタンスは到達不可
ERROR	インスタンスはエラー状態
MISSING	インスタンスはクラスタから削除済み

フェイルオーバーと高可用性

InnoDB Clusterは、自動フェイルオーバーをサポートする。
プライマリインスタンスが停止すると、自動的に新しいプライマリが選出される。

• 手動でのフェイルオーバー (プライマリ切り替え)

   // 特定のインスタンスをプライマリに設定
   cluster.setPrimaryInstance('user@host2:3306')
  

  
  

• クォーラムが失われた場合の対処方法

   // クォーラムを強制的に回復 (残存インスタンスを使用)
   cluster.forceQuorumUsingPartitionOf('user@host1:3306')
   
   // 失ったメンバーを再参加
   cluster.rejoinInstance('user@host3:3306')
  

InnoDB ReplicaSet

InnoDB ReplicaSetは、非同期レプリケーションベースの高可用性ソリューションである。
GTIDベースのレプリケーションを使用し、手動フェイルオーバーをサポートする。

ReplicaSetの作成と管理

InnoDB ReplicaSetを作成する手順を以下に示す。

 // サーバ設定の確認
 dba.checkInstanceConfiguration('user@host1:3306')
 
 // サーバ設定の調整
 dba.configureReplicaSetInstance('user@host1:3306')
 
 // ReplicaSetの作成
 replicaSet = dba.createReplicaSet('MyReplicaSet')
 
 // インスタンスを追加
 replicaSet.addInstance('user@host2:3306')
 replicaSet.addInstance('user@host3:3306')
 
 // ステータス確認
 replicaSet.status()

ReplicaSetの特徴を以下に示す。

• 非同期レプリケーション (GTIDベース)
• 手動フェイルオーバー
• シングルプライマリモード
• InnoDB Clusterより軽量

プライマリの切り替え

• プライマリインスタンスを手動で切り替える方法

   // ReplicaSetオブジェクトを取得
   replicaSet = dba.getReplicaSet()
   
   // プライマリを切り替え
   replicaSet.setPrimaryInstance('user@host2:3306')
  

  
  

• 強制的なプライマリ切り替え (元プライマリが停止している場合)

   // 強制的にプライマリを切り替え
   replicaSet.forcePrimaryInstance('user@host2:3306')
  

InnoDB ClusterSet

InnoDB ClusterSetは、複数のInnoDB Clusterを統合した災害復旧ソリューションである。
グローバルデプロイメントや災害対策に使用される。

ClusterSetの作成

InnoDB ClusterSetを作成する手順を以下に示す。

 // プライマリクラスタを取得
 cluster = dba.getCluster()
 
 // ClusterSetを作成
 clusterset = cluster.createClusterSet('MyClusterSet')
 
 // セカンダリクラスタを追加
 clusterset.createReplicaCluster('user@replica-host1:3306', 'ReplicaCluster1')
 
 // ClusterSetのステータス確認
 clusterset.status()

災害復旧とフェイルオーバー

ClusterSet全体のフェイルオーバー方法を以下に示す。

 // ClusterSetオブジェクトを取得
 clusterset = dba.getClusterSet()
 
 // セカンダリクラスタをプライマリに昇格
 clusterset.setPrimaryCluster('ReplicaCluster1')
 
 // 強制的なフェイルオーバー (プライマリクラスタが停止している場合)
 clusterset.forcePrimaryCluster('ReplicaCluster1')

ユーティリティ

MySQL Shellは、データベース管理のための豊富なユーティリティ関数を提供する。
util グローバルオブジェクトを通じてアクセスする。

データのエクスポート (util.dumpSchemas / util.dumpInstance)

データベースの論理バックアップを取得する方法を以下に示す。

• スキーマ単位のダンプ

   // 特定のスキーマをダンプ
   util.dumpSchemas(['schema1', 'schema2'], '/path/to/dump')
   
   // 全てのスキーマをダンプ (システムスキーマ除く)
   util.dumpSchemas([], '/path/to/dump', {includeSchemas: []})
   
   // オプション指定
   util.dumpSchemas(['mydb'], '/path/to/dump', {
      threads: 4,
      compression: 'zstd',
      chunking: true,
      bytesPerChunk: '64M',
      showProgress: true
   })
  

  
  

• インスタンス全体のダンプ

   // インスタンス全体をダンプ
   util.dumpInstance('/path/to/dump')
   
   // オプション指定
   util.dumpInstance('/path/to/dump', {
      threads: 8,
      compression: 'zstd',
      excludeSchemas: ['mysql', 'sys', 'performance_schema'],
      ocimds: false,
      showProgress: true
   })
  

下表に、主要なオプションの説明を示す。

util.dumpSchemas() / util.dumpInstance() オプション

オプション	説明
threads	並列スレッド数 (デフォルト: 4)
compression	圧縮方式 (zstd、gzip、none)
chunking	大きなテーブルを分割
bytesPerChunk	チャンクサイズ
ocimds	Oracle Cloud Infrastructure MySQL Database Service向け最適化
excludeSchemas	除外するスキーマ
excludeTables	除外するテーブル

データのインポート (util.loadDump)

ダンプファイルからデータを復元する方法を以下に示す。

 // ダンプをロード
 util.loadDump('/path/to/dump')
 
 // オプション指定
 util.loadDump('/path/to/dump', {
    threads: 8,
    ignoreVersion: true,
    resetProgress: false,
    deferTableIndexes: 'all',
    loadIndexes: true,
    progressFile: '/tmp/progress.json',
    showProgress: true
 })

下表に、主要なオプションの説明を示す。

util.loadDump() オプション

オプション	説明
threads	並列スレッド数 (デフォルト: 4)
ignoreVersion	MySQLバージョンチェックを無視
resetProgress	進捗ファイルをリセット
deferTableIndexes	インデックス作成を遅延 (all、fulltext)
loadIndexes	遅延したインデックスを作成
progressFile	進捗ファイルのパス

部分的なインポートの例を以下に示す。

 // 特定のスキーマのみをロード
 util.loadDump('/path/to/dump', {
    includeSchemas: ['mydb', 'testdb']
 })
 
 // 特定のテーブルのみをロード
 util.loadDump('/path/to/dump', {
    includeTables: ['mydb.users', 'mydb.orders']
 })
 
 // 特定のテーブルを除外
 util.loadDump('/path/to/dump', {
    excludeTables: ['mydb.logs', 'mydb.temp']
 })

アップグレードチェッカー (util.checkForServerUpgrade)

MySQLサーバのアップグレード互換性をチェックする方法を以下に示す。

 // アップグレードチェック
 util.checkForServerUpgrade()
 
 // ターゲットバージョンを指定
 util.checkForServerUpgrade('user@localhost:3306', {targetVersion: '8.0.35'})
 
 // オプション指定
 util.checkForServerUpgrade('user@localhost:3306', {
    targetVersion: '8.0.35',
    outputFormat: 'JSON',
    configPath: '/etc/my.cnf'
 })

チェック項目を以下に示す。

• 非推奨機能の使用状況
• 予約語との衝突
• データ型の互換性
• ストレージエンジンの互換性
• テーブル構造の問題
• 文字セットと照合順序
• パーティショニングの互換性
• 外部キー制約の問題

JSONデータのインポート (util.importJson)

JSONファイルをMySQLにインポートする方法を以下に示す。

 // JSONファイルをコレクションにインポート
 util.importJson('/path/to/file.json', {
    schema: 'mydb',
    collection: 'mycollection'
 })
 
 // JSONファイルをテーブルにインポート
 util.importJson('/path/to/file.json', {
    schema: 'mydb',
    table: 'mytable',
    tableColumn: 'json_data'
 })

テーブルのインポート (util.importTable)

CSVファイルやTSVファイルをテーブルにインポートする方法を以下に示す。

 // CSVファイルをインポート
 util.importTable('/path/to/file.csv', {
    schema: 'mydb',
    table: 'mytable',
    columns: ['id', 'name', 'email'],
    fieldsTerminatedBy: ',',
    fieldsEnclosedBy: '"',
    fieldsEscapedBy: '\\',
    linesTerminatedBy: '\n'
 })
 
 // TSVファイルをインポート
 util.importTable('/path/to/file.tsv', {
    schema: 'mydb',
    table: 'mytable',
    fieldsTerminatedBy: '\t'
 })

下表に、主要なオプションの説明を示す。

util.importTable() オプション

オプション	説明
columns	カラム名のリスト
fieldsTerminatedBy	フィールド区切り文字
fieldsEnclosedBy	フィールド囲み文字
fieldsEscapedBy	エスケープ文字
linesTerminatedBy	行区切り文字
skipRows	スキップする行数
replaceDuplicates	重複行を置換

X DevAPI

X DevAPIは、MySQLのドキュメントストア機能を提供するAPIである。
NoSQL風のCRUD操作をサポートする。

X DevAPIとは

X DevAPIの主要な特徴を以下に示す。

• JSON / ドキュメント指向データベースとしてのMySQL
• NoSQL風のCRUD操作 (Create、Read、Update、Delete)
• スキーマレスなデータモデル
• リレーショナルテーブルとドキュメントコレクションの統合利用
• SQL操作も可能

下表に、X DevAPIの主要オブジェクトを示す。

X DevAPI の主要オブジェクト

オブジェクト	説明
mysqlx	X DevAPIのエントリポイント
Session	X Protocolセッション
Schema	データベーススキーマ
Collection	ドキュメントコレクション
Table	リレーショナルテーブル

コレクション操作

ドキュメントコレクションの作成と管理方法を以下に示す。

 // スキーマを取得
 db = session.getSchema('mydb')
 
 // コレクションを作成
 db.createCollection('mycollection')
 
 // コレクションを取得
 collection = db.getCollection('mycollection')
 
 // コレクションの削除
 db.dropCollection('mycollection')
 
 // コレクション一覧を取得
 db.getCollections()

CRUD操作

ドキュメントのCRUD操作方法を以下に示す。

• ドキュメントの作成 (Create)

   // ドキュメントを追加
   collection.add({
      id: 1,
      name: 'Alice',
      email: 'alice@example.com',
      age: 30
   }).execute()
   
   // 複数のドキュメントを追加
   collection.add([
      {id: 2, name: 'Bob', email: 'bob@example.com', age: 25},
      {id: 3, name: 'Charlie', email: 'charlie@example.com', age: 35}
   ]).execute()
  

  
  

• ドキュメントの読み取り (Read)

   // 全てのドキュメントを取得
   collection.find().execute()
   
   // 条件指定で検索
   collection.find('id = 1').execute()
   
   // バインド変数を使用
   collection.find('name = :name').bind('name', 'Alice').execute()
   
   // 複雑な条件
   collection.find('age > :minAge AND age < :maxAge')
             .bind('minAge', 20)
             .bind('maxAge', 40)
             .execute()
   
   // 射影 (特定フィールドのみ取得)
   collection.find().fields('name', 'email').execute()
   
   // ソート
   collection.find().sort('age DESC').execute()
   
   // 制限
   collection.find().limit(10).execute()
   
   // オフセット指定
   collection.find().limit(10).offset(20).execute()
  

  
  

• ドキュメントの更新 (Update)

   // ドキュメントを更新
   collection.modify('id = 1')
             .set('email', 'alice.new@example.com')
             .execute()
   
   // 複数フィールドを更新
   collection.modify('id = 2')
             .set('email', 'bob.new@example.com')
             .set('age', 26)
             .execute()
   
   // フィールドを削除
   collection.modify('id = 3')
             .unset('age')
             .execute()
   
   // 配列に要素を追加
   collection.modify('id = 1')
             .arrayAppend('hobbies', 'reading')
             .execute()
  

  
  

• ドキュメントの削除 (Delete)

   // ドキュメントを削除
   collection.remove('id = 3').execute()
   
   // 条件に一致する全てを削除
   collection.remove('age > 60').execute()
   
   // 全てのドキュメントを削除
   collection.remove('true').execute()
  

  
  

• テーブル操作 (リレーショナル)

   // テーブルを取得
   table = db.getTable('users')
   
   // SELECT
   table.select(['id', 'name', 'email']).execute()
   
   // WHERE
   table.select().where('age > :age').bind('age', 30).execute()
   
   // INSERT
   table.insert(['id', 'name', 'email']).values(4, 'David', 'david@example.com').execute()
   
   // UPDATE
   table.update().set('email', 'eve.new@example.com').where('id = 5').execute()
   
   // DELETE
   table.delete().where('id = 6').execute()
  

プラグイン

MySQL Shellは、プラグインシステムにより機能を拡張できる。
カスタムレポート、独自のコマンド、拡張オブジェクトの追加が可能である。

プラグインの作成とインストール

プラグインの基本構造を以下に示す。

plugin_directory/
├── init.js (または init.py)
└── report.js (またはその他の拡張ファイル)

プラグインのインストール場所を以下に示す。

• Linux / MacOS

  ~/.mysqlsh/plugins/

• Windows

  %APPDATA%\MySQL\mysqlsh\plugins\

• プラグインの例

   // ~/.mysqlsh/plugins/my_plugin/init.js
   
   var myPlugin = shell.createExtensionObject()
   
   myPlugin.hello = function(name) {
      println("Hello, " + name + "!")
   }
   
   shell.registerGlobal("myPlugin", myPlugin, {
      brief: "My custom plugin",
      details: ["This is a simple example plugin."]
   })
  

  
  

• プラグインの使用方法

   // プラグインを使用
   myPlugin.hello("World")
   
   // 出力: Hello, World!
  

  
  

• カスタムレポートの作成例

   // レポート関数を定義
   function connectionReport(session) {
      var result = session.runSql("SHOW PROCESSLIST")
      var rows = result.fetchAll()
      return {
         report: rows
      }
   }
   
   // レポートを登録
   shell.registerReport("connections", "list", connectionReport, {
      brief: "Shows current connections",
      details: ["Lists all active MySQL connections."]
   })
  

  
  

• レポートの実行方法

   # レポート一覧を表示
   \show
   
   # カスタムレポートを実行
   \show connections
  

設定とカスタマイズ

設定ファイル

MySQL Shellの設定ファイルの場所を以下に示す。

• Linux/MacOS

  ~/.mysqlsh/mysqlsh.json

• Windows

  %APPDATA%\MySQL\mysqlsh\mysqlsh.json

設定ファイルの例を以下に示す。

 {
    "defaultMode": "js",
    "history.autoSave": true,
    "history.maxSize": 1000,
    "resultFormat": "table",
    "showWarnings": true,
    "logLevel": "info",
    "logSql": false,
    "autocomplete.nameCache": true,
    "devapi.dbObjectHandles": true
 }

永続設定

設定を永続化する方法を以下に示す。

 // オプションを永続化
 shell.options.setPersist('resultFormat', 'json')
 
 // オプションを一時的に設定 (セッションのみ)
 shell.options.set('resultFormat', 'table')
 
 // オプションを取得
 shell.options.get('resultFormat')
 
 // 全てのオプションを表示
 shell.options

コマンドラインでのオプション指定を以下に示す。

 # オプションを指定して起動
 mysqlsh --result-format=json
 
 # 永続的にオプションを設定
 \option resultFormat=json --persist

主要なオプションを以下に示す。

主要な設定オプション

オプション	説明
defaultMode	デフォルトモード (js、py、sql)
resultFormat	結果セットのフォーマット (table、json、json/pretty、tabbed、vertical)
history.autoSave	履歴の自動保存
history.maxSize	履歴の最大サイズ
showWarnings	警告の表示
logLevel	ログレベル (none、internal_error、error、warning、info、debug、debug2、debug3)
logSql	SQL文のログ記録

プロンプトのカスタマイズ

プロンプトの外観をカスタマイズする方法を以下に示す。

設定ファイル (~/.mysqlsh/prompt.json) の例を以下に示す。

 {
    "prompt": "\\u@\\h [\\d]> ",
    "segments": [
       {
          "text": "\\u",
          "fg": "green"
       },
       {
          "text": "@\\h",
          "fg": "cyan"
       },
       {
          "text": " [\\d]> ",
          "fg": "white"
       }
    ]
 }

使用可能なトークンを以下に示す。

プロンプトトークン

トークン	説明
\u	ユーザ名
\h	ホスト名
\d	スキーマ名
\P	ポート番号
\m	モード (JS、Py、SQL)

環境変数でプロンプトテーマを設定する方法を以下に示す。

 # ダークテーマ
 export MYSQLSH_PROMPT_THEME=dark
 
 # ライトテーマ
 export MYSQLSH_PROMPT_THEME=light

ロギング設定

ログレベルの設定方法を以下に示す。

# コマンドライン引数
mysqlsh --log-level=debug

# デバッグログを有効化
mysqlsh --log-level=debug --log-sql

ログファイルの場所を以下に示す。

• Linux/MacOS

  ~/.mysqlsh/mysqlsh.log

• Windows

  %APPDATA%\MySQL\mysqlsh\mysqlsh.log

MySQL Shell for VS Code

MySQL Shell for VS Codeは、Visual Studio Code向けの統合拡張機能である。
GUI環境でのMySQL管理とMySQL Shellの機能を提供する。

拡張機能のインストール

• VS Code Marketplaceからインストールする方法

   # コマンドライン
   code --install-extension Oracle.mysql-shell-for-vs-code
  

  
  

• VS Code内でのインストール手順
  1. 拡張機能ビュー ([Ctrl] + [Shift] + [X]キー) を開く。
  2. "MySQL Shell for VS Code" を検索する。
  3. [インストール]ボタンを押下する。

主な機能

MySQL Shell for VS Codeの主要な機能を以下に示す。

MySQL Shell の主な機能

機能	説明
接続管理	複数の接続プロファイルを保存・管理 X ProtocolとClassic Protocolの両方をサポート SSL/TLS接続設定
SQLエディタ	構文ハイライト シンタックス補完 (スキーマ、テーブル、カラム名) クエリ実行と結果表示 実行計画 (EXPLAIN) の可視化
スキーマブラウザ	テーブル・ビュー・ストアドプロシージャの階層表示 テーブル定義の確認 データのブラウズと編集
ノートブック機能	JavaScript/Pythonモードの統合 セル単位でのコード実行 実行結果のインライン表示
AdminAPI GUIダッシュボード	InnoDB Clusterの可視化 クラスタステータスのリアルタイム監視 グラフィカルな管理操作

セキュリティ

SSL/TLS接続

SSL/TLS接続を使用する方法を以下に示す。

 # SSL/TLS接続を強制
 mysqlsh --ssl-mode=REQUIRED --ssl-ca=/path/to/ca.pem --ssl-cert=/path/to/client-cert.pem --ssl-key=/path/to/client-key.pem -u user -h localhost
 
 # URI形式
 mysqlsh mysqlx://user@localhost:33060?ssl-mode=REQUIRED&ssl-ca=/path/to/ca.pem

下表に、SSL/TLSモードの説明を示す。

SSL/TLSモード

モード	説明
DISABLED	SSL/TLS接続を無効化
PREFERRED	可能であればSSL/TLS接続を使用 (デフォルト)
REQUIRED	SSL/TLS接続を強制 (証明書検証なし)
VERIFY_CA	SSL/TLS接続を強制 + CA証明書検証
VERIFY_IDENTITY	SSL/TLS接続を強制 + CA証明書検証 + ホスト名検証

認証方式

MySQLの認証方式を以下に示す。

MySQL 認証方式

プラグイン	説明
caching_sha2_password	MySQL 8.0デフォルト SHA-256ベースの認証 サーバ側でキャッシュ
mysql_native_password	レガシー認証方式 MySQL 5.7以前のデフォルト
sha256_password	SHA-256ベースの認証 キャッシュなし
authentication_pam	PAM認証 LDAP、Kerberos等と統合可能

認証方式を指定する方法を以下に示す。

# 認証方式を指定
mysqlsh --auth-method=caching_sha2_password -u user -h localhost

# サーバ公開鍵を取得 (caching_sha2_password使用時)
mysqlsh --get-server-public-key -u user -h localhost

パスワードの安全な管理方法を以下に示す。

# パスワードを対話式で入力 (推奨)
mysqlsh -u user -h localhost -p

# パスワードをURIに含めない (推奨)
mysqlsh mysqlx://user@localhost:33060

# パスワードストアの使用
mysqlsh --save-passwords=always

トラブルシューティング

接続エラー

接続エラーの診断と対処方法を以下に示す。

• ERROR 2003: Can't connect to MySQL server

  MySQLサーバが起動しているかを確認する

  ファイアウォール設定を確認する

  ポート番号が正しいかを確認する (X Protocol: 33060、Classic: 3306)

  ホスト名・IPアドレスが正しいかを確認する

• ERROR 2002: Can't connect through socket

  Unixソケットファイルのパスが正しいかを確認する

  MySQLサーバが起動しているかを確認する

  --socket オプションで明示的にソケットパスを指定する

• ERROR 1045: Access denied

  ユーザ名とパスワードが正しいかを確認する

  ユーザが存在するかを確認する (SELECT user, host FROM mysql.user;)

  ホストベースのアクセス制御を確認する

診断コマンドの例を以下に示す。

# MySQLサーバの状態確認
systemctl status mysqld

# ポートの確認
netstat -an | grep 3306
netstat -an | grep 33060

# ファイアウォール設定の確認 (Linux)
sudo firewall-cmd --list-all

# MySQLサーバログの確認
tail -100 /var/log/mysql/error.log

クラスタの問題

InnoDB Clusterの一般的な問題と対処方法を以下に示す。

• クォーラム喪失

  問題: 過半数のメンバーが停止し、クラスタが動作不可

  対処: cluster.forceQuorumUsingPartitionOf('instance') でクォーラムを強制回復

  
  

• 通信エラー

  問題: メンバー間の通信が失敗

  対処: ネットワーク設定とファイアウォールを確認 (ポート33061の通信許可)

  
  

• リカバリー状態

  問題: インスタンスがRECOVERING状態で停止

  対処: cluster.rescan() でクラスタ状態を再スキャン

クラスタのトラブルシューティングコマンドを以下に示す。

 // クラスタの状態を確認
 cluster = dba.getCluster()
 cluster.status({extended: 2})
 
 // クォーラムを強制回復
 cluster.forceQuorumUsingPartitionOf('user@host1:3306')
 
 // メンバーを再参加
 cluster.rejoinInstance('user@host2:3306')
 
 // クラスタ設定を再スキャン
 cluster.rescan()
 
 // 問題のあるインスタンスを削除
 cluster.removeInstance('user@host3:3306', {force: true})

よくある問題

その他のよくある問題と解決策を以下に示す。

• バージョン互換性エラー

  問題: MySQLサーバとMySQL Shellのバージョン不一致

  対処: util.checkForServerUpgrade() で互換性を確認

  対処: MySQL ShellまたはMySQLサーバをアップグレード

  
  

• メモリ不足

  問題: ダンプ/ロード時にメモリ不足エラー

  対処: threads オプションを減らす (例: threads: 1)

  対処: bytesPerChunk を小さくする

  
  

• 接続タイムアウト

  問題: 長時間のクエリ実行時に接続が切断される

  対処: --connect-timeout オプションを増やす (例: --connect-timeout=60)

  対処: MySQLサーバの wait_timeout 設定を確認

デバッグログの有効化方法を以下に示す。

 # デバッグログを有効化
 mysqlsh --log-level=debug --log-sql
 
 # ログファイルの確認
 tail -f ~/.mysqlsh/mysqlsh.log