feat(backup): support cross-platform background database backups

This commit is contained in:
CSXFanMeng authored and GitHub committed 2026-09-23 12:29:56 +08:00
1 parent 250e0c0a10
commit 2f960f104c
56 files changed
+4195 -962

No files matched your search

@@ -0,0 +1,54 @@
// @vitest-environment happy-dom
import { createApp, defineComponent, h, nextTick, type App } from "vue";
import { afterEach, expect, it, vi } from "vitest";
import type { SqlFilePreview } from "@/lib/backend/api";
const mocks = vi.hoisted(() => ({
store: {
connections: [],
sqlFileSource: null as { connectionId: string; database: string; filePath?: string; preview?: SqlFilePreview } | null,
},
}));
vi.mock("@/stores/connectionStore", async () => {
const { reactive } = await import("vue");
mocks.store = reactive(mocks.store);
return { useConnectionStore: () => mocks.store };
});
vi.mock("vue-i18n", () => ({ useI18n: () => ({ t: (key: string) => key }) }));
vi.mock("@/composables/useToast", () => ({ useToast: () => ({ toast: vi.fn() }) }));
import { useDialogSources } from "@/composables/useDialogSources";
let app: App | undefined;
afterEach(() => {
app?.unmount();
document.body.innerHTML = "";
});
it("hands prepared Web previews to the dialog, clears them on close, and preserves desktop paths", async () => {
let dialogs!: ReturnType<typeof useDialogSources>;
app = createApp(
defineComponent({
setup() {
dialogs = useDialogSources();
return () => h("div");
},
}),
);
app.mount(document.body.appendChild(document.createElement("div")));
const preview = { fileName: "backup.sql", filePath: "/server/tmp/sql_file/restore-token/backup.sql", preview: "SELECT 1;", sizeBytes: 9, canExecuteWithoutSelectedDatabase: true, cleanupToken: "restore-token" };
mocks.store.sqlFileSource = { connectionId: "mysql", database: "app", preview };
await nextTick();
expect(dialogs.showSqlFileDialog.value).toBe(true);
expect(dialogs.sqlFilePrefillPreview.value).toEqual(preview);
expect(dialogs.sqlFilePrefillFilePath.value).toBe("");
expect(mocks.store.sqlFileSource).toBeNull();
dialogs.showSqlFileDialog.value = false;
await nextTick();
expect(dialogs.sqlFilePrefillPreview.value).toBeUndefined();
mocks.store.sqlFileSource = { connectionId: "mysql", database: "app", filePath: "/local/backup.sql" };
await nextTick();
expect(dialogs.sqlFilePrefillFilePath.value).toBe("/local/backup.sql");
expect(dialogs.sqlFilePrefillPreview.value).toBeUndefined();
});
@@ -1,310 +1,190 @@
import { describe, expect, it, vi } from "vitest";
import type { DatabaseBackupExecutionConfig, DatabaseBackupRun } from "../../lib/backup/scheduledDatabaseBackup";
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { DatabaseBackupRun, DatabaseBackupSchedule } from "../../lib/backup/scheduledDatabaseBackup";
import type { DatabaseBackupSnapshot } from "../../lib/backup/backgroundDatabaseBackup";
const mocks = vi.hoisted(() => ({
connection: { id: "mysql-1", name: "Local MySQL", db_type: "mysql" },
listDatabases: vi.fn(async () => [{ name: "app" }]),
beginSnapshot: vi.fn(async () => ({ sessionId: "snapshot-1" })),
rollbackSnapshot: vi.fn(async () => {}),
deleteFiles: vi.fn(async () => 0),
cancelExport: vi.fn(async () => {}),
clearExportCancellation: vi.fn(async () => {}),
exportDatabase: vi.fn(),
runDatabaseExport: vi.fn(),
command: vi.fn(),
legacySchedules: vi.fn(() => []),
legacyRuns: vi.fn(() => []),
desktop: true,
addTask: vi.fn(),
registerCancel: vi.fn(),
unregisterCancel: vi.fn(),
updateTask: vi.fn(),
markTaskCancelling: vi.fn(),
restoreTaskRunning: vi.fn(),
nextId: 0,
}));
vi.mock("@/lib/backend/api", () => ({
listDatabases: mocks.listDatabases,
beginDatabaseBackupSnapshot: mocks.beginSnapshot,
rollbackManualTransaction: mocks.rollbackSnapshot,
deleteDatabaseBackupFiles: mocks.deleteFiles,
cancelDatabaseExport: mocks.cancelExport,
clearDatabaseExportCancellation: mocks.clearExportCancellation,
}));
vi.mock("@/lib/export/databaseExport", () => ({
buildAllDatabaseExportPlan: () => [{ database: "app", schema: "app", fileStem: "app", displayName: "app" }],
generateDatabaseExportId: () => `run-${++mocks.nextId}`,
runDatabaseExportUntilTerminal: mocks.runDatabaseExport,
}));
vi.mock("@/lib/backend/tauriRuntime", () => ({ isTauriRuntime: () => true }));
vi.mock("@/stores/connectionStore", () => ({
useConnectionStore: () => ({
getConfig: () => mocks.connection,
ensureConnected: vi.fn(async () => {}),
initFromDisk: vi.fn(async () => {}),
}),
cancelTask: vi.fn(),
register: vi.fn(),
unregister: vi.fn(),
}));
vi.mock("vue", async () => ({ ...(await vi.importActual("vue")), onMounted: vi.fn(), onUnmounted: vi.fn() }));
vi.mock("@/lib/backend/api", () => ({ databaseBackupCommand: mocks.command }));
vi.mock("@/lib/backend/debugLog", () => ({ appendDebugLog: vi.fn() }));
vi.mock("@/lib/backend/tauriRuntime", () => ({ isTauriRuntime: () => mocks.desktop }));
vi.mock("@/lib/backup/scheduledDatabaseBackup", () => ({ readDatabaseBackupSchedules: mocks.legacySchedules, readDatabaseBackupRuns: mocks.legacyRuns }));
vi.mock("@/composables/useExportTracker", () => ({
useExportTracker: () => ({
addDatabaseExportTask: mocks.addTask,
registerTaskCancelHandler: mocks.registerCancel,
unregisterTaskCancelHandler: mocks.unregisterCancel,
updateDatabaseExportTask: mocks.updateTask,
markDatabaseExportTaskCancelling: mocks.markTaskCancelling,
restoreDatabaseExportTaskRunning: mocks.restoreTaskRunning,
markDatabaseExportTaskCancelling: mocks.cancelTask,
registerTaskCancelHandler: mocks.register,
unregisterTaskCancelHandler: mocks.unregister,
}),
}));
import { useScheduledDatabaseBackups } from "../useScheduledDatabaseBackups";
let snapshot: DatabaseBackupSnapshot;
function run(status: DatabaseBackupRun["status"] = "running"): DatabaseBackupRun {
return { id: "run-1", scheduleId: "schedule-1", scheduleName: "Daily", connectionId: "mysql", connectionName: "Local", destinationDirectory: "/backups", source: "scheduled", trigger: "manual", status, startedAt: "2026-09-12T00:00:00Z", files: [], progressPercent: 45 };
}
async function create() {
return (await import("../useScheduledDatabaseBackups")).useScheduledDatabaseBackups();
}
const config: DatabaseBackupExecutionConfig = {
connectionId: "mysql-1",
databases: ["app"],
tableFilterMode: "all",
tablePatterns: [],
destinationDirectory: "/backups",
includeStructure: true,
includeData: true,
includeObjects: true,
dropTableIfExists: false,
outputCompression: "none",
};
beforeEach(() => {
vi.resetModules();
vi.clearAllMocks();
mocks.desktop = true;
snapshot = { schedules: [], runs: [], migrated: true, heartbeat: "2026-09-12T00:00:00Z", destinationRoot: null };
mocks.command.mockImplementation(async (command) => (command.action === "snapshot" ? structuredClone(snapshot) : null));
});
describe("useScheduledDatabaseBackups one-shot execution", () => {
it("deletes multiple completed runs and all of their backup files", async () => {
const backup = useScheduledDatabaseBackups();
const firstRun = {
id: "delete-many-first",
scheduleName: "First backup",
connectionId: "mysql-1",
connectionName: "Local MySQL",
destinationDirectory: "/backups",
trigger: "scheduled",
source: "scheduled",
status: "success",
startedAt: "2026-09-08T01:00:00.000Z",
files: [{ displayName: "first.sql", filePath: "/backups/first.sql" }],
} satisfies DatabaseBackupRun;
const secondRun = {
id: "delete-many-second",
scheduleName: "Second backup",
connectionId: "mysql-1",
connectionName: "Local MySQL",
destinationDirectory: "/backups",
trigger: "scheduled",
source: "scheduled",
status: "failed",
startedAt: "2026-09-08T02:00:00.000Z",
files: [{ displayName: "second.sql", filePath: "/backups/second.sql" }],
} satisfies DatabaseBackupRun;
backup.runs.value.push(firstRun, secondRun);
mocks.deleteFiles.mockClear();
try {
await backup.deleteRuns([firstRun.id, secondRun.id]);
expect(mocks.deleteFiles).toHaveBeenCalledWith(["/backups/first.sql", "/backups/second.sql"], ["/backups"]);
expect(backup.runs.value).not.toContainEqual(expect.objectContaining({ id: firstRun.id }));
expect(backup.runs.value).not.toContainEqual(expect.objectContaining({ id: secondRun.id }));
} finally {
backup.runs.value = backup.runs.value.filter((run) => run.id !== firstRun.id && run.id !== secondRun.id);
}
describe("backend-owned scheduled database backups", () => {
it("reconnects to running backups without starting another export", async () => {
snapshot.runs = [run()];
const backups = await create();
await backups.processDueSchedules();
await backups.processDueSchedules();
expect(backups.activeRunIds.has("run-1")).toBe(true);
expect(backups.activeScheduleIds.has("schedule-1")).toBe(true);
expect(mocks.addTask).toHaveBeenCalledTimes(1);
expect(mocks.command.mock.calls.every(([c]) => c.action === "snapshot")).toBe(true);
expect(mocks.updateTask).toHaveBeenLastCalledWith("run-1", expect.objectContaining({ status: "Running", overallPercent: 45 }));
});
it("keeps a shared backup path when deleting one of its history records", async () => {
const backup = useScheduledDatabaseBackups();
const sharedPath = "/backups/before-migration__app.sql";
const firstRun = {
id: "shared-path-first",
scheduleName: "First backup",
connectionId: "mysql-1",
connectionName: "Local MySQL",
trigger: "scheduled",
source: "scheduled",
status: "success",
startedAt: "2026-09-08T01:00:00.000Z",
files: [{ displayName: "first.sql", filePath: sharedPath }],
} satisfies DatabaseBackupRun;
const secondRun = { ...firstRun, id: "shared-path-second", startedAt: "2026-09-08T02:00:00.000Z" } satisfies DatabaseBackupRun;
backup.runs.value.push(firstRun, secondRun);
mocks.deleteFiles.mockClear();
try {
await backup.deleteRun(firstRun.id);
expect(mocks.deleteFiles).not.toHaveBeenCalled();
expect(backup.runs.value).not.toContainEqual(expect.objectContaining({ id: firstRun.id }));
expect(backup.runs.value).toContainEqual(expect.objectContaining({ id: secondRun.id }));
} finally {
backup.runs.value = backup.runs.value.filter((run) => run.id !== firstRun.id && run.id !== secondRun.id);
}
it("reflects completion from a worker that runs independently of the UI", async () => {
snapshot.runs = [run()];
const backups = await create();
await backups.processDueSchedules();
snapshot.runs[0] = { ...run("success"), progressPercent: 100 };
await backups.processDueSchedules();
expect(backups.activeRunIds.size).toBe(0);
expect(backups.activeScheduleIds.size).toBe(0);
expect(mocks.updateTask).toHaveBeenLastCalledWith("run-1", expect.objectContaining({ status: "Done", overallPercent: 100 }));
});
it("executes one-shot backups through the shared exporter without a schedule", async () => {
mocks.runDatabaseExport.mockImplementationOnce(async (_request: unknown, onProgress: (progress: unknown) => void) => {
onProgress({ status: "Done", objectIndex: 1, totalObjects: 1, currentObject: "app" });
return { status: "Done", objectIndex: 1, totalObjects: 1, currentObject: "app" };
});
const backup = useScheduledDatabaseBackups();
const scheduleCountBefore = backup.schedules.value.length;
const run = await backup.runOneShot(config, "One-time backup");
expect(run).toEqual(expect.objectContaining({ status: "success", source: "one-shot", trigger: "manual", scheduleId: undefined }));
expect(run).not.toHaveProperty("nextRunAt");
expect(backup.schedules.value).toHaveLength(scheduleCountBefore);
expect(mocks.runDatabaseExport).toHaveBeenCalledWith(expect.objectContaining({ preventOverwrite: true }), expect.any(Function));
expect(mocks.addTask).toHaveBeenCalledWith(expect.any(String), "One-time backup", "/backups", "manual");
it("waits for durable cancellation acceptance before showing cancellation", async () => {
snapshot.runs = [run()];
const backups = await create();
await backups.processDueSchedules();
mocks.command.mockRejectedValueOnce(new Error("offline"));
await expect(backups.cancelRun("run-1")).rejects.toThrow("offline");
expect(backups.cancellingRunIds.size).toBe(0);
mocks.command.mockResolvedValueOnce(true);
expect(await backups.cancelRun("run-1")).toBe(true);
expect(backups.cancellingRunIds.has("run-1")).toBe(true);
expect(mocks.command).toHaveBeenLastCalledWith({ action: "cancel", id: "run-1" });
});
it("rejects a repeated one-shot when its custom file name resolves to an existing path", async () => {
mocks.runDatabaseExport.mockImplementation(async (_request: unknown, onProgress: (progress: unknown) => void) => {
const progress = { status: "Done", objectIndex: 1, totalObjects: 1, currentObject: "app" };
onProgress(progress);
return progress;
});
const backup = useScheduledDatabaseBackups();
const customConfig = { ...config, fileNamePattern: "before-migration" };
let runIds: string[] = [];
try {
const firstRun = await backup.runOneShot(customConfig, "One-time backup");
runIds = [firstRun?.id].filter((id): id is string => Boolean(id));
const exportCallCount = mocks.runDatabaseExport.mock.calls.length;
const secondRun = await backup.runOneShot(customConfig, "One-time backup");
if (secondRun?.id) runIds.push(secondRun.id);
expect(firstRun).toEqual(expect.objectContaining({ status: "success" }));
expect(secondRun).toEqual(expect.objectContaining({ status: "failed", files: [] }));
expect(secondRun?.error).toContain("already used by another run");
expect(mocks.runDatabaseExport).toHaveBeenCalledTimes(exportCallCount);
} finally {
const ids = new Set(runIds);
backup.runs.value = backup.runs.value.filter((run) => !ids.has(run.id));
}
it("deletes by server record IDs, never by client supplied file paths", async () => {
snapshot.runs = [run("success")];
const backups = await create();
await backups.processDueSchedules();
await backups.deleteRuns(["run-1"]);
expect(mocks.command).toHaveBeenCalledWith({ action: "deleteRuns", ids: ["run-1"] });
});
it("does not delete a pre-existing file when the exporter rejects overwrite", async () => {
mocks.runDatabaseExport.mockRejectedValueOnce(new Error("Backup file already exists: /backups/before-migration__app.sql"));
const backup = useScheduledDatabaseBackups();
const result = await backup.runOneShot({ ...config, fileNamePattern: "before-migration" }, "One-time backup");
expect(result).toEqual(expect.objectContaining({ status: "failed", files: [] }));
expect(mocks.deleteFiles).not.toHaveBeenCalled();
it("preserves optimistic concurrency timestamps and saved time zones", async () => {
const schedule = { id: "schedule-1", name: "Daily", timeZone: "Asia/Tokyo", updatedAt: "2026-09-01T00:00:00Z" } as DatabaseBackupSchedule;
const backups = await create();
await backups.saveSchedule(schedule);
expect(mocks.command).toHaveBeenCalledWith({ action: "save", schedule });
});
it("prevents a second one-shot while one is already running", async () => {
const backup = useScheduledDatabaseBackups();
const activeRun = {
id: "active-one-shot",
scheduleName: "One-time backup",
connectionId: "mysql-1",
connectionName: "Local MySQL",
trigger: "manual",
source: "one-shot",
status: "running",
startedAt: new Date().toISOString(),
files: [],
} satisfies DatabaseBackupRun;
backup.runs.value.push(activeRun);
backup.activeRunIds.add(activeRun.id);
const exportCallCount = mocks.runDatabaseExport.mock.calls.length;
try {
expect(await backup.runOneShot(config, "One-time backup")).toBeNull();
expect(mocks.runDatabaseExport).toHaveBeenCalledTimes(exportCallCount);
} finally {
backup.activeRunIds.delete(activeRun.id);
backup.runs.value = backup.runs.value.filter((run: DatabaseBackupRun) => run.id !== activeRun.id);
}
it("does not overwrite local state after a failed save", async () => {
snapshot.schedules = [{ id: "schedule-1", name: "Original" } as DatabaseBackupSchedule];
const backups = await create();
await backups.processDueSchedules();
mocks.command.mockRejectedValueOnce(new Error("schedule changed"));
await expect(backups.saveSchedule({ ...snapshot.schedules[0], name: "New" })).rejects.toThrow("schedule changed");
expect(backups.schedules.value[0].name).toBe("Original");
});
it("cancels an active one-shot through the shared export cancellation path", async () => {
mocks.cancelExport.mockClear();
mocks.deleteFiles.mockClear();
let resolveExport!: (progress: { status: "Cancelled"; objectIndex: number; totalObjects: number; currentObject: string }) => void;
mocks.runDatabaseExport.mockImplementationOnce(
(_request: unknown, onProgress: (progress: unknown) => void) =>
new Promise((resolve) => {
resolveExport = (progress) => {
onProgress(progress);
resolve(progress);
};
}),
);
const backup = useScheduledDatabaseBackups();
const pendingRun = backup.runOneShot(config, "One-time backup");
await new Promise((resolve) => setTimeout(resolve, 0));
const activeRunId = [...backup.activeRunIds][0];
expect(activeRunId).toBeTruthy();
await backup.cancelRun(activeRunId!);
expect(mocks.cancelExport).toHaveBeenCalledWith(activeRunId);
expect(mocks.cancelExport).toHaveBeenCalledWith(`${activeRunId}-1`);
expect(mocks.markTaskCancelling).toHaveBeenCalledWith(activeRunId);
expect(backup.cancellingRunIds.has(activeRunId!)).toBe(true);
await backup.cancelRun(activeRunId!);
expect(mocks.cancelExport).toHaveBeenCalledTimes(2);
resolveExport({ status: "Cancelled", objectIndex: 0, totalObjects: 1, currentObject: "app" });
const finishedRun = await pendingRun;
expect(finishedRun).toEqual(expect.objectContaining({ status: "cancelled", source: "one-shot", files: [] }));
expect(mocks.deleteFiles).toHaveBeenCalledWith([expect.stringContaining(activeRunId!)], ["/backups"]);
expect(backup.runs.value.find((run) => run.id === activeRunId)).toEqual(expect.objectContaining({ status: "cancelled", files: [] }));
expect(backup.cancellingRunIds.has(activeRunId!)).toBe(false);
});
it("stops after cancelling during database discovery without creating a snapshot", async () => {
mocks.beginSnapshot.mockClear();
mocks.cancelExport.mockClear();
let resolveDatabases!: (databases: Array<{ name: string }>) => void;
mocks.listDatabases.mockImplementationOnce(
it("reloads after a save even when an older poll finishes later", async () => {
const backups = await create();
const oldSnapshot = structuredClone(snapshot);
let release!: (value: DatabaseBackupSnapshot) => void;
mocks.command.mockImplementationOnce(
() =>
new Promise((resolve) => {
resolveDatabases = resolve;
new Promise<DatabaseBackupSnapshot>((resolve) => {
release = resolve;
}),
);
const backup = useScheduledDatabaseBackups();
const pendingRun = backup.runOneShot(config, "One-time backup");
await new Promise((resolve) => setTimeout(resolve, 0));
const activeRunId = [...backup.activeRunIds][0];
expect(activeRunId).toBeTruthy();
await backup.cancelRun(activeRunId!);
expect(mocks.cancelExport).toHaveBeenCalledWith(activeRunId);
resolveDatabases([{ name: "app" }]);
const finishedRun = await pendingRun;
expect(finishedRun).toEqual(expect.objectContaining({ status: "cancelled", files: [] }));
expect(mocks.beginSnapshot).not.toHaveBeenCalled();
const polling = backups.processDueSchedules();
const schedule = { id: "schedule-1", name: "New", timeZone: "Asia/Shanghai" } as DatabaseBackupSchedule;
mocks.command.mockImplementation(async (command) => {
if (command.action === "save") {
snapshot.schedules = [schedule];
return schedule;
}
return structuredClone(snapshot);
});
const saving = backups.saveSchedule(schedule);
release(oldSnapshot);
await polling;
await saving;
expect(backups.schedules.value).toEqual([schedule]);
expect(mocks.command.mock.calls.filter(([command]) => command.action === "snapshot")).toHaveLength(2);
});
it("signals the backup run while snapshot creation is pending", async () => {
mocks.beginSnapshot.mockClear();
mocks.cancelExport.mockClear();
let resolveSnapshot!: (snapshot: { sessionId: string }) => void;
mocks.beginSnapshot.mockImplementationOnce(
it("does not lose a newly queued run to a stale in-flight snapshot", async () => {
const backups = await create();
const oldSnapshot = structuredClone(snapshot);
let release!: (value: DatabaseBackupSnapshot) => void;
mocks.command.mockImplementationOnce(
() =>
new Promise((resolve) => {
resolveSnapshot = resolve;
new Promise<DatabaseBackupSnapshot>((resolve) => {
release = resolve;
}),
);
const polling = backups.processDueSchedules();
mocks.command.mockImplementation(async (command) => {
if (command.action === "run") {
snapshot.runs = [run("success")];
return run();
}
return structuredClone(snapshot);
});
const running = backups.runSchedule("schedule-1");
release(oldSnapshot);
await polling;
expect(await running).toEqual(run("success"));
});
const backup = useScheduledDatabaseBackups();
const pendingRun = backup.runOneShot(config, "One-time backup");
await new Promise((resolve) => setTimeout(resolve, 0));
const activeRunId = [...backup.activeRunIds][0];
expect(activeRunId).toBeTruthy();
expect(mocks.beginSnapshot).toHaveBeenCalledWith("mysql-1", "app", activeRunId);
it("marks migration only after the backend accepts it", async () => {
snapshot.migrated = false;
const backups = await create();
mocks.command.mockImplementation(async (command) => {
if (command.action === "migrate") throw new Error("database locked");
return structuredClone(snapshot);
});
await expect(backups.processDueSchedules()).rejects.toThrow("database locked");
expect(mocks.legacySchedules).toHaveBeenCalledTimes(1);
expect(backups.error.value).toBe("database locked");
mocks.command.mockImplementation(async (command) => {
if (command.action === "migrate") {
snapshot.migrated = true;
return null;
}
return structuredClone(snapshot);
});
await backups.processDueSchedules();
await backups.processDueSchedules();
expect(mocks.legacySchedules).toHaveBeenCalledTimes(2);
});
await backup.cancelRun(activeRunId!);
expect(mocks.cancelExport).toHaveBeenCalledWith(activeRunId);
resolveSnapshot({ sessionId: "snapshot-pending" });
const finishedRun = await pendingRun;
expect(finishedRun).toEqual(expect.objectContaining({ status: "cancelled", files: [] }));
expect(mocks.rollbackSnapshot).toHaveBeenCalledWith("snapshot-pending");
expect(mocks.clearExportCancellation).toHaveBeenCalledWith(activeRunId);
it("never migrates browser-local paths into a server", async () => {
mocks.desktop = false;
snapshot.migrated = false;
const backups = await create();
await backups.processDueSchedules();
expect(mocks.legacySchedules).not.toHaveBeenCalled();
expect(mocks.legacyRuns).not.toHaveBeenCalled();
expect(mocks.command).toHaveBeenCalledWith({ action: "migrate", migration: { schedules: [], runs: [] } });
});
});