@batadata/cli 0.1.8 → 0.1.10

package/README.md

@@ -102,6 +102,8 @@ 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 |
+| `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 |
 | `generate` | Generate types from your database schema (`--watch` for watch mode) |
 | `dev` | Print the local development setup guide |
@@ -113,6 +115,38 @@ safety.
 
 Run `bata --help` for the full, authoritative command list, or `bata --version`.
 
+## Point-in-time restore (PITR)
+
+Recover a branch to an earlier point in time. Restore is **non-destructive**: it
+creates a **new** branch at the chosen point and never overwrites the source
+branch's data.
+
+```bash
+bata restore points                         # what can I restore to?
+bata restore create \
+  --branch main \
+  --at 2026-07-04T12:00:00Z \
+  --name before-the-bad-migration          # → a new branch at that timestamp
+```
+
+`--at` accepts either an **ISO-8601 timestamp** (e.g. `2026-07-04T12:00:00Z`) or
+a Postgres **LSN** (e.g. `0/15994B0`); the CLI detects which you passed. If
+`--name` is omitted the new branch is named `restore-<branch>-<timestamp>`. The
+new branch's compute may still be provisioning when the command returns — poll
+`bata db branches` before you query it.
+
+### How far back can I restore? (honest window)
+
+Recovery points are **timeline-metadata snapshots** the control plane's backup
+scheduler records about **every 6 hours** (`BACKUP_INTERVAL_HOURS`, default `6`).
+They are *not* full physical backups, and the earliest point `restore points`
+lists is simply the oldest metadata row we have — **not** a guaranteed floor on
+how far back you can restore. Actual restorability to an arbitrary timestamp
+depends on how much WAL the storage engine still retains: if the WAL no longer
+covers your timestamp, the server returns *"No data available at the requested
+timestamp"* and the restore is refused. We surface that verbatim rather than
+implying the window is deeper than it is.
+
 ## Headless / agent use
 
 Every command runs headlessly with just `BATA_API_KEY` set — no `bata login`,

package/dist/api.d.ts

@@ -50,5 +50,6 @@ export declare function asList<T = unknown>(data: unknown): T[];
 export declare const api: {
     get: <T = unknown>(path: string, token?: string, query?: Record<string, string>) => Promise<ApiResponse<T>>;
     post: <T = unknown>(path: string, body: Record<string, unknown>, token?: string) => Promise<ApiResponse<T>>;
+    patch: <T = unknown>(path: string, body: Record<string, unknown>, token?: string, query?: Record<string, string>) => Promise<ApiResponse<T>>;
     del: <T = unknown>(path: string, token?: string, query?: Record<string, string>) => Promise<ApiResponse<T>>;
 };

package/dist/api.js

@@ -152,5 +152,6 @@ export function asList(data) {
 export const api = {
     get: (path, token, query) => request("GET", path, { token, query }),
     post: (path, body, token) => request("POST", path, { token, body }),
+    patch: (path, body, token, query) => request("PATCH", path, { token, body, query }),
     del: (path, token, query) => request("DELETE", path, { token, query }),
 };

package/dist/commands/db.d.ts

@@ -23,6 +23,13 @@ export declare function url(): Promise<void>;
 export declare function branches(): Promise<void>;
 export declare function branchCreate(args?: string[]): Promise<void>;
 export declare function branchDelete(name?: string): Promise<void>;
+/**
+ * `bata db branch protect <name-or-id>` / `unprotect <name-or-id>` — flip a
+ * branch's protection flag (PATCH /v1/branches/:id). A protected branch refuses
+ * delete/reset/rollback/reap — the safety rail for headless/agent ops. The ref
+ * is resolved by name OR id, like the other branch commands.
+ */
+export declare function branchSetProtected(ref: string | undefined, wantProtected: boolean): Promise<void>;
 /**
  * `bata db branch checkout <name-or-id>` — pin a branch into the directory's
  * `.batadata/project.json` so later `db query` / `db url` target it with no

package/dist/commands/db.js

@@ -7,6 +7,9 @@ import { prompt, confirmDestructive } from "../utils/prompts.js";
 import { openBrowser } from "../utils/open.js";
 import { emitError, isRetryable } from "../utils/errors.js";
 import { resolveProjectId, resolveBranchId, findLinkFile, writeLinkFile } from "../link.js";
+// Share the exact LSN/timestamp discriminator `bata restore` uses so `db query
+// --at` classifies a restore point identically.
+import { classifyRestorePoint } from "./restore.js";
 async function getConnectionInfo(projectId, token) {
     // reveal=true so the returned string is actually usable (the owner is asking).
     const res = await api.get(`/v1/connection-info/${projectId}`, token, { reveal: "true" });
@@ -219,6 +222,8 @@ export async function branches() {
                 // Ephemeral-branch TTL: when set, the branch is auto-reaped after this.
                 expires_at: b.expiresAt ?? null,
                 purpose: b.purpose ?? null,
+                // Protection flag — a protected branch refuses delete/reset/rollback/reap.
+                protected: b.isProtected ?? false,
                 created_at: b.createdAt ?? null,
             })),
             count: branchList.length,
@@ -231,9 +236,12 @@ export async function branches() {
         log();
         return;
     }
-    table(["NAME", "PRIMARY", "STATUS", "EXPIRES", "CREATED"], branchList.map((b) => [
+    table(["NAME", "PRIMARY", "PROTECTED", "STATUS", "EXPIRES", "CREATED"], branchList.map((b) => [
         b.name,
         b.isPrimary ? colors.green("yes") : "-",
+        // Protected branches are locked against destructive ops — flag them so the
+        // column is scannable.
+        b.isProtected ? colors.yellow("locked") : "-",
         // Live compute lifecycle (computeStatus), with a check once ready so the
         // column is scannable.
         branchStatusLabel(b),
@@ -359,6 +367,56 @@ export async function branchDelete(name) {
     log(`  ${colors.green(">")} Branch ${colors.cyan(name)} deleted`);
     log();
 }
+/**
+ * `bata db branch protect <name-or-id>` / `unprotect <name-or-id>` — flip a
+ * branch's protection flag (PATCH /v1/branches/:id). A protected branch refuses
+ * delete/reset/rollback/reap — the safety rail for headless/agent ops. The ref
+ * is resolved by name OR id, like the other branch commands.
+ */
+export async function branchSetProtected(ref, wantProtected) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    const config = loadConfig();
+    const projectId = resolveProjectId().projectId;
+    const verb = wantProtected ? "protect" : "unprotect";
+    if (!projectId) {
+        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
+    }
+    if (!ref) {
+        emitError("MISSING_ARG", "Branch name or id is required.", `Usage: bata db branch ${verb} <name-or-id>`);
+    }
+    const s = jsonMode ? null : spinner(`Resolving branch ${colors.cyan(ref)}`);
+    const branch = await resolveBranchRef(projectId, token, config.defaultTeam, ref);
+    s?.stop();
+    if (!branch) {
+        emitError("BRANCH_NOT_FOUND", `Branch "${ref}" not found in this project.`, "List branches with: bata db branches --json");
+    }
+    const s2 = jsonMode ? null : spinner(`${wantProtected ? "Protecting" : "Unprotecting"} branch ${colors.cyan(branch.name)}`);
+    const query = {};
+    if (config.defaultTeam)
+        query.team_id = config.defaultTeam;
+    const res = await api.patch(`/v1/branches/${branch.id}`, { protected: wantProtected }, token, query);
+    s2?.stop();
+    if (!res.ok) {
+        emitError(res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE" : "CLI_ERROR", apiError(res, `Failed to ${verb} branch.`), "");
+    }
+    if (jsonMode) {
+        json({
+            branch: { id: branch.id, name: branch.name, project_id: projectId },
+            protected: res.data.isProtected ?? wantProtected,
+        });
+        return;
+    }
+    log();
+    if (wantProtected) {
+        log(`  ${colors.green(">")} Branch ${colors.cyan(branch.name)} is now ${colors.yellow("protected")}`);
+        log(`  ${colors.dim("It can't be deleted, reset, rolled back, or auto-reaped until unprotected.")}`);
+    }
+    else {
+        log(`  ${colors.green(">")} Branch ${colors.cyan(branch.name)} is no longer protected`);
+    }
+    log();
+}
 /**
  * Pull a `--project <id>` / `--project=<id>` flag out of args, returning the
  * explicit project id (if any) and the remaining positionals. Lets `db branch
@@ -436,14 +494,14 @@ export async function studio() {
     openBrowser(studioUrl);
 }
 /**
- * Pull a `--branch <ref>` / `--branch=<ref>` flag out of the query args and
- * return the explicit branch ref — an id OR a name, resolved later — plus the
- * remaining args, which join into the SQL string. Keeps `db query`
- * order-independent (the flag can sit before or after the SQL) and consistent
- * with how global flags are parsed.
+ * Pull `--branch <ref>` / `--at <ISO-timestamp|LSN>` flags (and their `=` forms)
+ * out of the query args and return them plus the remaining args, which join into
+ * the SQL string. Keeps `db query` order-independent (flags can sit before or
+ * after the SQL) and consistent with how global flags are parsed.
  */
-function parseBranchFlag(args) {
+function parseQueryFlags(args) {
     let branchId;
+    let at;
     const rest = [];
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -453,15 +511,117 @@ function parseBranchFlag(args) {
         else if (arg.startsWith("--branch=")) {
             branchId = arg.slice("--branch=".length);
         }
+        else if (arg === "--at") {
+            at = args[++i];
+        }
+        else if (arg.startsWith("--at=")) {
+            at = arg.slice("--at=".length);
+        }
         else {
             rest.push(arg);
         }
     }
-    return { branchId, rest };
+    return { branchId, at, rest };
+}
+/**
+ * Resolve the branch a query should target: an explicit `--branch <id-or-name>`
+ * (resolved against the project's branch list) or the project's primary branch.
+ * Exits (via emitError) with BRANCH_NOT_FOUND if nothing matches.
+ */
+async function resolveQueryBranchId(projectId, token, teamId, branchRef) {
+    if (branchRef) {
+        const branch = await resolveBranchRef(projectId, token, teamId, branchRef);
+        if (!branch) {
+            emitError("BRANCH_NOT_FOUND", `Branch "${branchRef}" not found in this project.`, "List branches with: bata db branches --json");
+        }
+        return branch.id;
+    }
+    const branch = await getPrimaryBranch(projectId, token, teamId);
+    if (!branch) {
+        emitError("BRANCH_NOT_FOUND", "No branch found for this project to run the query against.", "Check the project with: bata db branches --json");
+    }
+    return branch.id;
+}
+/**
+ * Run a time-travel query: POST /v1/time-travel/query, which forks a hidden
+ * ephemeral branch AS OF the point and runs the SQL there. Handles the cold-fork
+ * 503 contract — the response always carries the ephemeral `branch` handle so an
+ * agent can back off (exit 6) and retry the query itself via
+ * `bata db query <sql> --branch <returned-id>`.
+ */
+async function runTimeTravelQuery(opts) {
+    const { projectId, branchId, point, sql, token, jsonMode } = opts;
+    const s = jsonMode ? null : spinner(`Running query as of ${point.raw}`);
+    const res = await api.post("/v1/time-travel/query", { project_id: projectId, branch_id: branchId, at: point.value, query: sql }, token);
+    s?.stop();
+    if (!res.ok) {
+        const body = res.data;
+        // Cold fork: the ephemeral branch is still starting. Retryable (exit 6). The
+        // branch handle rides along so the agent can retry against it via /v1/sql.
+        if (isRetryable({ status: res.status, code: body?.code, message: body?.error })) {
+            if (jsonMode) {
+                json({
+                    error: apiError(res, "Time-travel branch is starting"),
+                    code: body?.code ?? "COMPUTE_STARTING",
+                    hint: "retry the query against the returned branch: bata db query <sql> --branch <branch.id>",
+                    branch: body?.branch ?? null,
+                });
+                process.exit(6);
+            }
+            emitError("COMPUTE_STARTING", apiError(res, "Time-travel branch is starting"), body?.branch
+                ? `compute is starting; retry in a few seconds with --branch ${body.branch.id}`
+                : "compute is starting; retry in a few seconds");
+        }
+        const code = res.status === 401 || res.status === 403 ? "INVALID_KEY" : "CLI_ERROR";
+        emitError(code, apiError(res, "Time-travel query failed"), "");
+    }
+    // The route returns an error field only on a real failure it couldn't map to a
+    // status; treat it as an error, not a silent success.
+    if (res.data.error) {
+        emitError("CLI_ERROR", res.data.error, "");
+    }
+    const columns = res.data.columns ?? [];
+    const rows = res.data.rows ?? [];
+    const rowCount = res.data.rowCount ?? rows.length;
+    const branch = res.data.branch ?? null;
+    if (jsonMode) {
+        json({
+            columns,
+            rows,
+            row_count: rowCount,
+            command: res.data.command ?? null,
+            at: point.value,
+            // The ephemeral branch the query ran against (auto-reaped after ~10 min).
+            branch,
+        });
+        return;
+    }
+    if (columns.length && rows.length) {
+        log();
+        table(columns.map((c) => c.toUpperCase()), rows.map((r) => columns.map((col) => fmtCell(r[col]))));
+        log();
+        log(`  ${colors.dim(`${rowCount} row(s) — as of ${point.raw}`)}`);
+    }
+    else if (rows.length) {
+        const keys = Object.keys(rows[0]);
+        log();
+        table(keys.map((k) => k.toUpperCase()), rows.map((r) => keys.map((k) => fmtCell(r[k]))));
+        log();
+        log(`  ${colors.dim(`${rowCount} row(s) — as of ${point.raw}`)}`);
+    }
+    else {
+        log();
+        const cmd = res.data.command ? `${res.data.command} ` : "";
+        log(`  ${colors.dim(`${cmd}OK — ${rowCount} row(s), as of ${point.raw}.`)}`);
+    }
+    if (branch) {
+        log(`  ${colors.dim(`Ran on ephemeral branch ${branch.id} (auto-deleted ~${new Date(branch.expires_at).toLocaleTimeString()}).`)}`);
+    }
+    log();
 }
 export async function query(args = []) {
     const jsonMode = isJsonMode();
-    const { branchId: branchFlag, rest } = parseBranchFlag(args);
+    const { branchId: branchFlag, at, rest } = parseQueryFlags(args);
     // Branch precedence: an explicit --branch wins, else the branch pinned by
     // `bata db branch checkout` in .batadata/project.json, else the primary.
     const branchId = resolveBranchId(branchFlag).branchId;
@@ -475,6 +635,24 @@ export async function query(args = []) {
     if (!projectId) {
         emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
+    // `--at` is a time-travel query: fork a hidden ephemeral branch AS OF the point
+    // and run the SQL there. Classify the point up front so a bad --at fails fast.
+    if (at !== undefined) {
+        const classified = classifyRestorePoint(at);
+        if (classified.error) {
+            emitError("INVALID_FLAG", classified.error, "Pass --at <ISO-timestamp|LSN> (an LSN looks like 0/15994B0).");
+        }
+        // Resolve the SOURCE branch to fork from (id or name), like the normal path.
+        const sourceBranchId = await resolveQueryBranchId(projectId, token, config.defaultTeam, branchId);
+        return runTimeTravelQuery({
+            projectId,
+            branchId: sourceBranchId,
+            point: classified.point,
+            sql,
+            token,
+            jsonMode,
+        });
+    }
     const s = jsonMode ? null : spinner("Running query");
     // Target branch: an explicit --branch <id-or-name> wins; otherwise resolve
     // the project's primary branch. /v1/sql/execute is keyed on branch_id, not
@@ -577,12 +755,15 @@ function dbHelp(sub) {
             log(`  ${colors.bold("bata db query")} — run a SQL query against a branch`);
             log();
             usage('bata db query "SELECT 1"');
-            usage("bata db query <sql> [--branch <id-or-name>] [--json]");
+            usage("bata db query <sql> [--branch <id-or-name>] [--at <timestamp|LSN>] [--json]");
             log();
             note("--branch <id-or-name>  Target a specific branch by id OR name (default: the project's primary)");
+            note("--at <timestamp|LSN>   Time-travel: run the query AS OF a past point (ISO-8601");
+            note("                       timestamp e.g. 2026-07-04T12:00:00Z, or an LSN e.g. 0/15994B0).");
+            note("                       Forks a hidden ephemeral branch (auto-deleted ~10 min).");
             note("--json                 Emit rows as JSON objects + row_count");
-            note("Cold-start note: a just-created/idle branch may answer with exit 6");
-            note("(retryable) while its compute wakes — retry in a few seconds.");
+            note("Cold-start note: a just-created/idle branch (or a fresh --at fork) may answer");
+            note("with exit 6 (retryable) while its compute wakes — retry in a few seconds.");
             break;
         case "branches":
             log(`  ${colors.bold("bata db branches")} — list branches and their compute status`);
@@ -598,11 +779,15 @@ function dbHelp(sub) {
             usage("bata db branch create <name> [--expires-in <2h|30m|7d>] [--purpose <text>]");
             usage("bata db branch delete <name> [--yes]");
             usage("bata db branch checkout <name-or-id> [--project <id>]");
+            usage("bata db branch protect <name-or-id>");
+            usage("bata db branch unprotect <name-or-id>");
             log();
             note("--expires-in  Auto-delete the branch after this long (units: s/m/h/d/w).");
             note("--purpose     Free-text note describing why the branch exists.");
             note("checkout pins the branch into .batadata/project.json so db query/url");
             note("target it without a --branch flag. Needs a linked project (bata link).");
+            note("protect/unprotect lock a branch against delete/reset/rollback/auto-reap.");
+            note("A protected branch cannot also carry a TTL (they're mutually exclusive).");
             break;
         case "url":
             log(`  ${colors.bold("bata db url")} — print the connection string`);
@@ -629,6 +814,8 @@ function dbHelp(sub) {
             usage("bata db branch create    Create a new branch");
             usage("bata db branch delete    Delete a branch");
             usage("bata db branch checkout  Pin a branch into .batadata/project.json");
+            usage("bata db branch protect   Lock a branch against destructive ops");
+            usage("bata db branch unprotect Remove a branch's protection");
             usage("bata db studio           Open the table browser");
             usage("bata db query <sql>      Run a SQL query (--branch <id-or-name> to target a branch)");
             log();
@@ -660,7 +847,11 @@ export async function handleDb(args) {
                 return branchDelete(args[2]);
             if (action === "checkout")
                 return branchCheckout(args.slice(2));
-            emitError("INVALID_FLAG", `Unknown: db branch ${action || ""}`, "Available: create, delete, checkout");
+            if (action === "protect")
+                return branchSetProtected(args[2], true);
+            if (action === "unprotect")
+                return branchSetProtected(args[2], false);
+            emitError("INVALID_FLAG", `Unknown: db branch ${action || ""}`, "Available: create, delete, checkout, protect, unprotect");
         }
         case "studio":
             return studio();

package/dist/commands/restore.d.ts

@@ -0,0 +1,71 @@
+/**
+ * bata restore — Point-in-time restore (PITR).
+ *
+ * Two subcommands:
+ *   restore points [--project <id>] [--json]
+ *       List the recovery points recorded for a project (GET
+ *       /v1/recovery-points/:projectId) plus each branch's live LSN and the
+ *       honest PITR window.
+ *
+ *   restore create --branch <name-or-id> --at <ISO-timestamp|LSN>
+ *                  [--name <newBranchName>] [--project <id>] [--json]
+ *       Restore a branch to a point in time by creating a NEW branch at that
+ *       point (POST /v1/restore). This is non-destructive: the source branch's
+ *       data is never overwritten.
+ *
+ * HONESTY RULE (documented, never overclaimed):
+ *   Recovery points are timeline-metadata snapshots the backup scheduler records
+ *   about every 6 hours (BACKUP_INTERVAL_HOURS) — they are NOT full physical
+ *   backups, and the earliest listed point is the oldest metadata row we have,
+ *   not a guaranteed floor on how far back you can restore. Restorability to an
+ *   arbitrary timestamp depends on how much WAL the pageserver still retains; if
+ *   the WAL doesn't extend that far the server returns "No data available at the
+ *   requested timestamp." We surface that verbatim rather than pretending the
+ *   window is deeper than it is.
+ */
+export interface RestorePoint {
+    /** How the input was interpreted. */
+    kind: "lsn" | "timestamp";
+    /**
+     * The value to send to the server. For an LSN it's the input as-is; for a
+     * timestamp it's normalized to offset-aware ISO 8601 so the server's
+     * `datetime({ offset: true })` validation accepts it.
+     */
+    value: string;
+    /** The raw user input (for human display). */
+    raw: string;
+}
+/**
+ * Classify a `--at` value as an LSN or a timestamp. An LSN (`0/15994B0`) is
+ * matched structurally; anything else is parsed as a date and normalized to
+ * offset-aware ISO 8601. Returns `{ error }` for input that is neither.
+ * Exported for unit testing.
+ */
+export declare function classifyRestorePoint(input: string): {
+    point?: RestorePoint;
+    error?: string;
+};
+/**
+ * Parse `restore create` args: `--branch`, `--at`, `--name`, `--project`
+ * (each accepting both `--flag value` and `--flag=value`). Order-independent,
+ * mirroring `parseBranchCreateArgs`. Exported for unit testing.
+ */
+export declare function parseRestoreCreateArgs(args: string[]): {
+    branch?: string;
+    at?: string;
+    name?: string;
+    projectId?: string;
+};
+/** Parse `restore points` args — only `--project` is meaningful here. */
+export declare function parseRestorePointsArgs(args: string[]): {
+    projectId?: string;
+};
+/**
+ * A default name for the restored branch when `--name` is omitted. Includes a
+ * compact UTC stamp so repeated restores don't collide, e.g.
+ * `restore-main-20260704T120000Z`.
+ */
+export declare function defaultRestoreBranchName(sourceName: string, now?: Date): string;
+export declare function restorePoints(args: string[]): Promise<void>;
+export declare function restoreCreate(args: string[]): Promise<void>;
+export declare function handleRestore(args: string[]): Promise<void>;

package/dist/commands/restore.js

@@ -0,0 +1,356 @@
+/**
+ * bata restore — Point-in-time restore (PITR).
+ *
+ * Two subcommands:
+ *   restore points [--project <id>] [--json]
+ *       List the recovery points recorded for a project (GET
+ *       /v1/recovery-points/:projectId) plus each branch's live LSN and the
+ *       honest PITR window.
+ *
+ *   restore create --branch <name-or-id> --at <ISO-timestamp|LSN>
+ *                  [--name <newBranchName>] [--project <id>] [--json]
+ *       Restore a branch to a point in time by creating a NEW branch at that
+ *       point (POST /v1/restore). This is non-destructive: the source branch's
+ *       data is never overwritten.
+ *
+ * HONESTY RULE (documented, never overclaimed):
+ *   Recovery points are timeline-metadata snapshots the backup scheduler records
+ *   about every 6 hours (BACKUP_INTERVAL_HOURS) — they are NOT full physical
+ *   backups, and the earliest listed point is the oldest metadata row we have,
+ *   not a guaranteed floor on how far back you can restore. Restorability to an
+ *   arbitrary timestamp depends on how much WAL the pageserver still retains; if
+ *   the WAL doesn't extend that far the server returns "No data available at the
+ *   requested timestamp." We surface that verbatim rather than pretending the
+ *   window is deeper than it is.
+ */
+import { api, apiError } from "../api.js";
+import { requireToken, loadConfig, isJsonMode } from "../config.js";
+import { colors, log, json, spinner, table, heading, kvList, success } from "../utils/logger.js";
+import { emitError, isRetryable } from "../utils/errors.js";
+import { resolveProjectId } from "../link.js";
+// A Postgres LSN is two hex words joined by a slash, e.g. `0/15994B0`. That
+// shape can never collide with an ISO-8601 timestamp (which carries `-`/`:`),
+// so the slash-of-hex is a safe discriminator.
+const LSN_RE = /^[0-9A-Fa-f]+\/[0-9A-Fa-f]+$/;
+/**
+ * Classify a `--at` value as an LSN or a timestamp. An LSN (`0/15994B0`) is
+ * matched structurally; anything else is parsed as a date and normalized to
+ * offset-aware ISO 8601. Returns `{ error }` for input that is neither.
+ * Exported for unit testing.
+ */
+export function classifyRestorePoint(input) {
+    const raw = (input ?? "").trim();
+    if (!raw) {
+        return { error: "A restore point is required. Pass --at <ISO-timestamp|LSN>." };
+    }
+    if (LSN_RE.test(raw)) {
+        return { point: { kind: "lsn", value: raw, raw } };
+    }
+    const d = new Date(raw);
+    if (!Number.isNaN(d.getTime())) {
+        return { point: { kind: "timestamp", value: d.toISOString(), raw } };
+    }
+    return {
+        error: `Could not parse "${raw}" as an ISO-8601 timestamp or an LSN (e.g. 0/15994B0).`,
+    };
+}
+/**
+ * Parse `restore create` args: `--branch`, `--at`, `--name`, `--project`
+ * (each accepting both `--flag value` and `--flag=value`). Order-independent,
+ * mirroring `parseBranchCreateArgs`. Exported for unit testing.
+ */
+export function parseRestoreCreateArgs(args) {
+    let branch;
+    let at;
+    let name;
+    let projectId;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--branch")
+            branch = args[++i];
+        else if (arg.startsWith("--branch="))
+            branch = arg.slice("--branch=".length);
+        else if (arg === "--at")
+            at = args[++i];
+        else if (arg.startsWith("--at="))
+            at = arg.slice("--at=".length);
+        else if (arg === "--name")
+            name = args[++i];
+        else if (arg.startsWith("--name="))
+            name = arg.slice("--name=".length);
+        else if (arg === "--project")
+            projectId = args[++i];
+        else if (arg.startsWith("--project="))
+            projectId = arg.slice("--project=".length);
+    }
+    return { branch, at, name, projectId };
+}
+/** Parse `restore points` args — only `--project` is meaningful here. */
+export function parseRestorePointsArgs(args) {
+    let projectId;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--project")
+            projectId = args[++i];
+        else if (arg.startsWith("--project="))
+            projectId = arg.slice("--project=".length);
+    }
+    return { projectId };
+}
+/**
+ * A default name for the restored branch when `--name` is omitted. Includes a
+ * compact UTC stamp so repeated restores don't collide, e.g.
+ * `restore-main-20260704T120000Z`.
+ */
+export function defaultRestoreBranchName(sourceName, now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+    return `restore-${sourceName}-${stamp}`;
+}
+// ─── Shared helpers ────────────────────────────────────────────────────────
+function requireProject(projectFlag) {
+    const { projectId } = resolveProjectId(projectFlag);
+    if (!projectId) {
+        emitError("NO_PROJECT", "No project. Pass --project <id>, or link one with `bata link <project>`.", "Run `bata link <project>` once, then restore commands need no --project.");
+    }
+    return projectId;
+}
+/**
+ * Resolve a `--branch` reference (id OR name) to a concrete branch via
+ * GET /v1/projects/:id. Agents pass the same name they branched with, so
+ * accepting only ids would be a footgun — mirrors `db query --branch`.
+ */
+async function resolveBranchRef(projectId, token, teamId, ref) {
+    const query = {};
+    if (teamId)
+        query.team_id = teamId;
+    const res = await api.get(`/v1/projects/${projectId}`, token, query);
+    if (!res.ok)
+        return null;
+    const branches = res.data.branches ?? [];
+    return branches.find((b) => b.id === ref || b.name === ref) ?? null;
+}
+function formatDateTime(iso) {
+    if (!iso)
+        return "-";
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    return d.toLocaleString("en-US", {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+    });
+}
+function formatBytes(bytes) {
+    if (bytes === null || bytes === undefined)
+        return "-";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(value < 10 ? 1 : 0)} ${units[unit]}`;
+}
+// ─── restore points ────────────────────────────────────────────────────────
+export async function restorePoints(args) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    const config = loadConfig();
+    const { projectId: projectFlag } = parseRestorePointsArgs(args);
+    const projectId = requireProject(projectFlag);
+    const query = {};
+    if (config.defaultTeam)
+        query.team_id = config.defaultTeam;
+    const s = jsonMode ? null : spinner("Fetching recovery points");
+    const res = await api.get(`/v1/recovery-points/${projectId}`, token, query);
+    s?.stop();
+    if (!res.ok) {
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                : "CLI_ERROR", apiError(res, "Failed to fetch recovery points"), "");
+    }
+    const data = res.data;
+    const points = data.recovery_points ?? [];
+    const live = data.live_state ?? [];
+    const window = data.pitr_window;
+    if (jsonMode) {
+        json({
+            project_id: data.project_id ?? projectId,
+            recovery_points: points,
+            live_state: live,
+            pitr_window: window,
+        });
+        return;
+    }
+    // Map branch_id → name from live_state so the table shows names, not ids.
+    const nameById = new Map(live.map((b) => [b.branch_id, b.branch_name]));
+    heading(`Recovery points — ${projectId}`);
+    kvList([
+        ["Earliest recorded", formatDateTime(window?.earliest_available ?? null)],
+        ["Latest (live)", formatDateTime(window?.latest_available ?? null)],
+    ]);
+    log();
+    if (points.length === 0) {
+        log(`  ${colors.dim("No recorded recovery points yet.")}`);
+        log(`  ${colors.dim("The backup scheduler records a point about every 6 hours.")}`);
+        log();
+    }
+    else {
+        table(["RECORDED", "BRANCH", "LSN", "SIZE", "TYPE"], points.map((p) => [
+            formatDateTime(p.recorded_at),
+            nameById.get(p.branch_id) ?? p.branch_id,
+            p.lsn ?? "-",
+            formatBytes(p.size_bytes),
+            p.type,
+        ]));
+        log();
+    }
+    // Honest window note — never overclaim depth. A recorded point is a metadata
+    // snapshot, and restorability past it depends on WAL retention.
+    log(`  ${colors.dim("Recovery points are timeline-metadata snapshots (recorded ~every 6h),")}`);
+    log(`  ${colors.dim("not full backups. Restore to any timestamp the WAL still covers with:")}`);
+    log(`  ${colors.cyan('bata restore create --branch <name> --at <ISO-timestamp|LSN>')}`);
+    log();
+}
+// ─── restore create ─────────────────────────────────────────────────────────
+export async function restoreCreate(args) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    const config = loadConfig();
+    const { branch, at, name, projectId: projectFlag } = parseRestoreCreateArgs(args);
+    const projectId = requireProject(projectFlag);
+    if (!branch) {
+        emitError("MISSING_ARG", "A source branch is required.", "Usage: bata restore create --branch <name-or-id> --at <ISO-timestamp|LSN>");
+    }
+    if (!at) {
+        emitError("MISSING_ARG", "A restore point is required.", "Pass --at <ISO-timestamp|LSN> (an LSN looks like 0/15994B0).");
+    }
+    const classified = classifyRestorePoint(at);
+    if (classified.error) {
+        emitError("INVALID_FLAG", classified.error, "");
+    }
+    const point = classified.point;
+    const s = jsonMode ? null : spinner(`Resolving branch ${colors.cyan(branch)}`);
+    const sourceBranch = await resolveBranchRef(projectId, token, config.defaultTeam, branch);
+    if (!sourceBranch) {
+        s?.stop();
+        emitError("BRANCH_NOT_FOUND", `Branch "${branch}" not found in this project.`, "List branches with: bata db branches --json");
+    }
+    const targetName = name || defaultRestoreBranchName(sourceBranch.name);
+    s?.update(`Restoring ${colors.cyan(sourceBranch.name)} to ${colors.cyan(point.raw)}`);
+    const body = {
+        project_id: projectId,
+        source_branch_id: sourceBranch.id,
+        target_branch_name: targetName,
+        restore_point: point.kind === "lsn" ? { lsn: point.value } : { timestamp: point.value },
+    };
+    const res = await api.post("/v1/restore", body, token);
+    s?.stop();
+    if (!res.ok) {
+        const respBody = res.data;
+        if (isRetryable({ status: res.status, code: respBody?.code, message: respBody?.error })) {
+            emitError("API_UNAVAILABLE", apiError(res, "Restore failed"), "transient upstream error — retry in a few seconds");
+        }
+        const code = res.status === 401 || res.status === 403 ? "INVALID_KEY" : "CLI_ERROR";
+        emitError(code, apiError(res, "Restore failed"), "");
+    }
+    const restored = res.data.restored_branch;
+    if (!restored) {
+        emitError("CLI_ERROR", res.data.error || "Restore did not return a branch.", "");
+    }
+    const queryHint = `bata db query "SELECT 1" --branch ${restored.id}`;
+    if (jsonMode) {
+        json({
+            restored_branch: {
+                id: restored.id,
+                name: restored.name,
+                parent_branch_id: restored.parent_branch_id,
+                restore_point: restored.restore_point,
+                resolved_lsn: restored.resolved_lsn,
+                compute_id: restored.compute_id,
+            },
+            source_branch_id: sourceBranch.id,
+            operation_id: res.data.operation_id ?? null,
+            // A NEW branch — the source branch's data is untouched.
+            non_destructive: true,
+            // The branch row exists immediately; its compute may still be
+            // provisioning — poll before querying.
+            ready: false,
+            poll: "bata db branches --json",
+            query_hint: queryHint,
+        });
+        return;
+    }
+    log();
+    success(`Restore initiated — created a NEW branch (no data on ${colors.cyan(sourceBranch.name)} was changed)`);
+    log();
+    kvList([
+        ["New branch", `${colors.cyan(restored.name)} ${colors.dim(restored.id)}`],
+        ["Restored from", `${sourceBranch.name} at ${point.raw} ${colors.dim(`(${point.kind})`)}`],
+        ["Resolved LSN", restored.resolved_lsn],
+        ["Operation", res.data.operation_id ?? "-"],
+    ]);
+    log();
+    log(`  ${colors.dim("Poll readiness with")} ${colors.cyan("bata db branches")}${colors.dim(", then query it:")}`);
+    log(`  ${colors.cyan(queryHint)}`);
+    log();
+}
+// ─── Help + dispatch ─────────────────────────────────────────────────────────
+function hasHelpFlag(args) {
+    return args.some((a) => a === "--help" || a === "-h");
+}
+function restoreHelp(sub) {
+    const usage = (line) => log(`  ${colors.cyan(line)}`);
+    const note = (line) => log(`  ${colors.dim(line)}`);
+    log();
+    switch (sub) {
+        case "points":
+            log(`  ${colors.bold("bata restore points")} — list recovery points for a project`);
+            log();
+            usage("bata restore points [--project <id>] [--json]");
+            log();
+            note("Shows recorded recovery points, each branch's live LSN, and the PITR window.");
+            note("Points are metadata snapshots (~every 6h), not full backups — see below.");
+            break;
+        case "create":
+            log(`  ${colors.bold("bata restore create")} — restore a branch to a point in time`);
+            log();
+            usage("bata restore create --branch <name-or-id> --at <ISO-timestamp|LSN> [--name <newBranch>] [--json]");
+            log();
+            note("Non-destructive: creates a NEW branch at the chosen point; the source");
+            note("branch's data is never overwritten. --at accepts an ISO-8601 timestamp");
+            note("(e.g. 2026-07-04T12:00:00Z) or an LSN (e.g. 0/15994B0).");
+            note("--name defaults to restore-<branch>-<timestamp> if omitted.");
+            break;
+        default:
+            log(`  ${colors.bold("bata restore")} — point-in-time restore (PITR)`);
+            log();
+            usage("bata restore points   List recovery points + the PITR window");
+            usage("bata restore create   Restore a branch to a timestamp/LSN as a NEW branch");
+            log();
+            note("Restore is non-destructive — it always creates a new branch.");
+            note("Add --help to a subcommand for details (e.g. bata restore create --help).");
+    }
+    log();
+}
+export async function handleRestore(args) {
+    const sub = args[0];
+    if (hasHelpFlag(args) || !sub) {
+        restoreHelp(sub);
+        return;
+    }
+    switch (sub) {
+        case "points":
+            return restorePoints(args.slice(1));
+        case "create":
+            return restoreCreate(args.slice(1));
+        default:
+            emitError("INVALID_FLAG", `Unknown subcommand: restore ${sub}`, "Available: points, create");
+    }
+}

package/dist/commands/schema.d.ts

@@ -1 +1,6 @@
+/** `model:action` when the shape came from the ORM corpus, else "—" (raw SQL). */
+export declare function ormLabel(q: {
+    model?: string | null;
+    action?: string | null;
+}): string;
 export declare function handleSchema(args: string[]): Promise<void>;

package/dist/commands/schema.js

@@ -53,6 +53,16 @@ function parseCheckArgs(args) {
 const riskColor = (r) => r === "breaking" ? colors.red(r.toUpperCase())
     : r === "risky" || r === "unknown" ? colors.yellow(r.toUpperCase())
         : colors.green(r.toUpperCase());
+/** `model:action` when the shape came from the ORM corpus, else "—" (raw SQL). */
+export function ormLabel(q) {
+    if (q.model && q.action)
+        return `${q.model}:${q.action}`;
+    if (q.model)
+        return q.model;
+    if (q.action)
+        return q.action;
+    return "—";
+}
 function affectedLabel(a) {
     if (a.index)
         return `index ${a.index}`;
@@ -145,8 +155,11 @@ function renderReport(v) {
         log(`    ${colors.dim(f.statement)}`);
         if (f.impactedQueries.length) {
             const shown = f.impactedQueries.slice(0, 8);
-            table(["QUERY", "CALLS", "MEAN", "RISK"], shown.map((q) => [
-                q.query.length > 60 ? q.query.slice(0, 57) + "…" : q.query,
+            // Show model:action (from the ORM corpus) when present — the differentiator
+            // over raw pg_stat_statements shapes, which have no ORM semantics ("—").
+            table(["MODEL:ACTION", "QUERY", "CALLS", "MEAN", "RISK"], shown.map((q) => [
+                ormLabel(q),
+                q.query.length > 48 ? q.query.slice(0, 45) + "…" : q.query,
                 q.calls.toLocaleString(),
                 `${q.meanTimeMs}ms`,
                 q.risk,

package/dist/commands/usage.d.ts

@@ -11,3 +11,14 @@
  *   We will only show a dollar figure for a dimension we genuinely meter.
  */
 export declare function usage(args: string[]): Promise<void>;
+/**
+ * Format an estimated cost for human output. Cost-truth: `null` means "no
+ * compute metered", rendered as "not metered yet" — NEVER "$0.00" (that would
+ * read as a real priced zero). A sub-cent but non-zero estimate is "<$0.01" so
+ * it never collapses to $0.00; sub-dollar keeps 4dp to preserve fractional cents.
+ */
+export declare function estCost(cents: number | null): string;
+export declare function modelActionLabel(q: {
+    model: string | null;
+    action: string | null;
+}): string;

package/dist/commands/usage.js

@@ -14,6 +14,7 @@ import { api, apiError } from "../api.js";
 import { requireToken, isJsonMode } from "../config.js";
 import { colors, log, json, spinner, table, heading, kvList } from "../utils/logger.js";
 import { emitError } from "../utils/errors.js";
+import { resolveProjectId } from "../link.js";
 /**
  * Decide whether a dimension is truly metered. A dimension is metered only when
  * the API explicitly says so (`metered === true`). A missing `metered` field is
@@ -44,15 +45,24 @@ function valueLabel(d) {
     return `${d.value} ${d.unit}`;
 }
 function parseProjectFlag(args) {
+    return parseValueFlag(args, "--project");
+}
+/** Read `--name value` or `--name=value`; undefined if absent. */
+function parseValueFlag(args, name) {
+    const eq = `${name}=`;
     for (let i = 0; i < args.length; i++) {
-        if (args[i] === "--project" && args[i + 1])
+        if (args[i] === name && args[i + 1])
             return args[i + 1];
-        if (args[i].startsWith("--project="))
-            return args[i].slice("--project=".length);
+        if (args[i].startsWith(eq))
+            return args[i].slice(eq.length);
     }
     return undefined;
 }
 export async function usage(args) {
+    // `--by-query` is a per-project cost-attribution view (Lever L1): which ORM
+    // queries drive the project's compute bill. It's estimated, not metered.
+    if (args.includes("--by-query"))
+        return usageByQuery(args);
     const jsonMode = isJsonMode();
     const token = requireToken();
     const projectFilter = parseProjectFlag(args);
@@ -162,3 +172,112 @@ export async function usage(args) {
         log();
     }
 }
+/**
+ * Format an estimated cost for human output. Cost-truth: `null` means "no
+ * compute metered", rendered as "not metered yet" — NEVER "$0.00" (that would
+ * read as a real priced zero). A sub-cent but non-zero estimate is "<$0.01" so
+ * it never collapses to $0.00; sub-dollar keeps 4dp to preserve fractional cents.
+ */
+export function estCost(cents) {
+    if (cents === null)
+        return colors.dim("not metered yet");
+    if (cents <= 0)
+        return "$0.00";
+    const d = cents / 100;
+    if (d < 0.01)
+        return "<$0.01";
+    return `$${d.toFixed(d < 1 ? 4 : 2)}`;
+}
+export function modelActionLabel(q) {
+    if (q.model && q.action)
+        return `${q.model}.${q.action}`;
+    if (q.model)
+        return q.model;
+    if (q.action)
+        return q.action;
+    return colors.dim("raw");
+}
+async function usageByQuery(args) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    // Project precedence: --project flag > .batadata link > config default.
+    const { projectId } = resolveProjectId(parseProjectFlag(args));
+    if (!projectId) {
+        emitError("NO_PROJECT", "No project for --by-query.", "Pass --project <id>, or run `bata link <project>` to set a default.");
+    }
+    const timeRange = parseValueFlag(args, "--window") ?? "24h";
+    const branch = parseValueFlag(args, "--branch");
+    const query = { timeRange, orderBy: "totalTime", limit: "20" };
+    if (branch)
+        query.branch_id = branch;
+    const s = jsonMode ? null : spinner("Attributing compute cost by query");
+    const res = await api.get(`/v1/insights/${projectId}/turbine-queries`, token, query);
+    s?.stop();
+    if (!res.ok) {
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status === 404 ? "NO_PROJECT"
+                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR", apiError(res, "Failed to fetch per-query cost"), "");
+    }
+    const rows = res.data?.queries ?? [];
+    const basis = res.data?.costBasis ?? {
+        method: "no-compute-metered",
+        windowCuMs: 0,
+        windowComputeCents: null,
+        windowTotalTimeMs: 0,
+    };
+    const notMetered = basis.method === "no-compute-metered";
+    if (jsonMode) {
+        json({
+            project_id: projectId,
+            window: timeRange,
+            branch_id: branch ?? null,
+            // Carry the basis so a consumer can always see HOW the estimate was made
+            // and that it is off the billing path.
+            cost_basis: {
+                method: basis.method,
+                estimated: true,
+                window_cu_ms: basis.windowCuMs,
+                window_compute_cents: basis.windowComputeCents,
+                window_total_time_ms: basis.windowTotalTimeMs,
+            },
+            queries: rows.map((q) => ({
+                fingerprint: q.fingerprint,
+                model: q.model,
+                action: q.action,
+                sql_template: q.sqlTemplate,
+                calls: q.calls,
+                mean_time_ms: q.meanTimeMs,
+                time_share: q.costTimeShare,
+                // null (not 0) when nothing was metered — never a priced $0.
+                estimated_cost_cents: q.estimatedCostCents,
+            })),
+        });
+        return;
+    }
+    heading("Cost by query — estimated");
+    log(`  ${colors.dim(`Project ${projectId} · window ${timeRange}${branch ? ` · branch ${branch}` : ""}`)}`);
+    log();
+    if (rows.length === 0) {
+        log(`  ${colors.dim("No ORM query traffic reported in this window.")}`);
+        log(`  ${colors.dim("Wire up createInsightsReporter() to start attributing cost.")}`);
+        log();
+        return;
+    }
+    table(["QUERY", "CALLS", "MEAN", "EST. COST"], rows.map((q) => [
+        modelActionLabel(q),
+        q.calls.toLocaleString(),
+        `${q.meanTimeMs}ms`,
+        estCost(q.estimatedCostCents),
+    ]));
+    log();
+    // Honest footer: never let the estimate masquerade as a metered charge.
+    if (notMetered) {
+        log(`  ${colors.yellow("!")} ${colors.dim("No compute metered in this window — cost can't be attributed to queries yet (never shown as $0).")}`);
+    }
+    else {
+        log(`  ${colors.bold("Window compute:")} ${estCost(basis.windowComputeCents)} ${colors.dim("total (metered)")}`);
+        log(`  ${colors.dim("Per-query figures are ESTIMATES — Turbine insights are off the billing path; compute is apportioned by each query's share of ORM wall-time.")}`);
+    }
+    log();
+}

package/dist/index.js

@@ -11,6 +11,7 @@ import { create } from "./commands/create.js";
 import { status } from "./commands/status.js";
 import { connect } from "./commands/connect.js";
 import { usage } from "./commands/usage.js";
+import { handleRestore } from "./commands/restore.js";
 import { link, unlink } from "./commands/link.js";
 import { parseGlobalFlags } from "./args.js";
 import { isJsonMode } from "./config.js";
@@ -53,6 +54,10 @@ function help() {
     log(`    ${colors.cyan("db studio")}          Open table browser in browser`);
     log(`    ${colors.cyan("db query")}           Run a SQL query ${colors.dim("(--branch <id> to target a branch)")}`);
     log();
+    log(`  ${colors.bold("Restore (PITR)")}`);
+    log(`    ${colors.cyan("restore points")}     List recovery points + the PITR window`);
+    log(`    ${colors.cyan("restore create")}     Restore a branch to a timestamp/LSN ${colors.dim("(creates a NEW branch)")}`);
+    log();
     log(`  ${colors.bold("Schema & Types")}`);
     log(`    ${colors.cyan("generate")}           Generate types from database schema`);
     log(`    ${colors.cyan("generate --watch")}   Watch mode for type generation`);
@@ -78,6 +83,7 @@ function help() {
     log(`    ${colors.cyan("db url --json")}                               Print connection string as JSON`);
     log(`    ${colors.cyan("db query <sql> --json")}                       Run SQL headlessly, rows as JSON objects`);
     log(`    ${colors.cyan("usage --json")}                                Per-dimension cost (honest: un-metered → null)`);
+    log(`    ${colors.cyan("usage --by-query [--project <id>] [--json]")}   Estimated compute cost per ORM query (off billing path)`);
     log();
     log(`    ${colors.dim("All errors in --json mode share one envelope:")} ${colors.dim('{ "error", "code", "hint" }')} ${colors.dim("on stderr.")}`);
     log();
@@ -159,6 +165,10 @@ async function main() {
             case "db":
                 await handleDb(rest);
                 break;
+            // Restore (PITR)
+            case "restore":
+                await handleRestore(rest);
+                break;
             // Schema
             case "schema":
                 await handleSchema(rest);

package/package.json

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