fix: reject incompatible mysqlsh before InnoDB Cluster deploy

MySQL Shell's AdminAPI refuses to manage a server whose major.minor
is greater than the shell's own (e.g. mysqlsh 8.0.x + MySQL Server
8.4.x yields "Unsupported server version: AdminAPI operations in
this version of MySQL Shell support MySQL Server up to version
8.0"). dbdeployer's findMysqlShell prefers <basedir>/bin/mysqlsh
and falls back to $PATH; when the PATH mysqlsh is too old, the
failure only surfaces deep inside init_cluster after sandboxes are
already running.

Parse `mysqlsh --version` up front, compare major.minor to the
target server, and bail out early with a message pointing the user
at https://dev.mysql.com/downloads/shell/. Unparseable --version
output is logged and does not block deploy.

Fixes #87.

Author: renecannao

CHANGELOG.md

@@ -1,5 +1,14 @@
 ## Unreleased
 
+## BUGS FIXED
+
+* Fail early when `mysqlsh` on PATH is too old for the target server
+  version (e.g. mysqlsh 8.0.x + MySQL Server 8.4+), instead of letting
+  the AdminAPI fail mid-deploy with "Unsupported server version"
+  (issue #87). dbdeployer now parses `mysqlsh --version`, compares its
+  major.minor to the server's, and emits an actionable error telling
+  the user to install a matching mysqlsh.
+
 ## DOCUMENTATION
 
 * Recommend `sudo cp` instead of `sudo mv` in manual install steps, so

sandbox/innodb_cluster.go

@@ -52,6 +52,56 @@ func findMysqlShell(basedir string) (string, error) {
 		"Install it from https://dev.mysql.com/downloads/shell/", basedir)
 }
 
+// mysqlShellVersionRegexp matches the "Ver X.Y.Z" token emitted by
+// `mysqlsh --version` (e.g. "mysqlsh   Ver 8.0.36 for Linux on x86_64 ...").
+var mysqlShellVersionRegexp = regexp.MustCompile(`Ver\s+(\d+\.\d+\.\d+)`)
+
+// getMysqlShellVersion runs `mysqlsh --version` and returns the parsed
+// X.Y.Z version string.
+func getMysqlShellVersion(mysqlshPath string) (string, error) {
+	out, err := common.RunCmdCtrlWithArgs(mysqlshPath, []string{"--version"}, true)
+	if err != nil {
+		return "", fmt.Errorf("running '%s --version': %s", mysqlshPath, err)
+	}
+	m := mysqlShellVersionRegexp.FindStringSubmatch(out)
+	if len(m) < 2 {
+		return "", fmt.Errorf("could not parse mysqlsh version from: %s", out)
+	}
+	return m[1], nil
+}
+
+// checkMysqlShellCompatibility verifies that a MySQL Shell at shellVersion
+// can drive a MySQL Server at serverVersion via AdminAPI. The rule is:
+// mysqlsh's major.minor must be >= the server's major.minor. In particular,
+// MySQL Shell 8.0.x refuses any server > 8.0 with
+// "Unsupported server version: AdminAPI operations in this version of
+// MySQL Shell support MySQL Server up to version 8.0".
+func checkMysqlShellCompatibility(shellVersion, serverVersion string) error {
+	shellList, err := common.VersionToList(shellVersion)
+	if err != nil {
+		return fmt.Errorf("invalid mysqlsh version '%s': %s", shellVersion, err)
+	}
+	serverList, err := common.VersionToList(serverVersion)
+	if err != nil {
+		return fmt.Errorf("invalid server version '%s': %s", serverVersion, err)
+	}
+	shellMajor, shellMinor := shellList[0], shellList[1]
+	serverMajor, serverMinor := serverList[0], serverList[1]
+	if shellMajor > serverMajor ||
+		(shellMajor == serverMajor && shellMinor >= serverMinor) {
+		return nil
+	}
+	return fmt.Errorf(
+		"MySQL Shell %s is too old for MySQL Server %s: "+
+			"the AdminAPI in mysqlsh %d.%d only supports MySQL Server up to %d.%d. "+
+			"Install mysqlsh >= %d.%d (see https://dev.mysql.com/downloads/shell/) "+
+			"and make sure it is the one found on $PATH, "+
+			"or place its 'mysqlsh' binary under <basedir>/bin/",
+		shellVersion, serverVersion,
+		shellMajor, shellMinor, shellMajor, shellMinor,
+		serverMajor, serverMinor)
+}
+
 // findMysqlRouter locates the mysqlrouter binary. It first checks the basedir/bin
 // directory, then falls back to the system PATH.
 func findMysqlRouter(basedir string) (string, error) {
@@ -116,6 +166,20 @@ func CreateInnoDBCluster(sandboxDef SandboxDef, origin string, nodes int, master
 	}
 	logger.Printf("Using MySQL Shell: %s\n", mysqlshPath)
 
+	// Pre-flight: fail early if the mysqlsh AdminAPI can't manage this
+	// server version (e.g. mysqlsh 8.0.x + server 8.4.x). If parsing the
+	// shell's own --version fails for any reason, proceed — we don't want
+	// unknown output to block a valid deployment.
+	shellVersion, err := getMysqlShellVersion(mysqlshPath)
+	if err != nil {
+		logger.Printf("Warning: could not determine mysqlsh version: %s\n", err)
+	} else {
+		logger.Printf("Detected MySQL Shell version: %s\n", shellVersion)
+		if err := checkMysqlShellCompatibility(shellVersion, sandboxDef.Version); err != nil {
+			return err
+		}
+	}
+
 	// Find mysqlrouter - optional if --skip-router is set
 	var mysqlrouterPath string
 	if !skipRouter {

sandbox/innodb_cluster_test.go

@@ -0,0 +1,99 @@
+// DBDeployer - The MySQL Sandbox
+// Copyright © 2006-2026 Giuseppe Maxia
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package sandbox
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestCheckMysqlShellCompatibility(t *testing.T) {
+	cases := []struct {
+		label     string
+		shell     string
+		server    string
+		wantErr   bool
+		wantMatch string // substring expected in error when wantErr is true
+	}{
+		// The exact scenario from issue #87
+		{"shell 8.0.36 rejects server 8.4.8", "8.0.36", "8.4.8", true, "too old"},
+		{"shell 8.0.36 rejects server 9.1.0", "8.0.36", "9.1.0", true, "too old"},
+
+		// Matching major.minor — allowed
+		{"shell 8.4.8 accepts server 8.4.8", "8.4.8", "8.4.8", false, ""},
+		{"shell 8.0.36 accepts server 8.0.42", "8.0.36", "8.0.42", false, ""},
+		{"shell 9.5.0 accepts server 9.5.0", "9.5.0", "9.5.0", false, ""},
+
+		// Shell newer than server — allowed
+		{"shell 8.4.0 accepts server 8.0.42", "8.4.0", "8.0.42", false, ""},
+		{"shell 9.5.0 accepts server 8.4.8", "9.5.0", "8.4.8", false, ""},
+
+		// Shell older than server by minor — rejected
+		{"shell 8.3.0 rejects server 8.4.0", "8.3.0", "8.4.0", true, "too old"},
+
+		// Malformed inputs
+		{"invalid shell version", "not-a-version", "8.4.8", true, "invalid mysqlsh version"},
+		{"invalid server version", "8.4.8", "nope", true, "invalid server version"},
+	}
+	for _, c := range cases {
+		err := checkMysqlShellCompatibility(c.shell, c.server)
+		if c.wantErr {
+			if err == nil {
+				t.Errorf("%s: expected error, got nil", c.label)
+				continue
+			}
+			if c.wantMatch != "" && !strings.Contains(err.Error(), c.wantMatch) {
+				t.Errorf("%s: error %q does not contain %q", c.label, err.Error(), c.wantMatch)
+			}
+		} else if err != nil {
+			t.Errorf("%s: unexpected error: %s", c.label, err)
+		}
+	}
+}
+
+func TestMysqlShellVersionRegexp(t *testing.T) {
+	cases := []struct {
+		label string
+		out   string
+		want  string
+	}{
+		{
+			"classic 8.0.36 output",
+			"mysqlsh   Ver 8.0.36 for Linux on x86_64 - for MySQL 8.0.36 (Source distribution)",
+			"8.0.36",
+		},
+		{
+			"8.4.8 output",
+			"mysqlsh   Ver 8.4.8 for Linux on x86_64 - for MySQL 8.4.8 (MySQL Community Server)",
+			"8.4.8",
+		},
+		{
+			"9.5.0 output",
+			"MySQL Shell Ver 9.5.0 for Linux on x86_64 - for MySQL 9.5.0",
+			"9.5.0",
+		},
+	}
+	for _, c := range cases {
+		m := mysqlShellVersionRegexp.FindStringSubmatch(c.out)
+		if len(m) < 2 {
+			t.Errorf("%s: no match in %q", c.label, c.out)
+			continue
+		}
+		if m[1] != c.want {
+			t.Errorf("%s: got %q, want %q", c.label, m[1], c.want)
+		}
+	}
+}