Skip to content

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

fix: async backup schema sync (#20115)

p0nydf450cd7bcba
diff --git a/backend/runner/taskrun/database_migrate_executor.go b/backend/runner/taskrun/database_migrate_executor.go
index 9151daa0d7..f177ed192b 100644
--- a/backend/runner/taskrun/database_migrate_executor.go
+++ b/backend/runner/taskrun/database_migrate_executor.go
@@ -887,19 +887,9 @@ func (exec *DatabaseMigrateExecutor) backupData(
}
if database.Engine != storepb.Engine_POSTGRES {
- if err := exec.schemaSyncer.SyncDatabaseSchema(ctx, backupDatabase); err != nil {
- slog.Error("failed to sync backup database schema",
- slog.String("database", targetDatabaseName),
- log.BBError(err),
- )
- }
+ exec.schemaSyncer.SyncDatabaseAsync(backupDatabase)
} else {
- if err := exec.schemaSyncer.SyncDatabaseSchema(ctx, database); err != nil {
- slog.Error("failed to sync backup database schema",
- slog.String("database", fmt.Sprintf("/instances/%s/databases/%s", instance.ResourceID, database.DatabaseName)),
- log.BBError(err),
- )
- }
+ exec.schemaSyncer.SyncDatabaseAsync(database)
}
return priorBackupDetail, nil
diff --git a/docs/superpowers/plans/2026-04-24-backup-schema-sync-async.md b/docs/superpowers/plans/2026-04-24-backup-schema-sync-async.md
new file mode 100644
index 0000000000..f4142a133f
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-24-backup-schema-sync-async.md
@@ -0,0 +1,152 @@
+# Backup Schema Sync Async 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:** Move `backupData`'s backup-phase schema metadata refresh off the migration task run critical path by enqueueing the existing async schema sync.
+
+**Architecture:** Keep the current `backupData` control flow and replace only the final synchronous schema sync calls with `SyncDatabaseAsync`. Non-Postgres still targets the backup database; Postgres still targets the source database because backup tables live in a backup schema inside that database. The async queue is best-effort in HA, which is acceptable because this sync only refreshes metadata and does not feed task result, changelog, revision, or sync history persistence.
+
+**Tech Stack:** Go, existing `backend/runner/taskrun` executor, existing `backend/runner/schemasync.Syncer.SyncDatabaseAsync`.
+
+---
+
+### Task 1: Replace Backup Schema Sync With Async Enqueue
+
+**Files:**
+- Modify: `backend/runner/taskrun/database_migrate_executor.go:889-903`
+
+- [ ] **Step 1: Record the current synchronous call sites**
+
+Run:
+
+```bash
+rg -n "SyncDatabaseSchema\\(ctx, (backupDatabase|database)\\)" backend/runner/taskrun/database_migrate_executor.go
+```
+
+Expected output before implementation:
+
+```text
+890: if err := exec.schemaSyncer.SyncDatabaseSchema(ctx, backupDatabase); err != nil {
+897: if err := exec.schemaSyncer.SyncDatabaseSchema(ctx, database); err != nil {
+```
+
+- [ ] **Step 2: Replace the blocking calls with async enqueue**
+
+Edit `backend/runner/taskrun/database_migrate_executor.go` and replace the block at the end of `backupData` with:
+
+```go
+ if database.Engine != storepb.Engine_POSTGRES {
+ exec.schemaSyncer.SyncDatabaseAsync(backupDatabase)
+ } else {
+ exec.schemaSyncer.SyncDatabaseAsync(database)
+ }
+```
+
+Remove the `slog.Error` blocks that only handled synchronous sync failures. `SyncDatabaseAsync` does not return an error, and execution failures are handled later by the schema syncer when it drains the async queue.
+
+- [ ] **Step 3: Verify no backupData synchronous sync remains**
+
+Run:
+
+```bash
+rg -n "SyncDatabaseSchema\\(ctx, (backupDatabase|database)\\)" backend/runner/taskrun/database_migrate_executor.go
+```
+
+Expected output after implementation: no matches.
+
+- [ ] **Step 4: Verify both async branch targets are present**
+
+Run:
+
+```bash
+rg -n "SyncDatabaseAsync\\((backupDatabase|database)\\)" backend/runner/taskrun/database_migrate_executor.go
+```
+
+Expected output after implementation:
+
+```text
+890: exec.schemaSyncer.SyncDatabaseAsync(backupDatabase)
+892: exec.schemaSyncer.SyncDatabaseAsync(database)
+```
+
+- [ ] **Step 5: Format the modified Go file**
+
+Run:
+
+```bash
+gofmt -w backend/runner/taskrun/database_migrate_executor.go
+```
+
+- [ ] **Step 6: Run targeted tests**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/runner/taskrun
+```
+
+Expected: package passes.
+
+- [ ] **Step 7: Commit the implementation**
+
+Run:
+
+```bash
+git add backend/runner/taskrun/database_migrate_executor.go
+git commit -m "fix: async backup schema sync"
+```
+
+---
+
+### Task 2: Repository Verification
+
+**Files:**
+- Verify: `backend/runner/taskrun/database_migrate_executor.go`
+
+- [ ] **Step 1: Run Go lint**
+
+Run:
+
+```bash
+golangci-lint run --allow-parallel-runners
+```
+
+Expected: no issues. If lint reports issues, run the fix command in Step 2.
+
+- [ ] **Step 2: Run Go lint auto-fix if needed**
+
+Run only if Step 1 reports fixable issues:
+
+```bash
+golangci-lint run --fix --allow-parallel-runners
+golangci-lint run --allow-parallel-runners
+```
+
+Expected: the final lint command reports no issues.
+
+- [ ] **Step 3: Build backend**
+
+Run:
+
+```bash
+go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go
+```
+
+Expected: build succeeds.
+
+- [ ] **Step 4: Confirm final diff is scoped**
+
+Run:
+
+```bash
+git diff --stat HEAD~1..HEAD
+git status --short
+```
+
+Expected:
+
+```text
+backend/runner/taskrun/database_migrate_executor.go | ...
+```
+
+`git status --short` may still show the pre-existing untracked `frontend/.vscode/settings.json`; do not stage or modify it.
diff --git a/docs/superpowers/specs/2026-04-24-backup-schema-sync-async-design.md b/docs/superpowers/specs/2026-04-24-backup-schema-sync-async-design.md
new file mode 100644
index 0000000000..ab6ce762e1
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-24-backup-schema-sync-async-design.md
@@ -0,0 +1,71 @@
+# Backup Schema Sync Async Design
+
+## Context
+
+`backupData` in `backend/runner/taskrun/database_migrate_executor.go` creates prior-backup tables before a migration runs. After creating those backup tables, it currently calls `SyncDatabaseSchema` synchronously:
+
+- non-Postgres engines sync the backup database;
+- Postgres syncs the source database because backup tables live in the backup schema inside that database.
+
+This sync only refreshes Bytebase database metadata. Its result is not used to persist the task run result, changelog, revision, or sync history. When the sync is slow, it extends the visible prior-backup phase even though the backup tables have already been created.
+
+Bytebase can run in HA mode. The existing async schema sync path uses an in-memory per-replica queue (`SyncDatabaseAsync`/`databaseSyncMap`) drained by the schema syncer. That queue is best-effort: if the executing replica exits before the queue is drained, the queued refresh can be lost.
+
+## Goal
+
+Remove the backup-phase schema sync from the migration task run critical path while preserving the same eventual metadata refresh target.
+
+## Non-Goals
+
+- Do not add a durable schema-sync request table.
+- Do not add task-run `DATABASE_SYNC` log entries for this path.
+- Do not change post-migration schema sync behavior, changelog updates, revision behavior, or sync-history behavior.
+
+## Design
+
+At the end of `backupData`, replace the blocking `SyncDatabaseSchema` call with `SyncDatabaseAsync`.
+
+Target selection remains unchanged:
+
+- for non-Postgres engines, enqueue `backupDatabase`;
+- for Postgres, enqueue `database`.
+
+The enqueue is intentionally best-effort in HA. This is acceptable because the backup-phase sync is a metadata refresh only. If the async request is lost due to replica shutdown, later periodic sync or manual database sync can repair the metadata.
+
+No task-run database-sync log events are emitted for this path because the actual sync is no longer part of the task run execution. The prior-backup task-run log span should represent backup table creation, not asynchronous metadata refresh.
+
+## Implementation Notes
+
+Keep the existing `if/else` structure at the single call site and replace the synchronous calls with async enqueues:
+
+```go
+if database.Engine != storepb.Engine_POSTGRES {
+ exec.schemaSyncer.SyncDatabaseAsync(backupDatabase)
+} else {
+ exec.schemaSyncer.SyncDatabaseAsync(database)
+}
+```
+
+The existing `SyncDatabaseAsync` method already ignores nil and deleted databases.
+
+## Error Handling
+
+The async enqueue itself does not fail. Sync execution failures are handled by the existing schema syncer path, which records sync failure state on database metadata when the queued sync runs.
+
+No migration task failure should be introduced by the async metadata refresh.
+
+## Testing
+
+Add focused unit coverage for the backup schema sync target behavior:
+
+- Postgres enqueues the source database.
+- Non-Postgres enqueues the backup database.
+- Nil backup database is tolerated by the async enqueue path because `SyncDatabaseAsync` already handles nil.
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/runner/taskrun
+```
+
+For final verification after implementation, follow repository Go workflow: `gofmt`, `golangci-lint run --allow-parallel-runners` until clean, relevant tests, and backend build.