@batadata/cli 0.1.17 → 0.2.1

package/README.md

@@ -87,6 +87,7 @@ flag always wins**, so linking never silently overrides an intentional request:
 | Command | Description |
 |---------|-------------|
 | `create <name>` | Create a project and wait for it to be ready |
+| `import --source <uri>` | Migrate a Postgres/Neon database into BataDB (see [Migrate from Neon](#migrate-from-neon)) |
 | `connect <name>` | Open `psql` to a project (auto-wakes if suspended) |
 | `status` | Show all projects and their status |
 | `usage` | Show per-dimension cost (compute, storage, transfer) for the current period |
@@ -115,6 +116,47 @@ safety.
 
 Run `bata --help` for the full, authoritative command list, or `bata --version`.
 
+## Migrate from Neon
+
+`bata import` moves an existing Postgres database — Neon or anything else — into a
+fresh BataDB project in one command. It shells out to the standard `pg_dump` /
+`psql` client tools (nothing proprietary), streams the dump straight through, and
+verifies the result.
+
+```bash
+bata import --source "postgresql://…@ep-x.neon.tech/neondb"        # → a new project named `neondb`
+bata import --source "$NEON_URL" --name my-app                     # name the new project
+bata import --source "$NEON_URL" --project proj_abc123 --yes       # into an existing project
+```
+
+**Prerequisite:** local `pg_dump` **and** `psql` whose major version is **≥ the
+source server's** (`pg_dump 16` cannot dump a PostgreSQL 17 server). Neon defaults
+to PostgreSQL 17, so install matching client tools:
+
+```bash
+brew install libpq                          # macOS  (or: brew install postgresql@17)
+sudo apt install postgresql-client-17       # Ubuntu
+```
+
+What it does, in order: inspects the source, checks your client tools, creates (or
+resolves) the target project, waits for its compute, **preflights extensions** (any
+source extension the target can't provide hard-fails *before* the restore starts,
+rather than dying mid-restore at `CREATE EXTENSION` and half-importing), streams
+`pg_dump … --encoding=UTF8 | psql` (the `--encoding=UTF8` guarantees a valid-UTF-8
+stream so non-UTF-8 source databases aren't corrupted in transit), then verifies
+every table's row count and every sequence's value on both sides. It exits non-zero
+on any mismatch. Importing into an existing `--project` that already holds user
+objects requires `--yes`. `--json` emits a machine-readable result for agents.
+
+**PostgreSQL 16 vs 17 (honest caveat).** BataDB runs PostgreSQL **16** today; Neon
+defaults to **17**. Standard schemas migrate cleanly — `bata import` transparently
+strips the one PG17-only line `pg_dump` emits (`SET transaction_timeout = 0;`) that
+PG16 would reject. But genuinely **PG17-only** schema features (a data type, syntax,
+or option that only exists in 17) **will fail loudly during restore** — the command
+surfaces the exact `psql` errors and exits non-zero rather than pretending the
+migration succeeded. See [docs/migrate-from-neon.md](../../docs/migrate-from-neon.md)
+for the full guide and the manual `pg_dump | psql` fallback.
+
 ## Point-in-time restore (PITR)
 
 Recover a branch to an earlier point in time. Restore is **non-destructive**: it

package/dist/commands/compute.d.ts

@@ -19,6 +19,19 @@ interface ComputeSetFlags {
  */
 export declare function parseComputeSetFlags(args: string[]): ComputeSetFlags;
 export declare function computeSet(args: string[]): Promise<void>;
+interface ComputeRefFlags {
+    projectId?: string;
+    branchRef?: string;
+    limit?: number;
+}
+/**
+ * Parse args for `compute restart` / `compute logs`. The branch is a positional
+ * `<id|name>` (or `--branch`, matching `compute set`); `--project` overrides the
+ * linked default; `--limit <n>` (logs only) bounds the line count.
+ */
+export declare function parseComputeRefArgs(args: string[]): ComputeRefFlags;
+export declare function computeRestart(args: string[]): Promise<void>;
+export declare function computeLogs(args: string[]): Promise<void>;
 export declare function computeStatus(args: string[]): Promise<void>;
 export declare function handleCompute(args: string[]): Promise<void>;
 export {};

package/dist/commands/compute.js

@@ -133,6 +133,128 @@ export async function computeSet(args) {
     }
     log();
 }
+/**
+ * Parse args for `compute restart` / `compute logs`. The branch is a positional
+ * `<id|name>` (or `--branch`, matching `compute set`); `--project` overrides the
+ * linked default; `--limit <n>` (logs only) bounds the line count.
+ */
+export function parseComputeRefArgs(args) {
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--project")
+            flags.projectId = args[++i];
+        else if (arg.startsWith("--project="))
+            flags.projectId = arg.slice("--project=".length);
+        else if (arg === "--branch")
+            flags.branchRef = args[++i];
+        else if (arg.startsWith("--branch="))
+            flags.branchRef = arg.slice("--branch=".length);
+        else if (arg === "--limit")
+            flags.limit = Number(args[++i]);
+        else if (arg.startsWith("--limit="))
+            flags.limit = Number(arg.slice("--limit=".length));
+        else if (!arg.startsWith("-") && flags.branchRef === undefined)
+            flags.branchRef = arg;
+    }
+    return flags;
+}
+/** Map an API status to the CLI error-code contract (see utils/errors.ts). */
+function computeErrorCode(status) {
+    if (status === 401 || status === 403)
+        return "INVALID_KEY";
+    if (status === 404)
+        return "NOT_FOUND";
+    if (status === 501)
+        return "NOT_IMPLEMENTED";
+    if (status >= 500 || status === 0)
+        return "API_UNAVAILABLE";
+    return "CLI_ERROR";
+}
+/**
+ * Resolve a branch's compute from a `<id|name>` ref, shared by restart/logs.
+ * Emits (and exits) on any failure; returns the resolved handles on success.
+ */
+async function resolveBranchCompute(flags, jsonMode) {
+    if (!flags.branchRef) {
+        emitError("MISSING_ARG", "A branch is required.", "Pass a branch name or id, e.g. bata compute restart main.");
+    }
+    const token = requireToken();
+    const projectId = resolveProjectId(flags.projectId).projectId;
+    if (!projectId) {
+        emitError("NO_PROJECT", "No project.", "Pass --project <id>, or run `bata link <project>` to set a default.");
+    }
+    const teamId = await resolveTeamId(token);
+    const s = jsonMode ? null : spinner(`Resolving branch ${colors.cyan(flags.branchRef)}`);
+    const project = await fetchProject(projectId, token, teamId);
+    if (!project) {
+        s?.stop();
+        emitError("API_UNAVAILABLE", "Failed to fetch project.", "");
+    }
+    const branch = findBranch(project, flags.branchRef);
+    if (!branch) {
+        s?.stop();
+        emitError("BRANCH_NOT_FOUND", `Branch "${flags.branchRef}" not found in this project.`, "List branches with: bata db branches --json");
+    }
+    const compute = branchCompute(branch);
+    if (!compute) {
+        s?.stop();
+        emitError("NOT_FOUND", `Branch "${branch.name}" has no compute yet.`, "Wait for the branch to finish provisioning, then retry.");
+    }
+    s?.stop();
+    return { token, teamId, projectId: projectId, branch: branch, compute: compute };
+}
+export async function computeRestart(args) {
+    const jsonMode = isJsonMode();
+    const flags = parseComputeRefArgs(args);
+    const { token, branch, compute } = await resolveBranchCompute(flags, jsonMode);
+    const res = await api.post(`/v1/computes/${compute.id}/restart`, {}, token);
+    if (!res.ok) {
+        emitError(computeErrorCode(res.status), apiError(res, "Failed to restart compute"), "");
+    }
+    if (jsonMode) {
+        json({
+            compute: {
+                id: compute.id,
+                branch: branch.name,
+                status: res.data.status ?? null,
+                restarted: res.data.restarted ?? true,
+            },
+        });
+        return;
+    }
+    log();
+    log(`  ${colors.green(">")} Compute for branch ${colors.cyan(branch.name)} restarted`);
+    log();
+}
+export async function computeLogs(args) {
+    const jsonMode = isJsonMode();
+    const flags = parseComputeRefArgs(args);
+    if (flags.limit !== undefined && (!Number.isInteger(flags.limit) || flags.limit < 1)) {
+        emitError("INVALID_FLAG", `Invalid --limit ${flags.limit}.`, "Pass a positive integer (max 500).");
+    }
+    const { token, branch, compute } = await resolveBranchCompute(flags, jsonMode);
+    const query = flags.limit !== undefined ? { limit: String(Math.min(flags.limit, 500)) } : undefined;
+    const res = await api.get(`/v1/computes/${compute.id}/logs`, token, query);
+    if (!res.ok) {
+        emitError(computeErrorCode(res.status), apiError(res, "Failed to fetch compute logs"), "");
+    }
+    const lines = res.data.lines ?? [];
+    if (jsonMode) {
+        json({ compute_id: compute.id, branch: branch.name, source: res.data.source, lines });
+        return;
+    }
+    heading(`Logs — ${branch.name} ${colors.dim(`(${res.data.source})`)}`);
+    if (lines.length === 0) {
+        log(`  ${colors.dim("No recent log lines.")}`);
+    }
+    else {
+        for (const line of lines) {
+            log(`  ${colors.dim(line.ts)}  ${line.message}`);
+        }
+    }
+    log();
+}
 export async function computeStatus(args) {
     const jsonMode = isJsonMode();
     const flags = parseComputeSetFlags(args); // reuse --project/--branch parsing
@@ -190,13 +312,17 @@ function computeHelp() {
     log();
     log(`  ${colors.cyan("bata compute status [--project <id>] [--branch <name-or-id>]")}`);
     log(`  ${colors.cyan("bata compute set --branch <name-or-id> [--always-on|--no-always-on] [--size <cu>]")}`);
+    log(`  ${colors.cyan("bata compute restart <name-or-id> [--project <id>]")}`);
+    log(`  ${colors.cyan("bata compute logs <name-or-id> [--limit <n>] [--project <id>]")}`);
     log();
     log(`  ${colors.dim("--always-on / --no-always-on")}  Dedicated always-on primary (no cold starts; flat bill)`);
     log(`  ${colors.dim("--size <cu>")}                   Fixed size: ${DEDICATED_SIZE_CU.join(", ")} CU (512MB, 1GB, 2GB, 4GB, 8GB)`);
+    log(`  ${colors.dim("--limit <n>")}                   Log lines to fetch (default 100, max 500)`);
     log(`  ${colors.dim("--project <id>")}                Target project (else the linked/default project)`);
     log(`  ${colors.dim("--branch <name-or-id>")}         Target branch by name OR id`);
     log();
     log(`  ${colors.dim("Changing --size restarts the compute briefly to apply it.")}`);
+    log(`  ${colors.dim("restart gracefully bounces an active compute in place (stop → start).")}`);
     log();
 }
 export async function handleCompute(args) {
@@ -211,7 +337,11 @@ export async function handleCompute(args) {
         case "status":
         case "info":
             return computeStatus(args.slice(1));
+        case "restart":
+            return computeRestart(args.slice(1));
+        case "logs":
+            return computeLogs(args.slice(1));
         default:
-            emitError("INVALID_FLAG", `Unknown subcommand: compute ${sub}`, "Available: set, status");
+            emitError("INVALID_FLAG", `Unknown subcommand: compute ${sub}`, "Available: set, status, restart, logs");
     }
 }

package/dist/commands/import.d.ts

@@ -0,0 +1,197 @@
+/**
+ * bata import — Neon (or any Postgres) → BataDB migration.
+ *
+ *   bata import --source <postgres-uri> [--project <id> | --name <name>] [--pg <major>] [--yes] [--json]
+ *
+ * Agent-native: shells out to the standard `pg_dump` / `psql` client tools
+ * (zero runtime deps) and streams a dump straight into a fresh BataDB project.
+ *
+ * BataDB runs PostgreSQL 16 today; Neon defaults to 17. A PG17 → PG16
+ * dump/restore is clean for standard schemas EXCEPT that pg_dump 17 emits
+ * `SET transaction_timeout = 0;` — a GUC PG16 doesn't know — into the dump
+ * preamble. We strip that one line (and any future target-unknown GUC SETs)
+ * out of the stream. Genuinely PG17-only schema features still fail loudly at
+ * restore time, and we surface those errors honestly rather than pretending
+ * the migration succeeded.
+ */
+/**
+ * GUC SET statements pg_dump emits that a BataDB (PG16) target rejects. Kept as
+ * an extensible list so a future target-unknown GUC is a one-line addition.
+ * `transaction_timeout` is new in PG17 and is the only one seen in practice.
+ */
+export declare const TARGET_UNKNOWN_GUCS: string[];
+/**
+ * A streaming line filter that drops target-unknown GUC `SET` statements from a
+ * pg_dump stream. It buffers a partial trailing line across chunk boundaries so
+ * a `SET transaction_timeout = 0;` split across two reads is still recognised
+ * and removed. `push()` returns the text to forward to psql for that chunk;
+ * `flush()` returns any buffered final line (a dump without a trailing newline).
+ *
+ * PREAMBLE-ONLY: pg_dump emits the target-unknown GUCs ONLY in the initial
+ * connection preamble (the block of `SET …;` / `SELECT pg_catalog.set_config(…)`
+ * statements at the very top). Filtering the whole stream is unsafe: a dumped
+ * function/procedure body can contain a standalone line `SET transaction_timeout
+ * = 0;` inside its dollar-quoted text, and a COPY data row can be literally
+ * anything — mutating those would silently corrupt the restore. So we only strip
+ * inside the preamble: the first line that is NOT one of {empty, a `--` comment,
+ * `SET …;`, `SELECT pg_catalog.set_config(…);`} permanently ends the preamble,
+ * after which every line passes through verbatim. A GUC-looking SET after the
+ * preamble is therefore NOT stripped — which is correct: transaction_timeout only
+ * ever appears in the preamble; were a future pg_dump to emit it mid-dump, the
+ * restore would fail loudly rather than be silently altered.
+ */
+export declare function makeGucLineFilter(gucs?: string[]): {
+    push: (chunk: string) => string;
+    flush: () => string;
+};
+/**
+ * Extract a PostgreSQL major version from any of the shapes we encounter:
+ *   - `server_version_num` (e.g. "170002", "160003", "90603")
+ *   - dotted `server_version` (e.g. "17.2", "16.3 (Ubuntu 16.3-1.pgdg…)")
+ *   - `pg_dump --version` output ("pg_dump (PostgreSQL) 16.3")
+ * Returns the integer major, or null if none can be found.
+ */
+export declare function parsePgMajor(v: string): number | null;
+/** A client tool must be at least the source major (pg_dump can't dump a newer
+ *  server than itself; psql can't parse a newer pg_dump's meta-commands). */
+export declare function toolMajorSatisfies(toolMajor: number, sourceMajor: number): boolean;
+/** Clear, actionable message when a local client tool is too old for the source. */
+export declare function toolVersionErrorMessage(tool: string, toolMajor: number, sourceMajor: number): string;
+/** Message when psql can't restore the stream THIS pg_dump produces. */
+export declare function psqlVsDumpErrorMessage(psqlMajor: number, dumpMajor: number): string;
+/**
+ * Verdict on whether the local client tools can migrate a source of `sourceMajor`
+ * (null when the source version couldn't be parsed). Rules:
+ *   - pg_dump must be ≥ source (can't dump a newer server than itself)
+ *   - psql must be ≥ source AND ≥ pg_dump — the restore stream is produced by the
+ *     LOCAL pg_dump, and pg_dump 17 emits \restrict/\unrestrict regardless of the
+ *     source version, so psql 16 + pg_dump 17 fails even against a PG16 source.
+ * Effectively psql must satisfy max(sourceMajor, dumpMajor). Returns the install
+ * target so the caller can point the user at the right client package.
+ */
+export declare function checkClientVersions(dumpMajor: number, psqlMajor: number, sourceMajor: number | null): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    needMajor: number;
+};
+/** Pull the first meaningful line out of a psql connection error for the user. */
+export declare function sourcePreflightErrorMessage(stderr: string): string;
+/** Default target project name = the source database name, else the URI path. */
+export declare function defaultProjectName(preflightDb: string | undefined, sourceUri: string): string;
+export interface CountRow {
+    name: string;
+    source: string;
+    target: string;
+}
+/**
+ * Compare two name→value maps (table row counts, or sequence last_values) and
+ * return only the mismatches. A name present on one side but not the other is a
+ * mismatch too (rendered as ∅). Deterministically sorted by name.
+ */
+export declare function diffCounts(source: Map<string, string>, target: Map<string, string>): CountRow[];
+/** Build the `table()` rows for a verify mismatch report (tables + sequences). */
+export declare function mismatchRows(tableRows: CountRow[], seqRows: CountRow[]): string[][];
+/** Double-quote a SQL identifier (escaping embedded quotes). */
+export declare function quoteIdent(id: string): string;
+/**
+ * Map a child process 'close' `(code, signal)` to the numeric exit used for the
+ * migration verdict. A signal death (`code === null`, e.g. OOM-killer or an
+ * operator `kill`) is a FAILURE — it must never read as success just because its
+ * peer exited cleanly. The one exception: when WE deliberately SIGTERM'd the dump
+ * after a restore failure (`intentionalKill`), that path already has a nonzero
+ * restoreCode so the overall verdict is false regardless; we normalize to 0 to
+ * avoid a redundant, confusing error line.
+ */
+export declare function resolveChildExit(code: number | null, signal: string | null, opts?: {
+    intentionalKill?: boolean;
+}): {
+    code: number;
+    error?: string;
+};
+/**
+ * Source extensions the target can't satisfy = source extensions not in the
+ * target's available set. `plpgsql` is built into every PostgreSQL and always
+ * present, so it's excluded — it can never be a real gap even though it shows up
+ * in pg_extension. Used both for the pre-restore availability gate (against
+ * `pg_available_extensions`) and the residual post-restore warning (against the
+ * target's installed `pg_extension`).
+ */
+export declare function missingExtensions(sourceExts: string[], targetHasExts: string[]): string[];
+/**
+ * Objects BataDB's provisioning seeds into EVERY new project — platform furniture,
+ * not user data. Because a freshly created target ALWAYS contains these, they must
+ * be excluded from all TARGET-side "unexpected object" accounting: the
+ * created-project hard-fail, the existing-target leftover warnings/JSON, and the
+ * `--yes` non-empty guard (a target holding ONLY these is effectively empty). They
+ * are NEVER excluded on the SOURCE side — a source `public.health_check` (or a
+ * source `neon_migration` schema, e.g. a migration FROM another BataDB) is treated
+ * as real data and must verify normally.
+ *
+ * Two flavours:
+ *  - Named objects: `public.health_check` (+ its sequence) — the data-path
+ *    health-check row/table seeded on provision.
+ *  - Whole schemas: `neon_migration` — our Neon-derived compute engine's
+ *    compute_ctl records applied internal SQL migrations here (table
+ *    `neon_migration.migration_id`) on EVERY compute startup. Real Neon hides this
+ *    schema from customer `pg_tables`; our compute exposes it, so ANY object under
+ *    `neon_migration.*` is platform furniture, never user data.
+ */
+export declare const PLATFORM_SCAFFOLDING_TABLES: string[];
+export declare const PLATFORM_SCAFFOLDING_SEQUENCES: string[];
+/** Schemas whose ENTIRE contents are platform furniture (any `<schema>.*` object). */
+export declare const PLATFORM_SCAFFOLDING_SCHEMAS: string[];
+/**
+ * Merge the server-published scaffolding list (GET /v1/platform/import-scaffolding)
+ * into the baked-in defaults above. The server is the source of truth going
+ * forward — if provisioning grows new furniture, an already-installed CLI keeps
+ * verifying correctly instead of false-failing on it. Union (never replace): the
+ * baked defaults still apply against an older control plane, and a partial or
+ * malformed server response can only ever ADD exclusions it explicitly names.
+ * The exported const arrays are extended in place so every existing reference
+ * (the --yes guard, the created-target check, verify) sees the merged lists.
+ */
+export declare function applyServerScaffolding(server: {
+    tables?: unknown;
+    sequences?: unknown;
+    schemas?: unknown;
+}): void;
+/** Is this qualified name one of BataDB's seeded platform-scaffolding objects —
+ *  either an exact named object, or anything inside a scaffolding schema? */
+export declare function isPlatformScaffolding(qualifiedName: string): boolean;
+/** Drop platform-scaffolding names — applied ONLY to TARGET-side object lists,
+ *  never to source accounting. */
+export declare function excludeScaffolding(names: string[]): string[];
+/**
+ * Scaffolding names that appear in a SOURCE object list — i.e. a user table that
+ * shares a name with BataDB's seeded platform table. On restore that `CREATE
+ * TABLE` clashes with the scaffolding already present on the target: with
+ * ON_ERROR_STOP the restore fails ("relation already exists" → RESTORE_FAILED),
+ * or, if the schemas happen to be compatible, rows append and the row-count verify
+ * catches the drift. Either way verify stays honest — the source name is NOT
+ * excluded from source accounting; we only warn the user up front.
+ */
+export declare function scaffoldingCollisions(sourceQualifiedNames: string[]): string[];
+/**
+ * Qualified names present on the TARGET but absent from the source — used for both
+ * tables and sequences. Verification only enumerates SOURCE objects, so on a
+ * `--project --yes` import into a non-empty target these are invisible to the
+ * count/value checks: they were left untouched and aren't covered by verify.
+ * Surfaced honestly (a warning for an existing target; unexpected for a freshly
+ * created one). Sorted, deduped by set.
+ */
+export declare function targetOnlyNames(sourceQualified: string[], targetQualified: string[]): string[];
+export declare function parseImportArgs(args: string[]): {
+    source?: string;
+    projectId?: string;
+    name?: string;
+    pg?: string;
+    help: boolean;
+} | {
+    error: string;
+};
+/** Default target major for a new project: match the source so features survive,
+ *  capped at what BataDB ships (a PG18 source → 17, a PG16 or older source → 16). */
+export declare function defaultTargetPg(sourceMajor: number): string;
+export declare function importDb(args: string[]): Promise<void>;