Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(action): enforce compatibility window (#20505)

p0ny770d941e51a7
diff --git a/action/command/check.go b/action/command/check.go
index 30f893b92d..407e0b45b0 100644
--- a/action/command/check.go
+++ b/action/command/check.go
@@ -60,7 +60,9 @@ func runCheck(w *world.World) func(*cobra.Command, []string) error {
defer client.close()
// Check version compatibility
- checkVersionCompatibility(w, client, args.Version)
+ if err := checkVersionCompatibility(w, client, args.Version); err != nil {
+ return err
+ }
releaseFiles, err := getReleaseFiles(w)
if err != nil {
diff --git a/action/command/rollout.go b/action/command/rollout.go
index dd973ae024..e391e8a075 100644
--- a/action/command/rollout.go
+++ b/action/command/rollout.go
@@ -62,7 +62,9 @@ func runRollout(w *world.World) func(command *cobra.Command, _ []string) error {
defer client.close()
// Check version compatibility
- checkVersionCompatibility(w, client, args.Version)
+ if err := checkVersionCompatibility(w, client, args.Version); err != nil {
+ return err
+ }
var plan *v1pb.Plan
if w.Plan != "" {
diff --git a/action/command/root.go b/action/command/root.go
index 679ced197a..64d4839ef2 100644
--- a/action/command/root.go
+++ b/action/command/root.go
@@ -5,6 +5,7 @@ import (
"log/slog"
"net/http"
"net/textproto"
+ "strconv"
"strings"
"time"
@@ -125,32 +126,144 @@ func (*customHeaderFlag) Type() string {
return "header"
}
-func checkVersionCompatibility(w *world.World, client *client, cliVersion string) {
+func checkVersionCompatibility(w *world.World, client *client, cliVersion string) error {
if cliVersion == "unknown" {
w.Logger.Warn("CLI version unknown, unable to check compatibility")
- return
+ return nil
}
actuatorInfo, err := client.getActuatorInfo(context.Background())
if err != nil {
w.Logger.Warn("Unable to get server version for compatibility check", "error", err)
- return
+ return nil
}
serverVersion := actuatorInfo.Version
if serverVersion == "" {
w.Logger.Warn("Server version is empty, unable to check compatibility")
- return
+ return nil
+ }
+
+ serverParsedVersion, err := parseVersion(serverVersion)
+ if err != nil {
+ return errors.Errorf("unable to parse Bytebase server version %q for compatibility check: %v; expected a self-hosted version like 3.14.0 or a Cloud version like cloud-YYYYMMDD", serverVersion, err)
}
if cliVersion == "latest" {
- w.Logger.Warn("Using 'latest' CLI version. It is recommended to use a specific version like bytebase-action:" + serverVersion + " to match your Bytebase server version " + serverVersion)
- return
+ actionTag := recommendedActionTag(serverParsedVersion)
+ w.Logger.Warn("Using 'latest' CLI version. It is recommended to use a specific version like bytebase-action:" + actionTag + " to match your Bytebase server version " + serverVersion)
+ return nil
}
- if cliVersion != serverVersion {
- w.Logger.Warn("CLI version mismatch", "cliVersion", cliVersion, "serverVersion", serverVersion, "recommendation", "use bytebase-action:"+serverVersion+" to match your Bytebase server")
- } else {
+ cliParsedVersion, err := parseVersion(cliVersion)
+ if err != nil {
+ return errors.Errorf("unable to parse CLI version %q for compatibility check: %v; expected a self-hosted version like 3.14.0 or a Cloud version like cloud-YYYYMMDD", cliVersion, err)
+ }
+ if cliParsedVersion.kind != serverParsedVersion.kind {
+ return errors.Errorf("unable to compare CLI version %q and Bytebase server version %q for compatibility check; expected both versions to use self-hosted versions like 3.14.0 or Cloud versions like cloud-YYYYMMDD", cliVersion, serverVersion)
+ }
+
+ if cliVersion == serverVersion {
w.Logger.Info("CLI version matches server version", "version", cliVersion)
+ return nil
+ }
+
+ if cliParsedVersion.kind == versionKindCloud {
+ // Cloud action/server builds are date-qualified and compatible when the
+ // action build is from the server's latest 7 days. Newer action builds
+ // may call APIs that do not exist on older or rolled-back servers.
+ dateDiff := int(cliParsedVersion.date.Sub(serverParsedVersion.date).Hours() / 24)
+ if dateDiff < -7 || dateDiff > 0 {
+ actionTag := recommendedActionTag(serverParsedVersion)
+ return errors.Errorf("CLI version %q is outside the compatibility window for Bytebase server version %q. Cloud compatibility requires both versions to use cloud-YYYYMMDD and be within 7 days. Use bytebase-action:%s to match your Bytebase server", cliVersion, serverVersion, actionTag)
+ }
+
+ actionTag := recommendedActionTag(serverParsedVersion)
+ w.Logger.Warn("CLI version is within the compatibility window but does not match server version", "cliVersion", cliVersion, "serverVersion", serverVersion, "recommendation", "use bytebase-action:"+actionTag+" to match your Bytebase server")
+ return nil
+ }
+
+ // Self-hosted action/server releases are compatible when the action version
+ // is within the server's latest 2 minor releases. Newer action versions may
+ // call APIs that do not exist on older servers, so reject them.
+ minorDiff := cliParsedVersion.minor - serverParsedVersion.minor
+ if cliParsedVersion.major != serverParsedVersion.major || minorDiff < -2 || minorDiff > 0 {
+ actionTag := recommendedActionTag(serverParsedVersion)
+ return errors.Errorf("CLI version %q is outside the compatibility window for Bytebase server version %q. Self-hosted compatibility requires the same major version and versions within 2 minor versions. Use bytebase-action:%s to match your Bytebase server", cliVersion, serverVersion, actionTag)
+ }
+
+ actionTag := recommendedActionTag(serverParsedVersion)
+ w.Logger.Warn("CLI version is within the compatibility window but does not match server version", "cliVersion", cliVersion, "serverVersion", serverVersion, "recommendation", "use bytebase-action:"+actionTag+" to match your Bytebase server")
+ return nil
+}
+
+type versionKind int
+
+const (
+ versionKindRelease versionKind = iota
+ versionKindCloud
+)
+
+const cloudVersionPrefix = "cloud-"
+
+type parsedVersion struct {
+ kind versionKind
+ raw string
+ major int
+ minor int
+ date time.Time
+}
+
+func parseVersion(version string) (parsedVersion, error) {
+ if strings.HasPrefix(version, "cloud") {
+ t, err := parseCloudVersionDate(version)
+ if err != nil {
+ return parsedVersion{}, err
+ }
+ return parsedVersion{kind: versionKindCloud, raw: version, date: t}, nil
+ }
+ major, minor, err := parseReleaseMajorMinor(version)
+ if err != nil {
+ return parsedVersion{}, err
+ }
+ return parsedVersion{kind: versionKindRelease, raw: version, major: major, minor: minor}, nil
+}
+
+func recommendedActionTag(version parsedVersion) string {
+ if version.kind == versionKindCloud {
+ return "cloud"
+ }
+ return version.raw
+}
+
+func parseCloudVersionDate(version string) (time.Time, error) {
+ if len(version) != len("cloud-YYYYMMDD") || !strings.HasPrefix(version, cloudVersionPrefix) {
+ return time.Time{}, errors.Errorf("expected cloud-YYYYMMDD")
+ }
+ for _, r := range strings.TrimPrefix(version, cloudVersionPrefix) {
+ if r < '0' || r > '9' {
+ return time.Time{}, errors.Errorf("expected cloud-YYYYMMDD")
+ }
+ }
+ t, err := time.Parse("20060102", strings.TrimPrefix(version, cloudVersionPrefix))
+ if err != nil {
+ return time.Time{}, err
+ }
+ return t, nil
+}
+
+func parseReleaseMajorMinor(version string) (int, int, error) {
+ parts := strings.Split(version, ".")
+ if len(parts) < 2 {
+ return 0, 0, errors.Errorf("expected at least major and minor release segments")
+ }
+ major, err := strconv.Atoi(parts[0])
+ if err != nil {
+ return 0, 0, errors.Wrap(err, "invalid major release segment")
+ }
+ minor, err := strconv.Atoi(parts[1])
+ if err != nil {
+ return 0, 0, errors.Wrap(err, "invalid minor release segment")
}
+ return major, minor, nil
}
diff --git a/action/command/root_test.go b/action/command/root_test.go
new file mode 100644
index 0000000000..22c1433236
--- /dev/null
+++ b/action/command/root_test.go
@@ -0,0 +1,210 @@
+package command
+
+import (
+ "context"
+ "io"
+ "log/slog"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+
+ "connectrpc.com/connect"
+ "github.com/stretchr/testify/require"
+ "google.golang.org/protobuf/types/known/emptypb"
+
+ "github.com/bytebase/bytebase/action/world"
+ v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
+ "github.com/bytebase/bytebase/backend/generated-go/v1/v1connect"
+)
+
+func TestCheckVersionCompatibility(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ cliVersion string
+ serverVersion string
+ wantError string
+ }{
+ {
+ name: "same release version",
+ cliVersion: "3.14.0",
+ serverVersion: "3.14.0",
+ },
+ {
+ name: "release version within two minor versions",
+ cliVersion: "3.13.0",
+ serverVersion: "3.15.0",
+ },
+ {
+ name: "release version outside two minor versions",
+ cliVersion: "3.12.0",
+ serverVersion: "3.15.0",
+ wantError: "outside the compatibility window",
+ },
+ {
+ name: "newer release version is outside window",
+ cliVersion: "3.17.0",
+ serverVersion: "3.15.0",
+ wantError: "outside the compatibility window",
+ },
+ {
+ name: "release version with different major is outside window",
+ cliVersion: "2.15.0",
+ serverVersion: "3.15.0",
+ wantError: "outside the compatibility window",
+ },
+ {
+ name: "plain cloud action is not a dated cloud build",
+ cliVersion: "cloud-20260604",
+ serverVersion: "cloud",
+ wantError: "unable to parse",
+ },
+ {
+ name: "plain cloud server is not a dated cloud build",
+ cliVersion: "cloud",
+ serverVersion: "cloud-20260604",
+ wantError: "unable to parse",
+ },
+ {
+ name: "dated cloud builds match",
+ cliVersion: "cloud-20260604",
+ serverVersion: "cloud-20260604",
+ },
+ {
+ name: "dated cloud builds within seven days",
+ cliVersion: "cloud-20260604",
+ serverVersion: "cloud-20260611",
+ },
+ {
+ name: "newer dated cloud build is outside window",
+ cliVersion: "cloud-20260611",
+ serverVersion: "cloud-20260604",
+ wantError: "outside the compatibility window",
+ },
+ {
+ name: "dated cloud builds outside seven days",
+ cliVersion: "cloud-20260603",
+ serverVersion: "cloud-20260611",
+ wantError: "outside the compatibility window",
+ },
+ {
+ name: "cloud action is not compatible with release server",
+ cliVersion: "cloud-20260604",
+ serverVersion: "3.14.0",
+ wantError: "unable to compare",
+ },
+ {
+ name: "invalid release version is parse error",
+ cliVersion: "3",
+ serverVersion: "3.14.0",
+ wantError: "unable to parse",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ client := newActuatorInfoTestClient(t, tt.serverVersion)
+ w := &world.World{Logger: slog.New(slog.NewTextHandler(io.Discard, nil))}
+
+ err := checkVersionCompatibility(w, client, tt.cliVersion)
+ if tt.wantError == "" {
+ require.NoError(t, err)
+ return
+ }
+ require.Error(t, err)
+ require.Contains(t, err.Error(), tt.wantError)
+ })
+ }
+}
+
+func TestRecommendedActionTag(t *testing.T) {
+ t.Parallel()
+
+ releaseVersion, err := parseVersion("3.14.0")
+ require.NoError(t, err)
+ require.Equal(t, "3.14.0", recommendedActionTag(releaseVersion))
+
+ cloudVersion, err := parseVersion("cloud-20260604")
+ require.NoError(t, err)
+ require.Equal(t, "cloud", recommendedActionTag(cloudVersion))
+}
+
+func TestCheckVersionCompatibilityReturnsErrorOutsideWindow(t *testing.T) {
+ t.Parallel()
+
+ client := newActuatorInfoTestClient(t, "3.15.0")
+ w := &world.World{Logger: slog.New(slog.NewTextHandler(io.Discard, nil))}
+
+ err := checkVersionCompatibility(w, client, "3.12.0")
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "outside the compatibility window")
+ require.Contains(t, err.Error(), "same major version")
+ require.Contains(t, err.Error(), "within 2 minor versions")
+}
+
+func TestCheckVersionCompatibilityReturnsUsefulCloudError(t *testing.T) {
+ t.Parallel()
+
+ client := newActuatorInfoTestClient(t, "cloud-20260604")
+ w := &world.World{Logger: slog.New(slog.NewTextHandler(io.Discard, nil))}
+
+ err := checkVersionCompatibility(w, client, "cloud-20260527")
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "cloud-YYYYMMDD")
+ require.Contains(t, err.Error(), "within 7 days")
+}
+
+func TestCheckVersionCompatibilityReturnsParseError(t *testing.T) {
+ t.Parallel()
+
+ client := newActuatorInfoTestClient(t, "cloud")
+ w := &world.World{Logger: slog.New(slog.NewTextHandler(io.Discard, nil))}
+
+ err := checkVersionCompatibility(w, client, "cloud-20260604")
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "unable to parse")
+ require.NotContains(t, err.Error(), "outside the compatibility window")
+}
+
+func TestCheckVersionCompatibilityAllowsVersionsWithinWindow(t *testing.T) {
+ t.Parallel()
+
+ client := newActuatorInfoTestClient(t, "cloud-20260604")
+ w := &world.World{Logger: slog.New(slog.NewTextHandler(io.Discard, nil))}
+
+ require.NoError(t, checkVersionCompatibility(w, client, "cloud-20260528"))
+}
+
+func newActuatorInfoTestClient(t *testing.T, version string) *client {
+ t.Helper()
+
+ path, handler := v1connect.NewActuatorServiceHandler(&actuatorInfoTestService{version: version})
+ mux := http.NewServeMux()
+ mux.Handle(path, handler)
+ server := httptest.NewServer(mux)
+ t.Cleanup(server.Close)
+
+ client, err := newClient(server.URL, "token", "", "", defaultClientOptions())
+ require.NoError(t, err)
+ t.Cleanup(client.close)
+ return client
+}
+
+type actuatorInfoTestService struct {
+ version string
+}
+
+func (s *actuatorInfoTestService) GetActuatorInfo(context.Context, *connect.Request[v1pb.GetActuatorInfoRequest]) (*connect.Response[v1pb.ActuatorInfo], error) {
+ return connect.NewResponse(&v1pb.ActuatorInfo{Version: s.version}), nil
+}
+
+func (*actuatorInfoTestService) SetupSample(context.Context, *connect.Request[v1pb.SetupSampleRequest]) (*connect.Response[emptypb.Empty], error) {
+ return connect.NewResponse(&emptypb.Empty{}), nil
+}
+
+func (*actuatorInfoTestService) DeleteCache(context.Context, *connect.Request[v1pb.DeleteCacheRequest]) (*connect.Response[emptypb.Empty], error) {
+ return connect.NewResponse(&emptypb.Empty{}), nil
+}