Skip to content

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

fix: classify gh-ost binlog validation errors (#20438)

p0ny53be315357ac
diff --git a/backend/component/ghost/validator.go b/backend/component/ghost/validator.go
index 8c3af2a0bd..2bb64d8156 100644
--- a/backend/component/ghost/validator.go
+++ b/backend/component/ghost/validator.go
@@ -12,11 +12,22 @@ import (
"github.com/bytebase/bytebase/backend/plugin/db"
)
+type binlogValidationFailureReason string
+
+const (
+ binlogStatusInaccessible binlogValidationFailureReason = "binlog_status_inaccessible"
+ binlogDisabled binlogValidationFailureReason = "binlog_disabled"
+ missingReplicationPrivilege binlogValidationFailureReason = "missing_replication_privilege"
+ unsupportedBinlogFormat binlogValidationFailureReason = "unsupported_binlog_format"
+ validationQueryFailed binlogValidationFailureReason = "validation_query_failed"
+)
+
// BinlogValidationResult contains detailed results of binlog access validation
type BinlogValidationResult struct {
// Core validation state
- Valid bool
- Error error
+ Valid bool
+ Error error
+ FailureReason binlogValidationFailureReason
// Detailed findings for specific error messages
BinlogEnabled bool
@@ -48,6 +59,7 @@ func ValidateBinlogAccess(ctx context.Context, driver db.Driver, adminDataSource
if !canAccessBinlog {
result.Valid = false
+ result.FailureReason = binlogStatusInaccessible
result.Error = errors.New("cannot access binary logs - ensure user has REPLICATION CLIENT privilege")
slog.Error("binlog access validation failed: cannot access binary logs",
slog.String("host", adminDataSource.GetHost()),
@@ -60,6 +72,7 @@ func ValidateBinlogAccess(ctx context.Context, driver db.Driver, adminDataSource
row := driver.GetDB().QueryRowContext(ctx, "SELECT @@log_bin")
if err := row.Scan(&logBin); err != nil {
result.Valid = false
+ result.FailureReason = validationQueryFailed
result.Error = errors.Wrap(err, "failed to check if binary logging is enabled")
return result
}
@@ -67,6 +80,7 @@ func ValidateBinlogAccess(ctx context.Context, driver db.Driver, adminDataSource
result.BinlogEnabled = (logBin == "1" || strings.ToUpper(logBin) == "ON")
if !result.BinlogEnabled {
result.Valid = false
+ result.FailureReason = binlogDisabled
result.Error = errors.New("binary logging is not enabled on this MySQL instance")
return result
}
@@ -75,6 +89,7 @@ func ValidateBinlogAccess(ctx context.Context, driver db.Driver, adminDataSource
rows, err := driver.GetDB().QueryContext(ctx, "SHOW GRANTS")
if err != nil {
result.Valid = false
+ result.FailureReason = validationQueryFailed
result.Error = errors.Wrap(err, "failed to check user grants")
return result
}
@@ -100,12 +115,14 @@ func ValidateBinlogAccess(ctx context.Context, driver db.Driver, adminDataSource
if err := rows.Err(); err != nil {
result.Valid = false
+ result.FailureReason = validationQueryFailed
result.Error = errors.Wrap(err, "error reading grants")
return result
}
if !result.HasPrivilege {
result.Valid = false
+ result.FailureReason = missingReplicationPrivilege
result.MissingPrivileges = append(result.MissingPrivileges, "REPLICATION SLAVE")
result.Error = errors.New("user does not have REPLICATION SLAVE privilege required for gh-ost")
slog.Error("missing REPLICATION SLAVE privilege",
@@ -119,12 +136,14 @@ func ValidateBinlogAccess(ctx context.Context, driver db.Driver, adminDataSource
row = driver.GetDB().QueryRowContext(ctx, "SELECT @@binlog_format")
if err := row.Scan(&result.BinlogFormat); err != nil {
result.Valid = false
+ result.FailureReason = validationQueryFailed
result.Error = errors.Wrap(err, "failed to check binlog format")
return result
}
if strings.ToUpper(result.BinlogFormat) == "STATEMENT" {
result.Valid = false
+ result.FailureReason = unsupportedBinlogFormat
result.Error = errors.Errorf("binlog_format is %s, but gh-ost requires ROW or MIXED format", result.BinlogFormat)
return result
}
@@ -146,32 +165,31 @@ func (r *BinlogValidationResult) GetUserFriendlyError() (title, content string)
title = "gh-ost migration prerequisites not met"
- if !r.BinlogEnabled {
- content = "Binary logging is not enabled on this MySQL instance. Please enable it with:\n" +
- "SET GLOBAL log_bin=ON (requires MySQL restart)"
- return title, content
- }
-
- if !r.HasPrivilege && len(r.MissingPrivileges) > 0 {
- content = fmt.Sprintf("Database user is missing required privilege: %s\n", strings.Join(r.MissingPrivileges, ", ")) +
- "Please grant it with:\n" +
- "GRANT REPLICATION SLAVE ON *.* TO 'user'@'host'"
- return title, content
- }
-
- if r.BinlogFormat == "STATEMENT" {
- content = fmt.Sprintf("Current binlog_format is %s, but gh-ost requires ROW or MIXED format.\n", r.BinlogFormat) +
+ switch r.FailureReason {
+ case binlogStatusInaccessible:
+ return title, "Cannot access binary log status. Ensure the Bytebase admin user has REPLICATION CLIENT privilege."
+ case binlogDisabled:
+ return title, "Binary logging is not enabled on this MySQL instance."
+ case missingReplicationPrivilege:
+ missingPrivileges := strings.Join(r.MissingPrivileges, ", ")
+ if missingPrivileges == "" {
+ missingPrivileges = "REPLICATION SLAVE"
+ }
+ return title, fmt.Sprintf("Database user is missing required privilege: %s\n", missingPrivileges) +
+ "Please grant REPLICATION SLAVE or an equivalent replication privilege to the Bytebase admin user."
+ case unsupportedBinlogFormat:
+ return title, fmt.Sprintf("Current binlog_format is %s, but gh-ost requires ROW or MIXED format.\n", r.BinlogFormat) +
"Please change it with:\n" +
"SET GLOBAL binlog_format='ROW'"
- return title, content
+ case validationQueryFailed:
+ if r.Error != nil {
+ return title, fmt.Sprintf("Validation failed: %v", r.Error)
+ }
+ return title, "Validation failed"
}
- // Generic error fallback
if r.Error != nil {
- content = fmt.Sprintf("Validation failed: %v", r.Error)
- } else {
- content = "Unknown validation error occurred"
+ return title, fmt.Sprintf("Validation failed: %v", r.Error)
}
-
- return title, content
+ return title, "Unknown validation error occurred"
}
diff --git a/backend/component/ghost/validator_test.go b/backend/component/ghost/validator_test.go
new file mode 100644
index 0000000000..6c1186bd39
--- /dev/null
+++ b/backend/component/ghost/validator_test.go
@@ -0,0 +1,102 @@
+package ghost
+
+import (
+ "errors"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestBinlogValidationResultGetUserFriendlyError(t *testing.T) {
+ tests := []struct {
+ name string
+ result *BinlogValidationResult
+ wantTitle string
+ wantContent string
+ }{
+ {
+ name: "valid result",
+ result: &BinlogValidationResult{
+ Valid: true,
+ },
+ wantTitle: "",
+ wantContent: "",
+ },
+ {
+ name: "binlog status inaccessible",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: false,
+ Error: errors.New("cannot access binary logs - ensure user has REPLICATION CLIENT privilege"),
+ FailureReason: binlogStatusInaccessible,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Cannot access binary log status. Ensure the Bytebase admin user has REPLICATION CLIENT privilege.",
+ },
+ {
+ name: "binary logging disabled",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: false,
+ Error: errors.New("binary logging is not enabled on this MySQL instance"),
+ FailureReason: binlogDisabled,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Binary logging is not enabled on this MySQL instance.",
+ },
+ {
+ name: "missing replication privilege",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: true,
+ HasPrivilege: false,
+ MissingPrivileges: []string{"REPLICATION SLAVE"},
+ Error: errors.New("user does not have REPLICATION SLAVE privilege required for gh-ost"),
+ FailureReason: missingReplicationPrivilege,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Database user is missing required privilege: REPLICATION SLAVE\nPlease grant REPLICATION SLAVE or an equivalent replication privilege to the Bytebase admin user.",
+ },
+ {
+ name: "unsupported binlog format",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: true,
+ HasPrivilege: true,
+ BinlogFormat: "statement",
+ Error: errors.New("binlog_format is statement, but gh-ost requires ROW or MIXED format"),
+ FailureReason: unsupportedBinlogFormat,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Current binlog_format is statement, but gh-ost requires ROW or MIXED format.\nPlease change it with:\nSET GLOBAL binlog_format='ROW'",
+ },
+ {
+ name: "generic validation query failure",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: false,
+ Error: errors.New("failed to check if binary logging is enabled: access denied"),
+ FailureReason: validationQueryFailed,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Validation failed: failed to check if binary logging is enabled: access denied",
+ },
+ {
+ name: "unknown invalid result falls back to error",
+ result: &BinlogValidationResult{
+ Valid: false,
+ Error: errors.New("unexpected validator failure"),
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Validation failed: unexpected validator failure",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ gotTitle, gotContent := tt.result.GetUserFriendlyError()
+ require.Equal(t, tt.wantTitle, gotTitle)
+ require.Equal(t, tt.wantContent, gotContent)
+ })
+ }
+}
diff --git a/docs/superpowers/plans/2026-05-29-gh-ost-binlog-validation-error.md b/docs/superpowers/plans/2026-05-29-gh-ost-binlog-validation-error.md
new file mode 100644
index 0000000000..8917ff394a
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-29-gh-ost-binlog-validation-error.md
@@ -0,0 +1,396 @@
+# gh-ost Binlog Validation Error Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fix gh-ost plan-save validation so binlog status access failures are not reported as disabled binary logging.
+
+**Architecture:** Keep the change inside `backend/component/ghost`. Add an explicit failure reason to `BinlogValidationResult`; set it in each failing validator branch; make the user-facing formatter switch on that reason instead of inferring from booleans.
+
+**Tech Stack:** Go, `github.com/pkg/errors`, `github.com/stretchr/testify/require`, existing Bytebase gh-ost validation package.
+
+---
+
+## File Structure
+
+- Modify: `backend/component/ghost/validator.go`
+ - Owns gh-ost binlog prerequisite validation and conversion of validation failures into plan-check messages.
+- Create: `backend/component/ghost/validator_test.go`
+ - Table-driven unit tests for `GetUserFriendlyError()` messages and fallback behavior.
+
+---
+
+### Task 1: Add Failing Formatter Tests
+
+**Files:**
+- Create: `backend/component/ghost/validator_test.go`
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `backend/component/ghost/validator_test.go` with:
+
+```go
+package ghost
+
+import (
+ "errors"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestBinlogValidationResultGetUserFriendlyError(t *testing.T) {
+ tests := []struct {
+ name string
+ result *BinlogValidationResult
+ wantTitle string
+ wantContent string
+ }{
+ {
+ name: "valid result",
+ result: &BinlogValidationResult{
+ Valid: true,
+ },
+ wantTitle: "",
+ wantContent: "",
+ },
+ {
+ name: "binlog status inaccessible",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: false,
+ Error: errors.New("cannot access binary logs - ensure user has REPLICATION CLIENT privilege"),
+ FailureReason: binlogStatusInaccessible,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Cannot access binary log status. Ensure the Bytebase admin user has REPLICATION CLIENT privilege.",
+ },
+ {
+ name: "binary logging disabled",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: false,
+ Error: errors.New("binary logging is not enabled on this MySQL instance"),
+ FailureReason: binlogDisabled,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Binary logging is not enabled on this MySQL instance.",
+ },
+ {
+ name: "missing replication privilege",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: true,
+ HasPrivilege: false,
+ MissingPrivileges: []string{"REPLICATION SLAVE"},
+ Error: errors.New("user does not have REPLICATION SLAVE privilege required for gh-ost"),
+ FailureReason: missingReplicationPrivilege,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Database user is missing required privilege: REPLICATION SLAVE\nPlease grant REPLICATION SLAVE or an equivalent replication privilege to the Bytebase admin user.",
+ },
+ {
+ name: "unsupported binlog format",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: true,
+ HasPrivilege: true,
+ BinlogFormat: "statement",
+ Error: errors.New("binlog_format is statement, but gh-ost requires ROW or MIXED format"),
+ FailureReason: unsupportedBinlogFormat,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Current binlog_format is statement, but gh-ost requires ROW or MIXED format.\nPlease change it with:\nSET GLOBAL binlog_format='ROW'",
+ },
+ {
+ name: "generic validation query failure",
+ result: &BinlogValidationResult{
+ Valid: false,
+ BinlogEnabled: false,
+ Error: errors.New("failed to check if binary logging is enabled: access denied"),
+ FailureReason: validationQueryFailed,
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Validation failed: failed to check if binary logging is enabled: access denied",
+ },
+ {
+ name: "unknown invalid result falls back to error",
+ result: &BinlogValidationResult{
+ Valid: false,
+ Error: errors.New("unexpected validator failure"),
+ },
+ wantTitle: "gh-ost migration prerequisites not met",
+ wantContent: "Validation failed: unexpected validator failure",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ gotTitle, gotContent := tt.result.GetUserFriendlyError()
+ require.Equal(t, tt.wantTitle, gotTitle)
+ require.Equal(t, tt.wantContent, gotContent)
+ })
+ }
+}
+```
+
+- [ ] **Step 2: Run the focused test to verify it fails**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/component/ghost -run TestBinlogValidationResultGetUserFriendlyError
+```
+
+Expected: FAIL because `FailureReason`, `binlogStatusInaccessible`, `binlogDisabled`, `missingReplicationPrivilege`, `unsupportedBinlogFormat`, and `validationQueryFailed` are not defined.
+
+- [ ] **Step 3: Commit the failing tests**
+
+Run:
+
+```bash
+git add backend/component/ghost/validator_test.go
+git commit -m "test: cover gh-ost binlog validation messages"
+```
+
+Expected: commit succeeds with only the new test file staged.
+
+---
+
+### Task 2: Add Explicit Failure Reasons
+
+**Files:**
+- Modify: `backend/component/ghost/validator.go`
+- Test: `backend/component/ghost/validator_test.go`
+
+- [ ] **Step 1: Add the failure reason type and field**
+
+In `backend/component/ghost/validator.go`, add this type and constants after the imports and before `BinlogValidationResult`:
+
+```go
+type binlogValidationFailureReason string
+
+const (
+ binlogStatusInaccessible binlogValidationFailureReason = "binlog_status_inaccessible"
+ binlogDisabled binlogValidationFailureReason = "binlog_disabled"
+ missingReplicationPrivilege binlogValidationFailureReason = "missing_replication_privilege"
+ unsupportedBinlogFormat binlogValidationFailureReason = "unsupported_binlog_format"
+ validationQueryFailed binlogValidationFailureReason = "validation_query_failed"
+)
+```
+
+Then add this field to `BinlogValidationResult` after `Error error`:
+
+```go
+FailureReason binlogValidationFailureReason
+```
+
+- [ ] **Step 2: Set failure reasons in validator branches**
+
+Update `ValidateBinlogAccess()` so each failing branch sets `FailureReason` before returning:
+
+```go
+if !canAccessBinlog {
+ result.Valid = false
+ result.FailureReason = binlogStatusInaccessible
+ result.Error = errors.New("cannot access binary logs - ensure user has REPLICATION CLIENT privilege")
+ slog.Error("binlog access validation failed: cannot access binary logs",
+ slog.String("host", adminDataSource.GetHost()),
+ slog.String("user", adminDataSource.GetUsername()))
+ return result
+}
+```
+
+```go
+if err := row.Scan(&logBin); err != nil {
+ result.Valid = false
+ result.FailureReason = validationQueryFailed
+ result.Error = errors.Wrap(err, "failed to check if binary logging is enabled")
+ return result
+}
+```
+
+```go
+if !result.BinlogEnabled {
+ result.Valid = false
+ result.FailureReason = binlogDisabled
+ result.Error = errors.New("binary logging is not enabled on this MySQL instance")
+ return result
+}
+```
+
+```go
+if err != nil {
+ result.Valid = false
+ result.FailureReason = validationQueryFailed
+ result.Error = errors.Wrap(err, "failed to check user grants")
+ return result
+}
+```
+
+```go
+if err := rows.Err(); err != nil {
+ result.Valid = false
+ result.FailureReason = validationQueryFailed
+ result.Error = errors.Wrap(err, "error reading grants")
+ return result
+}
+```
+
+```go
+if !result.HasPrivilege {
+ result.Valid = false
+ result.FailureReason = missingReplicationPrivilege
+ result.MissingPrivileges = append(result.MissingPrivileges, "REPLICATION SLAVE")
+ result.Error = errors.New("user does not have REPLICATION SLAVE privilege required for gh-ost")
+ slog.Error("missing REPLICATION SLAVE privilege",
+ slog.String("host", adminDataSource.GetHost()),
+ slog.String("user", adminDataSource.GetUsername()),
+ slog.Any("grants", result.CurrentGrants))
+ return result
+}
+```
+
+```go
+if err := row.Scan(&result.BinlogFormat); err != nil {
+ result.Valid = false
+ result.FailureReason = validationQueryFailed
+ result.Error = errors.Wrap(err, "failed to check binlog format")
+ return result
+}
+```
+
+```go
+if strings.ToUpper(result.BinlogFormat) == "STATEMENT" {
+ result.Valid = false
+ result.FailureReason = unsupportedBinlogFormat
+ result.Error = errors.Errorf("binlog_format is %s, but gh-ost requires ROW or MIXED format", result.BinlogFormat)
+ return result
+}
+```
+
+- [ ] **Step 3: Replace formatter inference with a reason switch**
+
+Replace the body of `GetUserFriendlyError()` after `title := "gh-ost migration prerequisites not met"` with:
+
+```go
+switch r.FailureReason {
+case binlogStatusInaccessible:
+ return title, "Cannot access binary log status. Ensure the Bytebase admin user has REPLICATION CLIENT privilege."
+case binlogDisabled:
+ return title, "Binary logging is not enabled on this MySQL instance."
+case missingReplicationPrivilege:
+ missingPrivileges := strings.Join(r.MissingPrivileges, ", ")
+ if missingPrivileges == "" {
+ missingPrivileges = "REPLICATION SLAVE"
+ }
+ return title, fmt.Sprintf("Database user is missing required privilege: %s\n", missingPrivileges) +
+ "Please grant REPLICATION SLAVE or an equivalent replication privilege to the Bytebase admin user."
+case unsupportedBinlogFormat:
+ return title, fmt.Sprintf("Current binlog_format is %s, but gh-ost requires ROW or MIXED format.\n", r.BinlogFormat) +
+ "Please change it with:\n" +
+ "SET GLOBAL binlog_format='ROW'"
+case validationQueryFailed:
+ if r.Error != nil {
+ return title, fmt.Sprintf("Validation failed: %v", r.Error)
+ }
+ return title, "Validation failed"
+}
+
+if r.Error != nil {
+ return title, fmt.Sprintf("Validation failed: %v", r.Error)
+}
+return title, "Unknown validation error occurred"
+```
+
+This ensures `BinlogEnabled=false` no longer causes the disabled-binlog message unless the validator explicitly sets `binlogDisabled`.
+
+- [ ] **Step 4: Format the changed Go files**
+
+Run:
+
+```bash
+gofmt -w backend/component/ghost/validator.go backend/component/ghost/validator_test.go
+```
+
+Expected: no command output.
+
+- [ ] **Step 5: Run the focused test**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/component/ghost -run TestBinlogValidationResultGetUserFriendlyError
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit the implementation**
+
+Run:
+
+```bash
+git add backend/component/ghost/validator.go backend/component/ghost/validator_test.go
+git commit -m "fix: classify gh-ost binlog validation errors"
+```
+
+Expected: commit succeeds with validator and test changes.
+
+---
+
+### Task 3: Verify Package and Required Go Checks
+
+**Files:**
+- Verify: `backend/component/ghost/validator.go`
+- Verify: `backend/component/ghost/validator_test.go`
+
+- [ ] **Step 1: Run the package tests**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/component/ghost
+```
+
+Expected: PASS for existing gh-ost package tests plus the new formatter test.
+
+- [ ] **Step 2: Run repository lint**
+
+Run:
+
+```bash
+golangci-lint run --allow-parallel-runners
+```
+
+Expected: PASS. If it reports issues, fix only issues caused by this change, then rerun the same command until it reports no issues.
+
+- [ ] **Step 3: Run repository lint auto-fix if lint reports fixable issues**
+
+Only if Step 2 reports fixable issues, run:
+
+```bash
+golangci-lint run --fix --allow-parallel-runners
+golangci-lint run --allow-parallel-runners
+```
+
+Expected: final lint run passes. Review any modified files before committing.
+
+- [ ] **Step 4: Commit verification fixes if any were needed**
+
+If Step 3 changed files, run:
+
+```bash
+git add backend/component/ghost/validator.go backend/component/ghost/validator_test.go
+git commit -m "chore: address gh-ost validator lint"
+```
+
+Expected: commit succeeds only if lint or formatting produced additional changes. If no files changed, skip this step.
+
+- [ ] **Step 5: Record final status**
+
+Run:
+
+```bash
+git status --short
+```
+
+Expected: no unstaged or uncommitted changes unless unrelated pre-existing files were already dirty.
diff --git a/docs/superpowers/specs/2026-05-29-gh-ost-binlog-validation-error-design.md b/docs/superpowers/specs/2026-05-29-gh-ost-binlog-validation-error-design.md
new file mode 100644
index 0000000000..929bbc4492
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-29-gh-ost-binlog-validation-error-design.md
@@ -0,0 +1,90 @@
+# gh-ost Binlog Validation Error Design
+
+## Context
+
+Bytebase 3.16.0 can report `Binary logging is not enabled on this MySQL instance`
+during gh-ost plan-save validation even when AWS RDS binary logging is enabled.
+The current validator initializes `BinlogEnabled` to `false`, then returns early
+if it cannot run `SHOW MASTER STATUS` or `SHOW BINARY LOG STATUS`. The
+user-facing formatter checks `!BinlogEnabled` first, so an access or privilege
+failure is misclassified as disabled binary logging.
+
+The fix should preserve compatibility with older MySQL and managed MySQL
+variants. Status access should point to `REPLICATION CLIENT`; gh-ost replication
+privilege messaging should continue to accept older `REPLICATION SLAVE` wording
+or an equivalent replication privilege.
+
+## Goals
+
+- Report binary logging as disabled only after `SELECT @@log_bin` succeeds and
+ returns OFF or 0.
+- Report binlog status access failures as access or privilege problems, not as
+ disabled binary logging.
+- Keep privilege guidance compatible with older MySQL/RDS installations.
+- Add focused tests for customer-visible validation messages.
+
+## Non-Goals
+
+- Do not change gh-ost migration execution behavior.
+- Do not require only modern privilege names such as `REPLICATION REPLICA`.
+- Do not broaden the plan-check flow beyond gh-ost binlog prerequisite
+ validation.
+
+## Design
+
+Add an explicit failure reason to `BinlogValidationResult`, implemented as an
+unexported typed string with constants:
+
+- `binlogStatusInaccessible`
+- `binlogDisabled`
+- `missingReplicationPrivilege`
+- `unsupportedBinlogFormat`
+- `validationQueryFailed`
+
+`ValidateBinlogAccess()` should set the reason at the branch where validation
+fails. `GetUserFriendlyError()` should switch on that reason instead of inferring
+the cause from booleans.
+
+Expected messages:
+
+- Status access failure:
+ `Cannot access binary log status. Ensure the Bytebase admin user has
+ REPLICATION CLIENT privilege.`
+- Disabled binlog:
+ `Binary logging is not enabled on this MySQL instance.`
+- Missing gh-ost replication privilege:
+ mention `REPLICATION SLAVE` or equivalent replication privilege, preserving
+ compatibility with older MySQL and RDS.
+- Statement binlog format:
+ keep the existing ROW/MIXED requirement message.
+
+The validation should still try `SHOW MASTER STATUS` first for older versions
+and fall back to `SHOW BINARY LOG STATUS` for MySQL 8.4+. The first failure
+branch should include enough internal error detail for debugging, but the
+customer-facing text should avoid claiming that binary logging is disabled unless
+that was verified.
+
+## Testing
+
+Add `backend/component/ghost/validator_test.go` with table-driven tests for
+`GetUserFriendlyError()` covering:
+
+- binlog status inaccessible
+- binary logging disabled
+- missing replication privilege
+- unsupported binlog format
+- generic validation query failure
+
+Keep this change focused on formatter tests and the direct reason assignment in
+the validator branches. Do not add a new SQL mock dependency for this narrow
+message classification fix.
+
+Run:
+
+```bash
+gofmt -w backend/component/ghost/validator.go backend/component/ghost/validator_test.go
+go test -v -count=1 ./backend/component/ghost
+```
+
+If implementation changes are made later, also run the repository-required
+`golangci-lint run --allow-parallel-runners` before completion.