@batadata/cli 0.2.11 → 0.2.13

package/README.md

@@ -103,6 +103,7 @@ flag always wins**, so linking never silently overrides an intentional request:
 | `db branch create` / `db branch delete` | Manage branches |
 | `db branch checkout <name-or-id>` | Pin a branch into the directory's link |
 | `db studio` | Open the table browser in your browser |
+| `studio` | Run Turbine Studio locally against a branch: a local web UI (`npx turbine-orm studio`) over a direct TCP connection, nothing hosted. Wakes the compute first. Read-only by default; PII redaction is turbine's UI feature, not a BataDB server control (`--project`, `--branch`, `--port`) |
 | `restore points` | List recovery points and the PITR window (see [Point-in-time restore](#point-in-time-restore-pitr)) |
 | `restore create` | Restore a branch to a timestamp/LSN as a **new** branch |
 | `schema check <file>` | Check a proposed schema change against live query traffic |

package/dist/commands/import.js

@@ -859,8 +859,9 @@ export async function importDb(args) {
     }
     if (namedHits.length > 0 && !jsonMode) {
         warn(`Source contains ${namedHits.join(", ")}, which shares a name with BataDB's seeded ` +
-            'platform scaffolding on the target. The restore will likely fail with "relation already ' +
-            'exists" — rename or exclude it on the source to migrate cleanly.');
+            "platform scaffolding. On a freshly created target the seeded copy is dropped so the " +
+            "source's version restores as real data; importing into an existing --project target " +
+            'will likely fail with "relation already exists".');
     }
     // ── Phase 2: check pg_dump AND psql are new enough ──────────────────────────
     // BOTH matter: pg_dump can't dump a newer server than itself, and psql must be
@@ -1072,6 +1073,27 @@ export async function importDb(args) {
     const strandedHintJson = "The target project was left in place (NOT deleted) for diagnosis/retry — re-run with " +
         `--project ${targetProjectId} --yes after fixing` +
         (created ? `, or remove it with: bata projects delete ${targetProjectId} --yes.` : ".");
+    // A freshly CREATED target's named scaffolding (public.health_check + its
+    // sequence) is disposable furniture — but the SOURCE may carry same-named
+    // tables (always true migrating FROM another BataDB, where provisioning
+    // seeded them too). Doctrine says source objects are real data and must
+    // restore + verify normally, so drop the target's seeded copies first;
+    // otherwise the restore is GUARANTEED to die on "already exists". Never
+    // touched on a --project target (created === false): its objects may be the
+    // user's own data, and the old collide-loudly behavior stays.
+    if (created && namedHits.length > 0) {
+        phase("Dropping seeded scaffolding the source will re-create");
+        for (const qn of namedHits) {
+            const dot = qn.indexOf(".");
+            const dropSql = `DROP TABLE IF EXISTS ${quoteIdent(qn.slice(0, dot))}.${quoteIdent(qn.slice(dot + 1))} CASCADE`;
+            const dropRes = runPsql(targetUri, dropSql);
+            if (dropRes.code !== 0) {
+                emitError("RESTORE_FAILED", `Could not clear the target's seeded ${qn} before restore.`, `The source has its own ${qn}, which cannot restore over the target's seeded copy. ` +
+                    strandedHintJson, 1);
+                return;
+            }
+        }
+    }
     // ── Phase 4: migrate ───────────────────────────────────────────────────────
     phase("Migrating schema + data (pg_dump | psql)");
     const migration = await runMigration(source, targetUri);

package/dist/commands/studio.d.ts

@@ -0,0 +1,31 @@
+/**
+ * bata studio: launch turbine-orm's Studio locally against a BataDB branch.
+ *
+ * Zero hosting infra: resolves the branch's DIRECT connection URI from the
+ * control plane, wakes the compute if it scaled to zero, then spawns
+ * `npx --yes turbine-orm@latest studio` with DATABASE_URL set. Studio itself
+ * is turbine's local web UI (loopback-only, read-only by default); everything
+ * it renders travels over a direct TCP connection from this machine.
+ *
+ * Compat-honest: PII redaction in Studio is turbine's feature (PII-tagged
+ * columns are redacted by default, `--show-pii` unredacts), not something
+ * BataDB enforces server-side.
+ */
+export interface StudioArgs {
+    project?: string;
+    branch?: string;
+    port?: number;
+    write: boolean;
+    showPii: boolean;
+    noOpen: boolean;
+    help: boolean;
+}
+/**
+ * Parse `bata studio` args (both `--flag value` and `--flag=value` forms).
+ * Returns `{ error }` on a malformed flag so the caller can fail fast with
+ * INVALID_FLAG before touching the network. Exported for unit testing.
+ */
+export declare function parseStudioArgs(args: string[]): StudioArgs | {
+    error: string;
+};
+export declare function studio(args?: string[]): Promise<void>;

package/dist/commands/studio.js

@@ -0,0 +1,262 @@
+/**
+ * bata studio: launch turbine-orm's Studio locally against a BataDB branch.
+ *
+ * Zero hosting infra: resolves the branch's DIRECT connection URI from the
+ * control plane, wakes the compute if it scaled to zero, then spawns
+ * `npx --yes turbine-orm@latest studio` with DATABASE_URL set. Studio itself
+ * is turbine's local web UI (loopback-only, read-only by default); everything
+ * it renders travels over a direct TCP connection from this machine.
+ *
+ * Compat-honest: PII redaction in Studio is turbine's feature (PII-tagged
+ * columns are redacted by default, `--show-pii` unredacts), not something
+ * BataDB enforces server-side.
+ */
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { api, asList, apiError } from "../api.js";
+import { requireToken, loadConfig, isJsonMode } from "../config.js";
+import { colors, log, spinner, info as logInfo } from "../utils/logger.js";
+import { emitError, isRetryable } from "../utils/errors.js";
+import { resolveProjectId, readLinkFile } from "../link.js";
+/**
+ * Parse `bata studio` args (both `--flag value` and `--flag=value` forms).
+ * Returns `{ error }` on a malformed flag so the caller can fail fast with
+ * INVALID_FLAG before touching the network. Exported for unit testing.
+ */
+export function parseStudioArgs(args) {
+    const out = { write: false, showPii: false, noOpen: false, help: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const takeVal = (flag) => {
+            const next = args[++i];
+            if (next === undefined || next.startsWith("-")) {
+                return { error: `${flag} requires a value.` };
+            }
+            return next;
+        };
+        let v;
+        if (a === "--project") {
+            v = takeVal("--project");
+            if (typeof v !== "string")
+                return v;
+            out.project = v;
+        }
+        else if (a.startsWith("--project=")) {
+            out.project = a.slice("--project=".length);
+        }
+        else if (a === "--branch") {
+            v = takeVal("--branch");
+            if (typeof v !== "string")
+                return v;
+            out.branch = v;
+        }
+        else if (a.startsWith("--branch=")) {
+            out.branch = a.slice("--branch=".length);
+        }
+        else if (a === "--port" || a.startsWith("--port=")) {
+            const raw = a === "--port" ? takeVal("--port") : a.slice("--port=".length);
+            if (typeof raw !== "string")
+                return raw;
+            const n = Number(raw);
+            if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+                return { error: `Invalid port "${raw}". Use an integer between 1 and 65535.` };
+            }
+            out.port = n;
+        }
+        else if (a === "--write") {
+            out.write = true;
+        }
+        else if (a === "--show-pii") {
+            out.showPii = true;
+        }
+        else if (a === "--no-open") {
+            out.noOpen = true;
+        }
+        else if (a === "--help" || a === "-h") {
+            out.help = true;
+        }
+        else {
+            return { error: `Unknown flag "${a}".` };
+        }
+    }
+    return out;
+}
+function studioHelp() {
+    const usage = (line) => log(`  ${colors.cyan(line)}`);
+    const note = (line) => log(`  ${colors.dim(line)}`);
+    log();
+    log(`  ${colors.bold("bata studio")}: launch Turbine Studio locally against a BataDB branch`);
+    log();
+    usage("bata studio [--project <id|name>] [--branch <name|id>] [--port <n>]");
+    usage("bata studio [--write] [--show-pii] [--no-open]");
+    log();
+    note("Runs turbine-orm's Studio on YOUR machine (npx turbine-orm@latest studio)");
+    note("over a direct TCP connection to the branch. Nothing is hosted by BataDB;");
+    note("close the terminal and it's gone.");
+    log();
+    note("--project <id|name>  Target project (default: linked/default project)");
+    note("--branch <name|id>   Target branch (default: the checked-out branch from");
+    note("                     `bata db branch checkout`, else the primary branch)");
+    note("--port <n>           Local port for Studio (default: turbine's 4983)");
+    note("--write              Forwarded to turbine: enable single-row writes (default read-only)");
+    note("--show-pii           Forwarded to turbine: show PII-tagged columns unredacted");
+    note("--no-open            Forwarded to turbine: don't auto-open the browser");
+    log();
+    note("Honesty notes: Studio binds to loopback only and is read-only by default.");
+    note("PII redaction is turbine's client-side feature (PII-tagged columns are");
+    note("redacted in the UI), NOT a BataDB server-side control: the direct");
+    note("connection itself sees real data.");
+    note("A scaled-to-zero compute is woken first; that can take a few seconds.");
+    log();
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Wake a branch's compute and wait until it answers a query. Kicks the start
+ * endpoint when the compute reports suspended, then probes with `SELECT 1`
+ * via /v1/sql/execute: retryable failures (503 COMPUTE_STARTING, connection
+ * refused) keep polling; a hard failure stops early (Studio's own connection
+ * will surface the real error). Budget exhausted → COMPUTE_STARTING (exit 6),
+ * the retryable contract agents already know.
+ */
+async function wakeBranch(branchId, computeStatus, token, onTick) {
+    if (computeStatus === "suspended") {
+        // Non-fatal if it fails: the probe below (or the proxy) can still wake it.
+        await api.post(`/v1/computes/${branchId}/start`, {}, token).catch(() => undefined);
+    }
+    const budget = 120_000;
+    const interval = 3_000;
+    const start = Date.now();
+    while (true) {
+        const res = await api.post("/v1/sql/execute", { branch_id: branchId, query: "SELECT 1" }, token);
+        if (res.ok && !res.data?.error)
+            return;
+        const body = res.data;
+        const retryable = isRetryable({ status: res.status, code: body?.code, message: body?.error });
+        if (!retryable)
+            return; // hard failure: let Studio's own connection report it
+        if (Date.now() - start >= budget) {
+            emitError("COMPUTE_STARTING", apiError(res, "Compute is still starting"), "compute is starting; retry `bata studio` in a few seconds");
+        }
+        onTick(Math.round((Date.now() - start) / 1000));
+        await sleep(interval);
+    }
+}
+export async function studio(args = []) {
+    const parsed = parseStudioArgs(args);
+    if ("error" in parsed) {
+        emitError("INVALID_FLAG", parsed.error, "Usage: bata studio [--project <id|name>] [--branch <name|id>] [--port <n>]");
+    }
+    if (parsed.help) {
+        studioHelp();
+        return;
+    }
+    // Studio is a long-running local web server with browser interaction; there
+    // is no headless JSON equivalent. Point agents at the headless surfaces.
+    if (isJsonMode()) {
+        emitError("INTERACTIVE_ONLY", "bata studio launches a local web UI and can't run in --json mode.", "Use `bata db query <sql> --json` or `bata schema dump` for headless access.");
+    }
+    const token = requireToken();
+    const config = loadConfig();
+    // Project precedence: --project (id OR name, resolved against /v1/projects)
+    // > .batadata link > config default.
+    let projectId = resolveProjectId().projectId;
+    if (parsed.project) {
+        const s = spinner("Looking up project");
+        const query = {};
+        if (config.defaultTeam)
+            query.team_id = config.defaultTeam;
+        const projRes = await api.get("/v1/projects", token, query);
+        s.stop();
+        if (!projRes.ok) {
+            emitError(projRes.status === 401 || projRes.status === 403 ? "INVALID_KEY"
+                : projRes.status >= 500 || projRes.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR", apiError(projRes, "Failed to fetch projects."), "");
+        }
+        const found = asList(projRes.data).find((p) => p.id === parsed.project || p.name === parsed.project);
+        if (!found) {
+            emitError("NOT_FOUND", `Project "${parsed.project}" not found.`, "List projects with: bata status");
+        }
+        projectId = found.id;
+    }
+    if (!projectId) {
+        emitError("NO_PROJECT", "No project specified.", "Pass --project <id|name>, or run `bata link <project>` to set a default.");
+    }
+    const s = spinner("Fetching connection info");
+    const connRes = await api.get(`/v1/connection-info/${projectId}`, token, { reveal: "true" });
+    if (!connRes.ok || !connRes.data?.connections?.length) {
+        s.stop();
+        emitError(connRes.status >= 500 || connRes.status === 0 ? "API_UNAVAILABLE" : "NOT_FOUND", apiError(connRes, "Could not fetch connection info for this project."), "");
+    }
+    const conns = connRes.data.connections;
+    // Branch precedence: an explicit --branch wins, else the branch pinned by
+    // `bata db branch checkout` in .batadata/project.json, but ONLY when studio
+    // targets the linked project (same guard as `db query`: a pinned branch from
+    // project A must never resolve against an explicit --project B).
+    const link = readLinkFile()?.link;
+    const pinnedBranch = link && link.projectId === projectId ? link.branchId ?? undefined : undefined;
+    const branchRef = parsed.branch ?? pinnedBranch;
+    const conn = branchRef
+        ? conns.find((c) => c.branch_id === branchRef || c.branch_name === branchRef)
+        : conns.find((c) => c.is_primary) ?? conns[0];
+    if (!conn) {
+        s.stop();
+        emitError("BRANCH_NOT_FOUND", `Branch "${branchRef}" not found in this project.`, "List branches with: bata db branches --json");
+    }
+    if (!conn.direct || !conn.branch_id) {
+        s.stop();
+        emitError("NOT_FOUND", "No direct connection string available for this branch.", "");
+    }
+    // BataDB computes scale to zero: wake the branch before handing the URI to
+    // Studio, so its first introspection doesn't hit a cold compute and die.
+    s.update("Waking compute");
+    await wakeBranch(conn.branch_id, conn.compute_status, token, (secs) => {
+        s.update(`Waking compute (${secs}s)`);
+    });
+    s.stop();
+    log();
+    logInfo(`Launching Turbine Studio for ${colors.cyan(connRes.data.project_name ?? projectId)}`
+        + (conn.branch_name ? ` ${colors.dim(`branch ${conn.branch_name}`)}` : ""));
+    log(`  ${colors.dim("Local UI over a direct TCP connection. Read-only by default;")}`);
+    log(`  ${colors.dim("PII redaction is turbine's UI feature, not a BataDB server control.")}`);
+    log(`  ${colors.dim("Press Ctrl+C to stop.")}`);
+    log();
+    // Run npx from a scratch dir so a turbine.config.* in the user's cwd can
+    // never override the DATABASE_URL we resolved (turbine's env wins over its
+    // config file, but a scratch cwd removes the question entirely). Studio
+    // introspects the live DB, so no config/client generation is needed.
+    const scratchDir = mkdtempSync(path.join(os.tmpdir(), "bata-studio-"));
+    const cleanup = () => {
+        try {
+            rmSync(scratchDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    };
+    const turbineArgs = ["--yes", "turbine-orm@latest", "studio"];
+    if (parsed.port !== undefined)
+        turbineArgs.push("--port", String(parsed.port));
+    if (parsed.write)
+        turbineArgs.push("--write");
+    if (parsed.showPii)
+        turbineArgs.push("--show-pii");
+    if (parsed.noOpen)
+        turbineArgs.push("--no-open");
+    const child = spawn("npx", turbineArgs, {
+        cwd: scratchDir,
+        stdio: "inherit",
+        env: { ...process.env, DATABASE_URL: conn.direct },
+    });
+    child.on("error", (err) => {
+        cleanup();
+        emitError("CLI_ERROR", `Failed to launch turbine-orm studio via npx: ${err.message}`, "Is npx (Node.js) on your PATH?");
+    });
+    child.on("exit", (code) => {
+        cleanup();
+        process.exit(code ?? 0);
+    });
+}

package/dist/index.js

@@ -17,6 +17,7 @@ import { handleCompute } from "./commands/compute.js";
 import { handleRestore } from "./commands/restore.js";
 import { handlePowdb } from "./commands/powdb.js";
 import { importDb } from "./commands/import.js";
+import { studio } from "./commands/studio.js";
 import { link, unlink } from "./commands/link.js";
 import { parseGlobalFlags } from "./args.js";
 import { isJsonMode } from "./config.js";
@@ -63,6 +64,7 @@ function help() {
     log(`    ${colors.cyan("db branch delete")}   Delete a branch`);
     log(`    ${colors.cyan("db branch checkout")} Pin a branch into ${colors.dim(".batadata/project.json")}`);
     log(`    ${colors.cyan("db studio")}          Open table browser in browser`);
+    log(`    ${colors.cyan("studio")}             Run Turbine Studio locally against a branch ${colors.dim("(local UI, direct TCP)")}`);
     log(`    ${colors.cyan("db query")}           Run a SQL query ${colors.dim("(--branch <id> to target a branch)")}`);
     log();
     log(`  ${colors.bold("Compute")}`);
@@ -220,6 +222,10 @@ async function main() {
             case "import":
                 await importDb(rest);
                 break;
+            // Local Turbine Studio against a branch
+            case "studio":
+                await studio(rest);
+                break;
             // Dev
             case "dev":
                 await dev();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batadata/cli",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "CLI for BataDB — serverless Postgres platform",
   "bin": {
     "bata": "./dist/index.js"