Add migrations_file manifest option to avoid JSON escaping pain

MajorTal · claude · MajorTal · commit 45a8100a70bd · 2026-03-18T11:23:44.000+01:00
When SQL contains JSONB literals, escaping them inside a JSON string
field is a nightmare. migrations_file reads SQL from a .sql file on
disk instead, resolved relative to the manifest directory.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/cli/lib/deploy.mjs b/cli/lib/deploy.mjs
@@ -1,7 +1,7 @@
 import { readFileSync } from "fs";
 import { dirname, resolve } from "path";
 import { API, allowanceAuthHeaders, findProject } from "./config.mjs";
-import { resolveFilePathsInManifest } from "./manifest.mjs";
+import { resolveFilePathsInManifest, resolveMigrationsFile } from "./manifest.mjs";
 
 const HELP = `run402 deploy — Deploy to an existing project on Run402
 
@@ -17,7 +17,8 @@ Options:
 Manifest format (JSON):
   {
     "project_id": "prj_...",
-    "migrations": "CREATE TABLE items (id serial PRIMARY KEY, title text NOT NULL, done boolean DEFAULT false)",
+    "migrations": "CREATE TABLE items (...)",
+    "migrations_file": "setup.sql",
     "rls": {
       "template": "public_read_write",
       "tables": [{ "table": "items" }]
@@ -37,6 +38,14 @@ Manifest format (JSON):
   project_id is required (provision first with 'run402 provision').
   All other fields are optional.
 
+  Migrations can be inline or read from a file:
+    "migrations": "CREATE TABLE ..."              ← inline SQL
+    "migrations_file": "setup.sql"                ← read from disk
+  Use migrations_file when your SQL contains JSONB literals or other
+  characters that are painful to escape inside a JSON string.
+  Paths are resolved relative to the manifest file's directory.
+  If both are present, migrations_file wins.
+
   Files can use either inline "data" or a local "path":
     { "file": "index.html", "data": "<html>...</html>" }   ← inline content
     { "file": "style.css",  "path": "./dist/style.css" }   ← read from disk
@@ -83,7 +92,11 @@ export async function run(args) {
 
   const raw = opts.manifest ? readFileSync(opts.manifest, "utf-8") : await readStdin();
   const manifest = JSON.parse(raw);
-  if (opts.manifest) resolveFilePathsInManifest(manifest, dirname(resolve(opts.manifest)));
+  if (opts.manifest) {
+    const baseDir = dirname(resolve(opts.manifest));
+    resolveMigrationsFile(manifest, baseDir);
+    resolveFilePathsInManifest(manifest, baseDir);
+  }
 
   // --project flag overrides manifest's project_id
   if (opts.project) manifest.project_id = opts.project;
diff --git a/cli/lib/manifest.mjs b/cli/lib/manifest.mjs
@@ -6,6 +6,23 @@ const TEXT_EXTS = new Set([
   ".json", ".svg", ".xml", ".txt", ".md", ".yaml", ".yml", ".toml", ".csv",
 ]);
 
+/**
+ * If the manifest has `migrations_file` instead of (or in addition to) `migrations`,
+ * read the SQL from that file path and set `migrations` to its contents.
+ * `migrations_file` is resolved relative to `baseDir`.
+ *
+ * @param {object} manifest  Parsed manifest JSON (mutated in place)
+ * @param {string} baseDir   Directory to resolve relative paths from
+ * @returns {object}         The same manifest object
+ */
+export function resolveMigrationsFile(manifest, baseDir) {
+  if (!manifest.migrations_file) return manifest;
+  const abs = resolve(baseDir, manifest.migrations_file);
+  manifest.migrations = readFileSync(abs, "utf-8");
+  delete manifest.migrations_file;
+  return manifest;
+}
+
 /**
  * Resolve `path` fields in a manifest's files array.
  *
diff --git a/cli/lib/manifest.test.mjs b/cli/lib/manifest.test.mjs
@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { resolveFilePathsInManifest } from "./manifest.mjs";
+import { resolveFilePathsInManifest, resolveMigrationsFile } from "./manifest.mjs";
 
 let tempDir;
 
@@ -13,6 +13,7 @@ before(() => {
   writeFileSync(join(tempDir, "index.html"), "<!DOCTYPE html><html><body>Hello</body></html>");
   writeFileSync(join(tempDir, "style.css"), "body { margin: 0; }");
   writeFileSync(join(tempDir, "logo.png"), Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])); // PNG header
+  writeFileSync(join(tempDir, "setup.sql"), "CREATE TABLE items (id serial PRIMARY KEY, data jsonb);\nINSERT INTO items (data) VALUES ('[{\"x\":0.5}]');");
 });
 
 after(() => {
@@ -88,3 +89,40 @@ describe("resolveFilePathsInManifest", () => {
     );
   });
 });
+
+describe("resolveMigrationsFile", () => {
+  it("reads SQL from migrations_file and sets migrations", () => {
+    const manifest = { migrations_file: "setup.sql" };
+    resolveMigrationsFile(manifest, tempDir);
+    assert.ok(manifest.migrations.includes("CREATE TABLE items"));
+    assert.ok(manifest.migrations.includes('[{"x":0.5}]'), "should preserve JSON literals without escaping issues");
+    assert.equal(manifest.migrations_file, undefined, "migrations_file should be removed");
+  });
+
+  it("overwrites inline migrations when migrations_file is present", () => {
+    const manifest = { migrations: "SELECT 1", migrations_file: "setup.sql" };
+    resolveMigrationsFile(manifest, tempDir);
+    assert.ok(manifest.migrations.includes("CREATE TABLE items"));
+    assert.equal(manifest.migrations_file, undefined);
+  });
+
+  it("leaves manifest untouched when no migrations_file", () => {
+    const manifest = { migrations: "SELECT 1" };
+    resolveMigrationsFile(manifest, tempDir);
+    assert.equal(manifest.migrations, "SELECT 1");
+  });
+
+  it("handles manifest with neither migrations nor migrations_file", () => {
+    const manifest = { files: [] };
+    resolveMigrationsFile(manifest, tempDir);
+    assert.equal(manifest.migrations, undefined);
+  });
+
+  it("throws on missing migrations file", () => {
+    const manifest = { migrations_file: "does-not-exist.sql" };
+    assert.throws(
+      () => resolveMigrationsFile(manifest, tempDir),
+      /ENOENT/,
+    );
+  });
+});
