Quantum Ink

Writing about the future as it unfolds.

Common MySQL Shell Admin API Commands for Engineers

Common MySQL Shell AdminAPI Commands Every Engineer Should Know

MySQL Shell’s AdminAPI is the supported way to manage MySQL InnoDB Cluster and InnoDB ClusterSet. Even if you are not a full-time DBA, knowing a small set of commands will help you diagnose issues, check replication health and perform basic operations safely.

This article focuses on practical AdminAPI commands that general engineers can use confidently. Examples assume:

  • MySQL Shell (mysqlsh) is installed on RHEL/Rocky Linux.
  • Instances are running MySQL with InnoDB and GTID-based replication.
  • You connect using the X DevAPI port (default 33060) when managing clusters.

1. Getting started with MySQL Shell

1.1 Launching MySQL Shell

On RHEL/Rocky Linux:

mysqlsh --uri root@db1:3306

Switch to JavaScript mode (AdminAPI is documented primarily in JS):

\js

Or Python mode if you prefer:

\py

Check AdminAPI availability:

\js
shell.help("dba")

1.2 Basic connection objects

Many AdminAPI commands take a connection string:

var conn = "root@db1:3306";

For production, use a dedicated admin user instead of root, with least-privilege grants for cluster administration.

2. Preparing instances: dba.checkInstanceConfiguration()

Before adding a server to a cluster, verify it is correctly configured. This avoids subtle replication and GTID issues later.

Run:

dba.checkInstanceConfiguration("admin@db1:3306")

Typical checks include:

  • GTID mode and consistency.
  • Binary logging enabled.
  • Required InnoDB settings (e.g. innodb_file_per_table).
  • Super read-only behaviour.

If problems are found, you’ll see “ERROR” or “WARNING” entries with suggested fixes. You can let AdminAPI attempt automatic fixes (on a non-production first):

dba.configureInstance("admin@db1:3306")

Best practice: On RHEL/Rocky Linux, always review generated configuration changes. They typically go into /etc/my.cnf or a file under /etc/my.cnf.d/. Use version control for MySQL configuration.

3. Creating a cluster: dba.createCluster()

3.1 Initial cluster creation

Once your first instance is configured, create a cluster:

var cluster = dba.createCluster("prodCluster", {
  "memberSslMode": "REQUIRED",
  "ipWhitelist": "10.0.0.0/24"
});

This command:

  • Initialises InnoDB Cluster metadata on the current instance.
  • Configures Group Replication (single primary by default).
  • Applies security and network settings from the options.

Basic ASCII view of a 3-node cluster:

┌───────────────┐
│  prodCluster  │
├───────────────┤
│ PRIMARY   db1 │
│ SECONDARY db2 │
│ SECONDARY db3 │
└───────────────┘

Best practice: Run dba.createCluster() on the instance you want as the initial primary. Ensure it has the most up-to-date data, typically your existing master.

3.2 Getting an existing cluster handle

On any cluster member, reconnect and run:

var cluster = dba.getCluster("prodCluster");

If you omit the name:

var cluster = dba.getCluster();

MySQL Shell will infer the cluster from the current instance’s metadata.

4. Adding and removing instances

4.1 dba.createClusterSet() (multi-site, optional)

For most engineers, a single InnoDB Cluster is enough. ClusterSet adds DR across sites. The command is:

var c = dba.getCluster("prodCluster");
var cs = dba.createClusterSet(c, {"name": "prodClusterSet"});

Only use this if you understand cross-site replication latency and failover implications. Start with a single cluster first.

4.2 Adding replicas: cluster.addInstance()

To add a new instance to an existing cluster:

var cluster = dba.getCluster("prodCluster");
cluster.addInstance("admin@db2:3306", {
  "recoveryMethod": "clone"
});

Key points:

  • recoveryMethod: "clone" uses MySQL Clone plugin to seed data.
  • Ensure the target instance has no important data; it will be overwritten.
  • The command configures Group Replication channels and joins the node.

Warning: Adding an instance with recoveryMethod: "clone" is destructive for the target server’s data. Never run this against a server containing data you wish to keep.

4.3 Removing instances: cluster.removeInstance()

To remove a member cleanly:

var cluster = dba.getCluster("prodCluster");
cluster.removeInstance("admin@db3:3306");

This:

  • Removes the instance from Group Replication.
  • Updates the cluster metadata.
  • Leaves MySQL running as a standalone server.

Best practice: Always use removeInstance() rather than manually stopping Group Replication. It keeps metadata and topology consistent.

5. Monitoring health: cluster.status()

5.1 Quick health overview

The most useful AdminAPI command in daily operations is:

var cluster = dba.getCluster("prodCluster");
cluster.status();

This prints a JSON-like structure showing:

  • Cluster name and mode (singlePrimary/multiPrimary).
  • Primary instance and its role.
  • Each member’s status (ONLINE, OFFLINE, RECOVERING, ERROR).
  • Replication state and error messages.

Example (simplified):

{
  "clusterName": "prodCluster",
  "defaultReplicaSet": {
    "status": "OK",
    "topology": {
      "db1:3306": { "role": "PRIMARY", "status": "ONLINE" },
      "db2:3306": { "role": "SECONDARY", "status": "ONLINE" }
    }
  }
}

Best practice: Integrate cluster.status() into operational runbooks. When you get an alert from monitoring, run this first to see if the issue is local or cluster-wide.

5.2 Compact status for scripts

For automation, use:

cluster.status({"extended": 0});

This returns a more compact format that is easier to parse programmatically.

6. Handling failover and primary changes

6.1 Planned primary switchover: cluster.setPrimaryInstance()

For maintenance on the current primary, perform a controlled switchover:

var cluster = dba.getCluster("prodCluster");
cluster.setPrimaryInstance("admin@db2:3306");

This:

  • Promotes db2 to primary.
  • Demotes the old primary to secondary.
  • Keeps client writes available with minimal disruption (assuming routers are used).

Best practice:

  • Check cluster.status() before and after switchover.
  • Ensure application traffic uses MySQL Router or another abstraction, not hardcoded hostnames for the primary.

6.2 Recovering from failures: dba.rebootClusterFromCompleteOutage()

In a full outage where all members went down, you may need to “reboot” the cluster from the most advanced instance.

Warning: This is a potentially disruptive operation. It can discard transactions from less advanced members. Always verify GTID sets and data consistency.

On the instance you choose as the new reference:

var cluster = dba.rebootClusterFromCompleteOutage("prodCluster");

AdminAPI will:

  • Inspect available instances and their GTID sets.
  • Rebuild cluster metadata based on the chosen member.
  • Attempt to rejoin other instances if compatible.

Use this only when the cluster cannot be recovered with normal start-up and cluster.status() shows inconsistent metadata.

7. Backups and consistency checks around AdminAPI

AdminAPI does not replace backup tooling, but some commands help you maintain a safe environment for backups and consistency.

7.1 Checking for unmanaged replication: dba.checkInstanceConfiguration()

Before configuring backup replicas outside the cluster, re-run:

dba.checkInstanceConfiguration("backup@backup-db:3306");

Ensure backup servers do not accidentally join Group Replication when you only want asynchronous replication.

7.2 Read-only mode during logical backups

For logical backups (e.g. mysqldump) on the primary, you may want a short read-only window. Use SQL, not AdminAPI, but coordinate with cluster status:

cluster.status();

// On primary only
SQL> SET GLOBAL super_read_only = ON;
-- run backup
SQL> SET GLOBAL super_read_only = OFF;

Best practice: Prefer taking backups from a secondary or a dedicated asynchronous replica to avoid impacting the primary.

8. Useful diagnostic helpers

8.1 dba.checkInstanceState()

When an instance behaves oddly, but is still reachable:

dba.checkInstanceState("admin@db2:3306");

This reports whether the instance:

  • Belongs to a known cluster.
  • Is correctly configured for Group Replication.
  • Has local issues (e.g. plugin not loaded).

8.2 cluster.rescan()

If someone manually changed Group Replication configuration, the cluster metadata can get out of sync. Use:

var cluster = dba.getCluster("prodCluster");
cluster.rescan();

This inspects Group Replication membership and updates metadata accordingly. Use it after manual interventions, but try to avoid such interventions in the first place.

9. Operational best practices

  • Always use AdminAPI for cluster changes (add/remove nodes, switch primary) instead of raw SQL on Group Replication.
  • Separate admin accounts: create dedicated users for AdminAPI with strong passwords and no application privileges.
  • Automate common checks: script cluster.status() and dba.checkInstanceConfiguration() in CI/CD or operational health checks.
  • Document runbooks: for failover, maintenance and outage recovery, include exact AdminAPI commands and expected outputs.
  • Test upgrades in staging: when upgrading MySQL or MySQL Shell, validate AdminAPI behaviour against a staging cluster first.

This article offers general technical guidance. Validate all configurations in a safe environment before applying them to production.

Smart reads for curious minds

We don’t spam! Read more in our privacy policy