Skip to content

The open-source app everyone uses to manage agents at work

fix(worktree): disable automatic database backups (#10520)

Dotta7cfb655f60a2
diff --git a/cli/src/__tests__/worktree.test.ts b/cli/src/__tests__/worktree.test.ts
index b75699caef..bbd055ea1e 100644
--- a/cli/src/__tests__/worktree.test.ts
+++ b/cli/src/__tests__/worktree.test.ts
@@ -276,6 +276,7 @@ describe("worktree helpers", () => {
path.resolve("/tmp/paperclip-worktrees", "instances", "feature-worktree-support", "db"),
);
expect(config.database.embeddedPostgresPort).toBe(54339);
+ expect(config.database.backup.enabled).toBe(false);
expect(config.server.port).toBe(3110);
expect(config.auth.publicBaseUrl).toBe("http://127.0.0.1:3110/");
expect(config.storage.localDisk.baseDir).toBe(
@@ -289,6 +290,7 @@ describe("worktree helpers", () => {
expect(env.PAPERCLIP_HOME).toBe(path.resolve("/tmp/paperclip-worktrees"));
expect(env.PAPERCLIP_INSTANCE_ID).toBe("feature-worktree-support");
expect(env.PAPERCLIP_IN_WORKTREE).toBe("true");
+ expect(env.PAPERCLIP_DB_BACKUP_ENABLED).toBe("false");
expect(env.PAPERCLIP_WORKTREE_NAME).toBe("feature-worktree-support");
expect(env.PAPERCLIP_WORKTREE_COLOR).toBe("#3abf7a");
expect(formatShellExports(env)).toContain("export PAPERCLIP_INSTANCE_ID='feature-worktree-support'");
diff --git a/cli/src/commands/worktree-lib.ts b/cli/src/commands/worktree-lib.ts
index 2be4528e50..0d1d60f65e 100644
--- a/cli/src/commands/worktree-lib.ts
+++ b/cli/src/commands/worktree-lib.ts
@@ -197,7 +197,7 @@ export function buildWorktreeConfig(input: {
embeddedPostgresDataDir: paths.embeddedPostgresDataDir,
embeddedPostgresPort: databasePort,
backup: {
- enabled: source?.database.backup.enabled ?? true,
+ enabled: false,
intervalMinutes: source?.database.backup.intervalMinutes ?? 60,
retentionDays: source?.database.backup.retentionDays ?? 30,
dir: paths.backupDir,
@@ -258,6 +258,7 @@ export function buildWorktreeEnvEntries(
PAPERCLIP_CONFIG: paths.configPath,
PAPERCLIP_CONTEXT: paths.contextPath,
PAPERCLIP_IN_WORKTREE: "true",
+ PAPERCLIP_DB_BACKUP_ENABLED: "false",
...(branding?.name ? { PAPERCLIP_WORKTREE_NAME: branding.name } : {}),
...(branding?.color ? { PAPERCLIP_WORKTREE_COLOR: branding.color } : {}),
};
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index c929036915..0e0fddf80f 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -355,6 +355,7 @@ This command:
- creates an isolated instance under `~/.paperclip-worktrees/instances/<worktree-id>/`
- when run inside a linked git worktree, mirrors the effective git hooks into that worktree's private git dir
- picks a free app port and embedded PostgreSQL port
+- disables automatic database backups for the isolated instance
- by default seeds the isolated DB in `minimal` mode from the current effective Paperclip instance/config (repo-local worktree config when present, otherwise the default instance) via a logical SQL snapshot
Seed modes:
@@ -374,6 +375,7 @@ Provisioned git worktrees also pause seeded routines that still have enabled sch
That repo-local env also sets:
- `PAPERCLIP_IN_WORKTREE=true`
+- `PAPERCLIP_DB_BACKUP_ENABLED=false`
- `PAPERCLIP_WORKTREE_NAME=<worktree-name>`
- `PAPERCLIP_WORKTREE_COLOR=<hex-color>`
@@ -655,6 +657,11 @@ schemas. Defaults:
- retain 30 days
- backup dir: `~/.paperclip/instances/default/data/backups`
+Automatic backups are disabled for isolated worktree instances created with
+`paperclipai worktree init` or `paperclipai worktree:make`. Existing worktree
+configs are migrated to the disabled setting when their server next starts. The
+main/default instance keeps the normal enabled-by-default behavior.
+
Configure these in:
```sh
diff --git a/server/src/__tests__/worktree-config.test.ts b/server/src/__tests__/worktree-config.test.ts
index ea1a4c8764..1ea6859f99 100644
--- a/server/src/__tests__/worktree-config.test.ts
+++ b/server/src/__tests__/worktree-config.test.ts
@@ -101,6 +101,10 @@ function buildIsolatedConfig(instanceRoot: string, serverPort: number, databaseP
database: {
...config.database,
embeddedPostgresPort: databasePort,
+ backup: {
+ ...config.database.backup,
+ enabled: false,
+ },
},
server: {
...config.server,
@@ -155,6 +159,7 @@ describe("worktree config repair", () => {
const instanceRoot = path.join(isolatedHome, "instances", "pap-884-ai-commits-component");
expect(repairedConfig.database.embeddedPostgresDataDir).toBe(path.join(instanceRoot, "db"));
+ expect(repairedConfig.database.backup.enabled).toBe(false);
expect(repairedConfig.database.backup.dir).toBe(path.join(instanceRoot, "data", "backups"));
expect(repairedConfig.logging.logDir).toBe(path.join(instanceRoot, "logs"));
expect(repairedConfig.storage.localDisk.baseDir).toBe(path.join(instanceRoot, "data", "storage"));
@@ -163,10 +168,64 @@ describe("worktree config repair", () => {
expect(repairedEnv).toContain('PAPERCLIP_INSTANCE_ID="pap-884-ai-commits-component"');
expect(repairedEnv).toContain(`PAPERCLIP_CONFIG=${JSON.stringify(await fs.realpath(configPath))}`);
expect(repairedEnv).toContain(`PAPERCLIP_CONTEXT=${JSON.stringify(path.join(isolatedHome, "context.json"))}`);
- expect(repairedEnv).toContain('PAPERCLIP_AGENT_JWT_SECRET="shared-secret"');
+ expect(repairedEnv).toContain('PAPERCLIP_DB_BACKUP_ENABLED="false"');
+ expect(repairedEnv).toContain("PAPERCLIP_AGENT_JWT_SECRET=shared-secret");
expect(process.env.PAPERCLIP_HOME).toBe(isolatedHome);
expect(process.env.PORT).toBe("3101");
expect(process.env.PAPERCLIP_INSTANCE_ID).toBe("pap-884-ai-commits-component");
+ expect(process.env.PAPERCLIP_DB_BACKUP_ENABLED).toBe("false");
+ });
+
+ it("disables backups in an otherwise isolated existing worktree config", async () => {
+ const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-backup-migration-"));
+ const worktreeRoot = path.join(tempRoot, "disable-worktree-backups");
+ const paperclipDir = path.join(worktreeRoot, ".paperclip");
+ const configPath = path.join(paperclipDir, "config.json");
+ const envPath = path.join(paperclipDir, ".env");
+ const isolatedHome = path.join(tempRoot, ".paperclip-worktrees");
+ const instanceRoot = path.join(isolatedHome, "instances", "disable-worktree-backups");
+
+ await fs.mkdir(paperclipDir, { recursive: true });
+ const legacyIsolatedConfig = buildIsolatedConfig(instanceRoot, 3110, 54339);
+ legacyIsolatedConfig.database.backup.enabled = true;
+ await fs.writeFile(configPath, JSON.stringify(legacyIsolatedConfig, null, 2) + "\n", "utf8");
+ await fs.writeFile(
+ envPath,
+ [
+ "# Paperclip environment variables",
+ "# Keep this operator note during repair",
+ `PAPERCLIP_HOME=${JSON.stringify(isolatedHome)}`,
+ 'PAPERCLIP_INSTANCE_ID="disable-worktree-backups"',
+ `PAPERCLIP_CONFIG=${JSON.stringify(configPath)}`,
+ 'PAPERCLIP_DB_BACKUP_ENABLED="true" # managed worktree policy',
+ 'PAPERCLIP_IN_WORKTREE="true"',
+ 'PAPERCLIP_WORKTREE_NAME="disable-worktree-backups"',
+ "# Keep this trailing note too",
+ "",
+ ].join("\n"),
+ "utf8",
+ );
+
+ process.chdir(worktreeRoot);
+ process.env.PAPERCLIP_HOME = isolatedHome;
+ process.env.PAPERCLIP_INSTANCE_ID = "disable-worktree-backups";
+ process.env.PAPERCLIP_CONFIG = configPath;
+ process.env.PAPERCLIP_DB_BACKUP_ENABLED = "true";
+ process.env.PAPERCLIP_IN_WORKTREE = "true";
+ process.env.PAPERCLIP_WORKTREE_NAME = "disable-worktree-backups";
+
+ const result = maybeRepairLegacyWorktreeConfigAndEnvFiles();
+ const repairedConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+ const repairedEnv = await fs.readFile(envPath, "utf8");
+
+ expect(result).toEqual({ repairedConfig: true, repairedEnv: true });
+ expect(repairedConfig.database.backup.enabled).toBe(false);
+ expect(repairedEnv).toContain(
+ 'PAPERCLIP_DB_BACKUP_ENABLED="false" # managed worktree policy',
+ );
+ expect(repairedEnv).toContain("# Keep this operator note during repair");
+ expect(repairedEnv).toContain("# Keep this trailing note too");
+ expect(process.env.PAPERCLIP_DB_BACKUP_ENABLED).toBe("false");
});
it("preserves an externally supplied PORT while repairing worktree config", async () => {
@@ -601,7 +660,7 @@ describe("worktree config repair", () => {
expect(result).toEqual({
repairedConfig: true,
- repairedEnv: false,
+ repairedEnv: true,
});
expect(repairedConfig.database.embeddedPostgresDataDir).toBe(path.join(stableInstanceRoot, "db"));
expect(repairedConfig.database.backup.dir).toBe(path.join(stableInstanceRoot, "data", "backups"));
@@ -611,6 +670,7 @@ describe("worktree config repair", () => {
path.join(stableInstanceRoot, "secrets", "master.key"),
);
expect(repairedEnv).toContain(`PAPERCLIP_HOME=${JSON.stringify(isolatedHome)}`);
+ expect(repairedEnv).toContain('PAPERCLIP_DB_BACKUP_ENABLED="false"');
expect(repairedEnv).not.toContain(`PAPERCLIP_HOME=${JSON.stringify(transientHome)}`);
expect(process.env.PAPERCLIP_HOME).toBe(isolatedHome);
});
diff --git a/server/src/worktree-config.ts b/server/src/worktree-config.ts
index dc5d620528..de8d824c18 100644
--- a/server/src/worktree-config.ts
+++ b/server/src/worktree-config.ts
@@ -85,6 +85,64 @@ function formatEnvEntries(entries: Record<string, string>): string {
].join("\n");
}
+function trailingEnvComment(rawValue: string): string {
+ let quote: "\"" | "'" | null = null;
+ let escaped = false;
+
+ for (let index = 0; index < rawValue.length; index += 1) {
+ const character = rawValue[index];
+ if (escaped) {
+ escaped = false;
+ continue;
+ }
+ if (quote === "\"" && character === "\\") {
+ escaped = true;
+ continue;
+ }
+ if (quote !== null) {
+ if (character === quote) quote = null;
+ continue;
+ }
+ if (character === "\"" || character === "'") {
+ quote = character;
+ continue;
+ }
+ if (character !== "#" || index === 0 || !/\s/.test(rawValue[index - 1] ?? "")) continue;
+
+ let commentStart = index;
+ while (commentStart > 0 && /\s/.test(rawValue[commentStart - 1] ?? "")) {
+ commentStart -= 1;
+ }
+ return rawValue.slice(commentStart);
+ }
+
+ return "";
+}
+
+function updateEnvFileContents(contents: string, entries: Record<string, string>): string {
+ const newline = contents.includes("\r\n") ? "\r\n" : "\n";
+ const missingEntries = new Map(Object.entries(entries));
+ const lines = contents.split(/\r?\n/).map((rawLine) => {
+ const match = rawLine.match(/^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(\s*=\s*)(.*)$/);
+ if (!match) return rawLine;
+
+ const [, prefix, key, separator, rawValue] = match;
+ const value = entries[key];
+ if (value === undefined) return rawLine;
+
+ missingEntries.delete(key);
+ return `${prefix}${key}${separator}${JSON.stringify(value)}${trailingEnvComment(rawValue)}`;
+ });
+
+ const insertionIndex = lines.at(-1) === "" ? lines.length - 1 : lines.length;
+ lines.splice(
+ insertionIndex,
+ 0,
+ ...Array.from(missingEntries, ([key, value]) => `${key}=${JSON.stringify(value)}`),
+ );
+ return lines.join(newline);
+}
+
function isPathInside(candidatePath: string, rootPath: string): boolean {
const candidate = path.resolve(candidatePath);
const root = path.resolve(rootPath);
@@ -355,6 +413,7 @@ function buildIsolatedWorktreeConfig(
embeddedPostgresPort: databasePort ?? config.database.embeddedPostgresPort,
backup: {
...config.database.backup,
+ enabled: false,
dir: context.backupDir,
},
}
@@ -399,6 +458,9 @@ function needsWorktreeConfigRepair(
context: WorktreeRuntimeContext,
): boolean {
if (config.database.mode === "embedded-postgres") {
+ if (config.database.backup.enabled) {
+ return true;
+ }
if (!isPathInside(config.database.embeddedPostgresDataDir, context.instanceRoot)) {
return true;
}
@@ -562,23 +624,32 @@ export function maybeRepairLegacyWorktreeConfigAndEnvFiles(): {
}
const existingEnvEntries = readEnvEntries(context.envPath);
- const desiredEnvEntries: Record<string, string> = {
- ...existingEnvEntries,
+ const managedEnvEntries: Record<string, string> = {
PAPERCLIP_HOME: context.homeDir,
PAPERCLIP_INSTANCE_ID: context.instanceId,
PAPERCLIP_CONFIG: context.configPath,
PAPERCLIP_CONTEXT: context.contextPath,
PAPERCLIP_IN_WORKTREE: "true",
+ PAPERCLIP_DB_BACKUP_ENABLED: "false",
PAPERCLIP_WORKTREE_NAME: context.worktreeName,
};
- const repairedEnv = Object.entries(desiredEnvEntries).some(
+ process.env.PAPERCLIP_DB_BACKUP_ENABLED = "false";
+
+ const repairedEnv = Object.entries(managedEnvEntries).some(
([key, value]) => existingEnvEntries[key] !== value,
);
if (repairedEnv) {
fs.mkdirSync(path.dirname(context.envPath), { recursive: true });
- fs.writeFileSync(context.envPath, formatEnvEntries(desiredEnvEntries), { mode: 0o600 });
+ const existingContents = fs.existsSync(context.envPath)
+ ? fs.readFileSync(context.envPath, "utf8")
+ : null;
+ const repairedContents =
+ existingContents === null
+ ? formatEnvEntries(managedEnvEntries)
+ : updateEnvFileContents(existingContents, managedEnvEntries);
+ fs.writeFileSync(context.envPath, repairedContents, { mode: 0o600 });
}
return { repairedConfig, repairedEnv };