MySQL Shell 9.2

Abstract

MySQL Shell is an advanced client and code editor for MySQL. This document describes the core features of MySQL Shell. In addition to the provided SQL functionality, similar to mysql, MySQL Shell provides scripting capabilities for JavaScript and Python and includes APIs for working with MySQL. X DevAPI enables you to work with both relational and document data, see Using MySQL as a Document Store. AdminAPI enables you to work with InnoDB Cluster, InnoDB ClusterSet, and InnoDB ReplicaSet.

MySQL Shell 9.2.0 is highly recommended for use with any GA version of MySQL 8.4, or higher. Please upgrade to MySQL Shell 9.2.0. If you have not yet installed MySQL Shell, download it from the download site.

For notes detailing the changes in each release, see the MySQL Shell Release Notes.

For help with using MySQL, please visit the MySQL Forums, where you can discuss your issues with other MySQL users.

Licensing information.  This product may include third-party software, used under license. If you are using a Commercial release of MySQL Shell, see MySQL Shell Commercial License Information User Manual for licensing information, including licensing information relating to third-party software that may be included in this Commercial release. If you are using a Community release of MySQL Shell, see MySQL Shell Community License Information User Manual for licensing information, including licensing information relating to third-party software that may be included in this Community release.

Document generated on: 2025-02-26 (revision: 81046)

Table of Contents

1 MySQL Shell Features
2 Installing MySQL Shell
2.1 Installing MySQL Shell on Microsoft Windows
2.2 Installing MySQL Shell on Linux
2.3 Installing MySQL Shell on macOS
3 Using MySQL Shell Commands
3.1 MySQL Shell Commands
4 Getting Started with MySQL Shell
4.1 Starting MySQL Shell
4.2 MySQL Shell Sessions
4.2.1 Creating the Session Global Object While Starting MySQL Shell
4.2.2 Creating the Session Global Object After Starting MySQL Shell
4.2.3 Scripting Sessions in JavaScript and Python Mode
4.3 MySQL Shell Connections
4.3.1 Connecting using Individual Parameters
4.3.2 Connecting using login-path and Options Files
4.3.3 Connecting using Unix Sockets and Windows Named Pipes
4.3.4 Using Encrypted Connections
4.3.5 Using LDAP and Kerberos Authentication
4.3.6 Using OpenID Connect
4.3.7 Using an SSH Tunnel
4.3.8 Using Compressed Connections
4.4 Pluggable Password Store
4.4.1 Pluggable Password Configuration Options
4.4.2 Working with Credentials
4.5 MySQL Shell Global Objects
4.6 Using a Pager
4.7 Cloud Service Configuration
4.7.1 Oracle Cloud Infrastructure Object Storage
4.7.2 S3-compatible Storage
4.7.3 Azure Blob Storage
4.8 OCI Authentication Connection Options
5 MySQL Shell Code Execution
5.1 Active Language
5.2 Interactive Code Execution
5.3 Code Autocompletion
5.4 Editing Code
5.5 Code History
5.6 Batch Code Execution
5.7 Output Formats
5.7.1 Table Format
5.7.2 Tab Separated Format
5.7.3 Vertical Format
5.7.4 JSON Format Output
5.7.5 JSON Wrapping
5.7.6 Result Metadata
5.8 API Command Line Integration
5.8.1 Command Line Integration Overview
5.8.2 Command Line Integration Details
5.9 JSON Integration
5.10 Limitations
6 MySQL AdminAPI
6.1 Using MySQL AdminAPI
6.2 Installing AdminAPI Software Components
6.2.1 Configuring the Host Name
6.2.2 Connecting to Server Instances
6.2.3 Persisting Settings
6.3 Retrieving a Handler Object
6.4 Creating User Accounts for AdminAPI
6.5 Verbose Logging
6.6 Finding the Primary
6.7 Scripting AdminAPI
6.8 AdminAPI MySQL Sandboxes
6.8.1 Deploying Sandbox Instances
6.8.2 Managing Sandbox Instances
6.8.3 Setting up InnoDB Cluster and MySQL Router
6.9 Tagging Metadata
6.10 Upgrade Metadata Schema
6.11 Locking Mechanism for AdminAPI Operations
6.12 Executing SQL on Topologies
6.13 Replication Compatibility Checks
7 MySQL Router and AdminAPI
7.1 Bootstrapping MySQL Router
7.2 Configuring the MySQL Router User
7.3 Deploying MySQL Router
7.4 Routing Options
7.5 Using ReplicaSets with MySQL Router
7.6 Testing InnoDB Cluster High Availability
7.7 Working with a Cluster's Routers
7.8 Routing Guidelines
7.8.1 Routing Guidelines JSON Syntax
7.8.2 Create and Activate Routing Guidelines
7.8.3 Importing and Exporting Routing Guidelines
7.8.4 Edit Routing Guidelines
7.8.5 Visualize Routing Guidelines
7.8.6 Routing Guidelines Examples
8 MySQL InnoDB Cluster
8.1 InnoDB Cluster Requirements
8.2 InnoDB Cluster Limitations
8.3 User Accounts for InnoDB Cluster
8.4 Deploying a Production InnoDB Cluster
8.4.1 Pre-Checking Instance Configuration for InnoDB Cluster Usage
8.4.2 Configuring Production Instances for InnoDB Cluster Usage
8.4.3 Creating an InnoDB Cluster
8.4.4 Adding Instances to an InnoDB Cluster
8.4.5 Configuring InnoDB Cluster Ports
8.4.6 Using MySQL Clone with InnoDB Cluster
8.4.7 Adopting a Group Replication Deployment
8.5 Configuring InnoDB Cluster
8.5.1 Setting Options for InnoDB Cluster
8.5.2 Customizing InnoDB Cluster Member Servers
8.5.3 Configuring the Election Process
8.5.4 Configuring Failover Consistency
8.5.5 Configuring Automatic Rejoin of Instances
8.5.6 Configuring the Parallel Replication Applier
8.5.7 InnoDB Cluster and Auto-increment
8.5.8 InnoDB Cluster and Binary Log Purging
8.5.9 Configuring the Group Replication Communication Stack
8.6 Securing InnoDB Cluster
8.7 Monitoring InnoDB Cluster
8.8 Restoring and Rebooting an InnoDB Cluster
8.8.1 Rejoining an Instance to a Cluster
8.8.2 Restoring a Cluster from Quorum Loss
8.8.3 Rebooting a Cluster from a Major Outage
8.8.4 Rescanning a Cluster
8.8.5 Fencing a Cluster
8.9 Modifying or Dissolving an InnoDB Cluster
8.10 Upgrade InnoDB Cluster
8.10.1 InnoDB Cluster Upgrade
8.10.2 Troubleshooting InnoDB Cluster Upgrades
8.11 MySQL InnoDB Cluster Read Replicas
8.11.1 Prerequisites
8.11.2 Creating Read Replicas
8.11.3 Modifying or Removing Read Replicas
8.11.4 Monitoring Read Replicas
9 MySQL InnoDB ClusterSet
9.1 InnoDB ClusterSet Requirements
9.2 InnoDB ClusterSet Limitations
9.3 User Accounts for InnoDB ClusterSet
9.4 Deploying InnoDB ClusterSet
9.5 Asynchronous Replication Channel Options
9.6 Integrating MySQL Router With InnoDB ClusterSet
9.7 InnoDB ClusterSet Status and Topology
9.8 InnoDB ClusterSet Controlled Switchover
9.9 InnoDB ClusterSet Emergency Failover
9.10 InnoDB ClusterSet Repair and Rejoin
9.10.1 Fencing Clusters in an InnoDB ClusterSet
9.10.2 Inconsistent Transaction Sets (GTID Sets) in InnoDB ClusterSet Clusters
9.10.3 Repairing Member Servers and Clusters in an InnoDB ClusterSet
9.10.4 Removing a Cluster from an InnoDB ClusterSet
9.10.5 Rejoining a Cluster to an InnoDB ClusterSet
9.11 Dissolving a ClusterSet
9.12 Upgrade InnoDB ClusterSet
10 MySQL InnoDB ReplicaSet
10.1 Deploying InnoDB ReplicaSet
10.2 Configuring InnoDB ReplicaSet Instances
10.3 Creating an InnoDB ReplicaSet
10.4 Asynchronous Replication Channel Options
10.5 Adding Instances to a ReplicaSet
10.5.1 Provisioning Instances for InnoDB ReplicaSet
10.5.2 Example of Adding Instances to a ReplicaSet
10.6 Adopting an Existing Replication Setup
10.7 Changing the Primary Instance
10.8 Forcing a New Primary Instance
10.9 Tagging ReplicaSets
10.10 Checking the Status of InnoDB ReplicaSet
10.11 Upgrade InnoDB ReplicaSet
10.12 Dissolving a ReplicaSet
10.13 Rescanning a ReplicaSet
10.14 Describing a ReplicaSet
11 Extending MySQL Shell
11.1 Reporting with MySQL Shell
11.1.1 Creating MySQL Shell Reports
11.1.2 Registering MySQL Shell Reports
11.1.3 Persisting MySQL Shell Reports
11.1.4 Example MySQL Shell Report
11.1.5 Running MySQL Shell Reports
11.1.6 Built-in MySQL Shell Reports
11.2 Adding Extension Objects to MySQL Shell
11.2.1 Creating User-Defined MySQL Shell Global Objects
11.2.2 Creating Extension Objects
11.2.3 Persisting Extension Objects
11.2.4 Example MySQL Shell Extension Objects
11.3 MySQL Shell Plugins
11.3.1 Creating MySQL Shell Plugins
11.3.2 Creating Plugin Groups
11.3.3 Example MySQL Shell Plugins
11.4 Custom SQL Handler
11.4.1 Registering SQL Handler
11.4.2 Returning a Custom Result
11.4.3 Result Data Specification
12 MySQL Shell Utilities
12.1 Upgrade Checker Utility
12.2 JSON Import Utility
12.2.1 Running the Utility
12.2.2 Importing JSON Documents With the Mysqlsh Command Interface
12.2.3 Importing JSON Documents With the --import Command
12.2.4 Conversions for Representations of BSON Data Types
12.3 Table Export Utility
12.4 Parallel Table Import Utility
12.5 Instance Dump Utility, Schema Dump Utility, and Table Dump Utility
12.6 Dump Loading Utility
12.7 Binary Log Dumping and Loading Utilities
12.7.1 Dumping Binary Logs
12.7.2 Loading Binary Log Dumps
12.8 Copy Instance, Schemas, and Tables
12.9 Diagnostics Utilities
12.9.1 collectDiagnostics Utility
12.9.2 collectHighLoadDiagnostics Utility
12.9.3 collectSlowQueryDiagnostics Utility
13 MySQL Shell Logging and Debug
13.1 Application Log
13.2 Verbose Output
13.3 System Logging for User SQL Statements
13.4 MySQL Shell SQL Logging
14 Customizing MySQL Shell
14.1 Working With Startup Scripts
14.2 Adding Module Search Paths
14.2.1 Module Search Path Environment Variables
14.2.2 Module Search Path Variable in Startup Scripts
14.3 Customizing the Prompt
14.4 Configuring MySQL Shell Options
A MySQL Shell Command Reference
A.1 mysqlsh — The MySQL Shell