@batadata/cli 0.1.17 → 0.2.1

package/dist/commands/import.js

@@ -0,0 +1,1316 @@
+/**
+ * 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.
+ */
+import { spawn, spawnSync, execSync } from "node:child_process";
+import { URL } from "node:url";
+import { api, apiError, resolveTeamId, asList } from "../api.js";
+import { requireToken, loadConfig, isJsonMode, isYes } from "../config.js";
+import { colors, log, json, success, warn, heading, kvList, table } from "../utils/logger.js";
+import { emitError } from "../utils/errors.js";
+// ── Pure, unit-tested helpers ────────────────────────────────────────────────
+/**
+ * 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 const TARGET_UNKNOWN_GUCS = ["transaction_timeout"];
+/**
+ * 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 function makeGucLineFilter(gucs = TARGET_UNKNOWN_GUCS) {
+    // `^SET <guc> …;` — a standalone GUC SET statement. Anchored to the start of
+    // the line and requiring the trailing semicolon so it can't match a data row
+    // that merely begins with the same text.
+    const patterns = gucs.map((g) => new RegExp(`^SET\\s+${g}\\b[^\\n]*;\\s*$`, "i"));
+    const isStripped = (line) => patterns.some((re) => re.test(line));
+    // Lines that legitimately appear in the preamble; the first line that matches
+    // NONE of these ends the preamble for good. `\restrict <token>` is a psql
+    // meta-command pg_dump 17.x emits at the top (paired with `\unrestrict` at the
+    // very end) — it sits BEFORE the GUC SETs, so it must be recognised or the
+    // preamble would end early and the GUC we strip would sail through untouched.
+    const PREAMBLE_LINE = [
+        /^\s*$/, // blank
+        /^--/, // SQL comment
+        /^\\(un)?restrict\b/i, // psql \restrict / \unrestrict (PG17.x)
+        /^SET\s.+;\s*$/i, // any GUC SET (incl. the ones we strip)
+        /^SELECT\s+pg_catalog\.set_config\(.*\);\s*$/i, // set_config form
+    ];
+    const isPreambleLine = (line) => PREAMBLE_LINE.some((re) => re.test(line));
+    let preambleDone = false;
+    let pending = "";
+    // Whether a preamble line survives (updating the preambleDone latch). Only
+    // called while still in the preamble.
+    const keepPreambleLine = (raw) => {
+        const line = raw.replace(/\r$/, "");
+        if (!isPreambleLine(line)) {
+            preambleDone = true; // first non-preamble line ends filtering permanently
+            return true;
+        }
+        return !isStripped(line);
+    };
+    return {
+        push(chunk) {
+            // Once out of the preamble, bypass line-splitting entirely and stream the
+            // chunk through verbatim. Buffering-until-newline here would hold a single
+            // huge COPY value (a multi-MB TOAST row on one line) entirely in memory and
+            // defeat backpressure — the body is never filtered, so there's no reason to
+            // reassemble its lines.
+            if (preambleDone)
+                return chunk;
+            pending += chunk;
+            const lines = pending.split("\n");
+            // The final element has no terminating newline yet — hold it for next push.
+            pending = lines.pop() ?? "";
+            let out = "";
+            for (let i = 0; i < lines.length; i++) {
+                if (keepPreambleLine(lines[i]))
+                    out += lines[i] + "\n";
+                // The moment the preamble ends, everything remaining in this chunk is
+                // body — emit it verbatim (with its newlines) and stop line-processing.
+                if (preambleDone) {
+                    const rest = lines.slice(i + 1);
+                    if (rest.length > 0)
+                        out += rest.join("\n") + "\n";
+                    if (pending) {
+                        out += pending;
+                        pending = "";
+                    }
+                    break;
+                }
+            }
+            return out;
+        },
+        flush() {
+            // After the preamble, push() already emitted everything (pending is empty).
+            const last = pending;
+            pending = "";
+            if (!last)
+                return "";
+            // A dump that is ALL preamble (no trailing newline on the last line).
+            return keepPreambleLine(last) ? last : "";
+        },
+    };
+}
+/**
+ * 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 function parsePgMajor(v) {
+    const t = (v ?? "").trim();
+    // server_version_num form: all digits, wide enough to be an encoded version.
+    if (/^\d+$/.test(t) && t.length >= 5) {
+        return Math.floor(parseInt(t, 10) / 10000);
+    }
+    const m = t.match(/(\d+)/);
+    return m ? parseInt(m[1], 10) : 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 function toolMajorSatisfies(toolMajor, sourceMajor) {
+    return toolMajor >= sourceMajor;
+}
+/** Clear, actionable message when a local client tool is too old for the source. */
+export function toolVersionErrorMessage(tool, toolMajor, sourceMajor) {
+    return (`Your ${tool} is version ${toolMajor}, but the source server is PostgreSQL ${sourceMajor}. ` +
+        `A client older than the source can't reliably migrate it (e.g. psql ${sourceMajor - 1} can't parse ` +
+        `pg_dump ${sourceMajor}'s \\restrict meta-commands). Install PostgreSQL ${sourceMajor} (or newer) ` +
+        `client tools and re-run.`);
+}
+/** Message when psql can't restore the stream THIS pg_dump produces. */
+export function psqlVsDumpErrorMessage(psqlMajor, dumpMajor) {
+    return (`Your psql is version ${psqlMajor}, but pg_dump is version ${dumpMajor} — psql can't reliably ` +
+        `restore a stream produced by a newer pg_dump (pg_dump ${dumpMajor} emits \\restrict meta-commands ` +
+        `psql ${psqlMajor} doesn't understand). Install matching PostgreSQL ${dumpMajor} client tools and re-run.`);
+}
+/**
+ * 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 function checkClientVersions(dumpMajor, psqlMajor, sourceMajor) {
+    if (sourceMajor !== null && !toolMajorSatisfies(dumpMajor, sourceMajor)) {
+        return { ok: false, message: toolVersionErrorMessage("pg_dump", dumpMajor, sourceMajor), needMajor: sourceMajor };
+    }
+    if (sourceMajor !== null && !toolMajorSatisfies(psqlMajor, sourceMajor)) {
+        return { ok: false, message: toolVersionErrorMessage("psql", psqlMajor, sourceMajor), needMajor: sourceMajor };
+    }
+    if (!toolMajorSatisfies(psqlMajor, dumpMajor)) {
+        return { ok: false, message: psqlVsDumpErrorMessage(psqlMajor, dumpMajor), needMajor: dumpMajor };
+    }
+    return { ok: true };
+}
+/** Pull the first meaningful line out of a psql connection error for the user. */
+export function sourcePreflightErrorMessage(stderr) {
+    const line = (stderr ?? "")
+        .split("\n")
+        .map((s) => s.trim())
+        .find((s) => s.length > 0);
+    return line
+        ? line.replace(/^psql:\s*(error:\s*)?/i, "")
+        : "Could not connect to the source database.";
+}
+/** Default target project name = the source database name, else the URI path. */
+export function defaultProjectName(preflightDb, sourceUri) {
+    if (preflightDb && preflightDb.trim())
+        return preflightDb.trim();
+    try {
+        const p = new URL(sourceUri).pathname.replace(/^\//, "");
+        if (p)
+            return p;
+    }
+    catch {
+        /* not a parseable URL — fall through */
+    }
+    return "imported-db";
+}
+/**
+ * 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 function diffCounts(source, target) {
+    const names = new Set([...source.keys(), ...target.keys()]);
+    const rows = [];
+    for (const name of [...names].sort()) {
+        const s = source.get(name) ?? "∅";
+        const t = target.get(name) ?? "∅";
+        if (s !== t)
+            rows.push({ name, source: s, target: t });
+    }
+    return rows;
+}
+/** Build the `table()` rows for a verify mismatch report (tables + sequences). */
+export function mismatchRows(tableRows, seqRows) {
+    return [
+        ...tableRows.map((r) => [`table ${r.name}`, r.source, r.target]),
+        ...seqRows.map((r) => [`seq ${r.name}`, r.source, r.target]),
+    ];
+}
+/** Double-quote a SQL identifier (escaping embedded quotes). */
+export function quoteIdent(id) {
+    return `"${id.replace(/"/g, '""')}"`;
+}
+/**
+ * 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 function resolveChildExit(code, signal, opts = {}) {
+    if (code !== null)
+        return { code };
+    if (opts.intentionalKill)
+        return { code: 0 };
+    return { code: -1, error: `terminated by signal ${signal ?? "(unknown)"}` };
+}
+/**
+ * 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 function missingExtensions(sourceExts, targetHasExts) {
+    const has = new Set(targetHasExts);
+    return sourceExts.filter((e) => e !== "plpgsql" && !has.has(e));
+}
+/**
+ * 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 const PLATFORM_SCAFFOLDING_TABLES = ["public.health_check"];
+export const PLATFORM_SCAFFOLDING_SEQUENCES = ["public.health_check_id_seq"];
+/** Schemas whose ENTIRE contents are platform furniture (any `<schema>.*` object). */
+export const PLATFORM_SCAFFOLDING_SCHEMAS = ["neon_migration"];
+let PLATFORM_SCAFFOLDING_NAMES = new Set([
+    ...PLATFORM_SCAFFOLDING_TABLES,
+    ...PLATFORM_SCAFFOLDING_SEQUENCES,
+]);
+let PLATFORM_SCAFFOLDING_SCHEMA_PREFIXES = PLATFORM_SCAFFOLDING_SCHEMAS.map((s) => `${s}.`);
+/**
+ * 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 function applyServerScaffolding(server) {
+    const merge = (into, from) => {
+        if (!Array.isArray(from))
+            return;
+        for (const v of from) {
+            if (typeof v === "string" && v.length > 0 && !into.includes(v))
+                into.push(v);
+        }
+    };
+    merge(PLATFORM_SCAFFOLDING_TABLES, server.tables);
+    merge(PLATFORM_SCAFFOLDING_SEQUENCES, server.sequences);
+    merge(PLATFORM_SCAFFOLDING_SCHEMAS, server.schemas);
+    PLATFORM_SCAFFOLDING_NAMES = new Set([
+        ...PLATFORM_SCAFFOLDING_TABLES,
+        ...PLATFORM_SCAFFOLDING_SEQUENCES,
+    ]);
+    PLATFORM_SCAFFOLDING_SCHEMA_PREFIXES = PLATFORM_SCAFFOLDING_SCHEMAS.map((s) => `${s}.`);
+}
+/** Is this qualified name one of BataDB's seeded platform-scaffolding objects —
+ *  either an exact named object, or anything inside a scaffolding schema? */
+export function isPlatformScaffolding(qualifiedName) {
+    if (PLATFORM_SCAFFOLDING_NAMES.has(qualifiedName))
+        return true;
+    return PLATFORM_SCAFFOLDING_SCHEMA_PREFIXES.some((p) => qualifiedName.startsWith(p));
+}
+/** Drop platform-scaffolding names — applied ONLY to TARGET-side object lists,
+ *  never to source accounting. */
+export function excludeScaffolding(names) {
+    return names.filter((n) => !isPlatformScaffolding(n));
+}
+/**
+ * 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 function scaffoldingCollisions(sourceQualifiedNames) {
+    return sourceQualifiedNames.filter((n) => isPlatformScaffolding(n));
+}
+/**
+ * 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 function targetOnlyNames(sourceQualified, targetQualified) {
+    const source = new Set(sourceQualified);
+    return targetQualified.filter((t) => !source.has(t)).sort();
+}
+/** Single-quote a SQL string literal (escaping embedded quotes). */
+function quoteLiteral(s) {
+    return `'${s.replace(/'/g, "''")}'`;
+}
+/** Split an array into fixed-size batches (used to bound verify query size). */
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/**
+ * Run a one-shot capture query with `psql -Atc`. `-X` skips ~/.psqlrc so a user's
+ * custom formatting / field separators / pager can't silently break the -Atc
+ * parsers; `-w` never prompts for a password.
+ */
+function runPsql(uri, sql) {
+    const res = spawnSync("psql", [uri, "-X", "-w", "-Atc", sql], {
+        encoding: "utf8",
+        env: { ...process.env, PGCONNECT_TIMEOUT: process.env.PGCONNECT_TIMEOUT ?? "10" },
+        maxBuffer: 128 * 1024 * 1024,
+    });
+    if (res.error)
+        return { code: -1, stdout: "", stderr: res.error.message };
+    return { code: res.status ?? -1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+/** Is a client tool on PATH? Mirrors `bata connect`'s `which` probe. */
+function hasTool(name) {
+    try {
+        execSync(`which ${name}`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The local pg_dump major version, or null if it can't be determined. */
+function pgDumpMajor() {
+    const res = spawnSync("pg_dump", ["--version"], { encoding: "utf8" });
+    if ((res.status ?? -1) !== 0 || !res.stdout)
+        return null;
+    return parsePgMajor(res.stdout);
+}
+/** The local psql major version, or null if it can't be determined. */
+function psqlMajor() {
+    const res = spawnSync("psql", ["--version"], { encoding: "utf8" });
+    if ((res.status ?? -1) !== 0 || !res.stdout)
+        return null;
+    return parsePgMajor(res.stdout);
+}
+/** Parse `psql -At` `key|value` rows into a Map. */
+function parseKvRows(stdout) {
+    const m = new Map();
+    for (const line of stdout.split("\n")) {
+        if (!line)
+            continue;
+        const idx = line.indexOf("|");
+        if (idx === -1)
+            continue;
+        m.set(line.slice(0, idx), line.slice(idx + 1));
+    }
+    return m;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Stream `pg_dump <source>` → GUC filter → `psql <target> -v ON_ERROR_STOP=1`.
+ * Nothing is buffered whole; the dump flows chunk-by-chunk. Deliberately NOT
+ * --single-transaction: one giant transaction through a serverless proxy is
+ * fragile. Collects restore stderr (the actionable errors, e.g. a PG17-only
+ * feature) and resolves ok only when both processes exit 0.
+ */
+function runMigration(sourceUri, targetUri) {
+    return new Promise((resolve) => {
+        const filter = makeGucLineFilter();
+        const env = { ...process.env, PGCONNECT_TIMEOUT: process.env.PGCONNECT_TIMEOUT ?? "10" };
+        // `--encoding=UTF8` is load-bearing: the dump stream passes through JS strings
+        // here (dump.stdout is decoded as utf8 so the line filter can operate on text).
+        // Without it, a LATIN1 (or any non-UTF-8) source database's non-ASCII bytes
+        // would be replacement-mangled during that decode BEFORE reaching psql — silent
+        // data corruption that row-count verify wouldn't catch. Forcing UTF8 makes the
+        // server convert, guaranteeing a valid-UTF-8 stream; the dump carries
+        // `SET client_encoding = 'UTF8';`, which restores correctly into any target.
+        const dump = spawn("pg_dump", [sourceUri, "--no-owner", "--no-privileges", "--encoding=UTF8"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env,
+        });
+        // `-X` skips ~/.psqlrc: a user's custom settings (e.g. AUTOCOMMIT off, a
+        // different ON_ERROR_ROLLBACK, output tweaks) must not change restore
+        // semantics. `-w` never prompts for a password.
+        const restore = spawn("psql", [targetUri, "-X", "-w", "-v", "ON_ERROR_STOP=1"], {
+            stdio: ["pipe", "ignore", "pipe"],
+            env,
+        });
+        let restoreAlive = true;
+        const restoreErr = [];
+        let dumpErr = "";
+        let dumpCode = null;
+        let restoreCode = null;
+        let settled = false;
+        // Set true exactly where WE SIGTERM the dump after a restore failure, so the
+        // dump 'close' handler can tell our deliberate kill from an external one.
+        let intentionalDumpKill = false;
+        // Backpressure contract: psql can restore slower than pg_dump produces
+        // (index builds, TOAST writes, fsync). If we ignored write()'s return value,
+        // an unbounded backlog would buffer the ENTIRE dump in CLI memory and OOM on
+        // a multi-GB source. So when psql's stdin buffer is full (write() === false),
+        // pause the dump and resume only on 'drain'. This caps memory at ~one dump
+        // chunk plus psql's own buffer.
+        const safeWrite = (s) => {
+            if (!restoreAlive || !s)
+                return;
+            try {
+                if (!restore.stdin.write(s))
+                    dump.stdout.pause();
+            }
+            catch {
+                /* psql closed its stdin (early exit) — stop feeding it */
+            }
+        };
+        restore.stdin.on("drain", () => {
+            if (restoreAlive)
+                dump.stdout.resume();
+        });
+        dump.stdout.setEncoding("utf8");
+        dump.stdout.on("data", (chunk) => safeWrite(filter.push(chunk)));
+        dump.stdout.on("end", () => {
+            safeWrite(filter.flush());
+            if (restoreAlive) {
+                try {
+                    restore.stdin.end();
+                }
+                catch {
+                    /* already closed */
+                }
+            }
+        });
+        dump.stderr.setEncoding("utf8");
+        dump.stderr.on("data", (d) => {
+            dumpErr += d;
+        });
+        restore.stderr.setEncoding("utf8");
+        restore.stderr.on("data", (d) => {
+            for (const line of d.split("\n")) {
+                const t = line.trim();
+                if (t)
+                    restoreErr.push(t);
+            }
+        });
+        restore.stdin.on("error", () => {
+            /* EPIPE when psql exits before we finish writing — expected on failure */
+        });
+        const maybeSettle = () => {
+            if (settled || dumpCode === null || restoreCode === null)
+                return;
+            settled = true;
+            const ok = dumpCode === 0 && restoreCode === 0;
+            const errors = restoreErr.slice(0, 12);
+            if (dumpCode !== 0 && dumpErr.trim()) {
+                errors.push(...dumpErr
+                    .trim()
+                    .split("\n")
+                    .map((s) => s.trim())
+                    .filter(Boolean)
+                    .slice(0, 4));
+            }
+            resolve({ ok, errors });
+        };
+        dump.on("error", (e) => {
+            dumpErr += `pg_dump failed to start: ${e.message}\n`;
+            dumpCode = dumpCode ?? -1;
+            restoreAlive = false;
+            try {
+                restore.stdin.end();
+            }
+            catch {
+                /* noop */
+            }
+            maybeSettle();
+        });
+        restore.on("error", (e) => {
+            restoreErr.push(`psql failed to start: ${e.message}`);
+            restoreCode = restoreCode ?? -1;
+            maybeSettle();
+        });
+        dump.on("close", (code, signal) => {
+            // A signal death (code === null) is a FAILURE — an OOM-killed or externally
+            // terminated pg_dump must not read as success just because psql exited
+            // cleanly. The ONLY exception is our own deliberate SIGTERM after a restore
+            // failure: restoreCode is already nonzero there so `ok` stays false anyway,
+            // and we normalize to 0 to avoid a redundant error line. On restore SUCCESS
+            // we never kill the dump — it closes naturally and its REAL exit code is
+            // honored here, so a late pg_dump failure can't be masked into success.
+            const r = resolveChildExit(code, signal, { intentionalKill: intentionalDumpKill });
+            if (r.error)
+                dumpErr += `pg_dump ${r.error}\n`;
+            dumpCode = r.code;
+            maybeSettle();
+        });
+        restore.on("close", (code, signal) => {
+            restoreAlive = false;
+            // A signal death is likewise a failure (never success on an external kill).
+            const r = resolveChildExit(code, signal);
+            if (r.error)
+                restoreErr.push(`psql ${r.error}`);
+            restoreCode = r.code;
+            // Kill the dump ONLY when the restore FAILED: a failed psql means no 'drain'
+            // will ever come, so a backpressure-paused pg_dump would hang forever and
+            // maybeSettle() would wait on dumpCode indefinitely — and its remaining
+            // output is useless anyway. On restore SUCCESS we deliberately do NOT kill:
+            // let pg_dump finish and report its real exit code, so maybeSettle (which
+            // waits for both) catches a late dump failure instead of hiding it.
+            if (restoreCode !== 0) {
+                intentionalDumpKill = true;
+                try {
+                    dump.kill("SIGTERM");
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            maybeSettle();
+        });
+    });
+}
+/**
+ * Delete a project we created for this import (DELETE /v1/projects/:id — the same
+ * endpoint `bata projects delete` uses). Returns whether it was actually removed,
+ * so the caller can tell the user to clean up manually if it wasn't. Only ever
+ * called for a project THIS run created — never a pre-existing --project target.
+ */
+async function deleteCreatedProject(projectId, token, teamId) {
+    const query = {};
+    if (teamId)
+        query.team_id = teamId;
+    try {
+        const res = await api.del(`/v1/projects/${projectId}`, token, query);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** Fetch the primary branch's usable (password-revealed) direct URI — the same
+ *  path `bata connect` / `bata db url` use. Never fabricated locally. */
+async function getTargetUri(projectId, token) {
+    const res = await api.get(`/v1/connection-info/${projectId}`, token, { reveal: "true" });
+    if (!res.ok)
+        return null;
+    const conns = res.data?.connections ?? [];
+    const c = conns.find((x) => x.is_primary) ?? conns[0];
+    return c?.direct ?? null;
+}
+/**
+ * Poll GET /v1/branches?project_id= until the primary compute is ready. Cold
+ * attach can take 40s+, so the budget is patient (~180s). Falls back to a real
+ * `SELECT 1` probe once past the warm-up window, since a working query is the
+ * true readiness signal even if the `ready` flag lags.
+ */
+async function waitForReady(projectId, targetUri, token, teamId, onTick) {
+    const budget = 180_000;
+    const interval = 3_000;
+    const probeAfter = 30_000;
+    const start = Date.now();
+    while (Date.now() - start < budget) {
+        const query = { project_id: projectId };
+        if (teamId)
+            query.team_id = teamId;
+        const res = await api.get("/v1/branches", token, query);
+        if (res.ok) {
+            const branches = asList(res.data);
+            const primary = branches.find((b) => b.isPrimary ?? b.is_primary) ?? branches[0];
+            if (primary?.ready === true)
+                return true;
+        }
+        if (Date.now() - start > probeAfter && runPsql(targetUri, "SELECT 1").code === 0) {
+            return true;
+        }
+        onTick(Math.round((Date.now() - start) / 1000));
+        await sleep(interval);
+    }
+    // Last chance: a successful query means ready regardless of the flag.
+    return runPsql(targetUri, "SELECT 1").code === 0;
+}
+// ── Command ──────────────────────────────────────────────────────────────────
+export function parseImportArgs(args) {
+    let source;
+    let projectId;
+    let name;
+    let pg;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const takeVal = () => {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith("-"))
+                return undefined;
+            i++;
+            return next;
+        };
+        if (a === "--help" || a === "-h")
+            help = true;
+        else if (a === "--source") {
+            const v = takeVal();
+            if (v === undefined)
+                return { error: "--source requires a value (a postgres:// connection URI)." };
+            source = v;
+        }
+        else if (a.startsWith("--source="))
+            source = a.slice("--source=".length);
+        else if (a === "--project") {
+            const v = takeVal();
+            if (v === undefined)
+                return { error: "--project requires a value (a project id)." };
+            projectId = v;
+        }
+        else if (a.startsWith("--project="))
+            projectId = a.slice("--project=".length);
+        else if (a === "--name") {
+            const v = takeVal();
+            if (v === undefined)
+                return { error: "--name requires a value." };
+            name = v;
+        }
+        else if (a.startsWith("--name="))
+            name = a.slice("--name=".length);
+        else if (a === "--pg") {
+            const v = takeVal();
+            if (v === undefined)
+                return { error: "--pg requires a value (a PostgreSQL major, e.g. 17)." };
+            pg = v;
+        }
+        else if (a.startsWith("--pg="))
+            pg = a.slice("--pg=".length);
+        // Unknown tokens / positionals are ignored — --source is the only input.
+    }
+    if (pg !== undefined && !/^\d+$/.test(pg)) {
+        return { error: `--pg must be a PostgreSQL major version number (got "${pg}").` };
+    }
+    // --pg picks the version of a NEW project; an existing project's version is fixed.
+    if (pg !== undefined && projectId !== undefined && !help) {
+        return { error: "--pg only applies when creating a new project — it cannot change an existing --project's version." };
+    }
+    // --project (import into an existing project) and --name (create a new one) are
+    // opposite intents. Silently taking --project was the riskier read (mutating an
+    // existing project while ignoring the requested name) — make it an explicit error.
+    if (projectId !== undefined && name !== undefined && !help) {
+        return {
+            error: "--project and --name are mutually exclusive (import into an existing project OR create a new one).",
+        };
+    }
+    return { source, projectId, name, pg, help };
+}
+/** Highest PostgreSQL major BataDB can create today — used only to pick the
+ *  DEFAULT version for a new import target (min(source major, this), floored at
+ *  16). An explicit --pg is passed through as-is and validated by the API's
+ *  allowlist, so a newer server accepts newer majors without a CLI release. */
+const HIGHEST_SUPPORTED_PG = 17;
+/** 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 function defaultTargetPg(sourceMajor) {
+    return String(Math.max(16, Math.min(sourceMajor, HIGHEST_SUPPORTED_PG)));
+}
+function printHelp() {
+    log();
+    log(`  ${colors.bold("bata import")} ${colors.dim("--source <postgres-uri> [--project <id> | --name <name>] [--pg <major>]")}`);
+    log();
+    log(`  Migrate a Neon (or any Postgres) database into BataDB via pg_dump | psql.`);
+    log();
+    log(`  ${colors.bold("Options")}`);
+    log(`    ${colors.dim("--source <uri>")}    Source Postgres connection URI ${colors.dim("(required)")}`);
+    log(`    ${colors.dim("--project <id>")}    Import into an existing BataDB project`);
+    log(`    ${colors.dim("--name <name>")}     Create a new project with this name ${colors.dim("(default: source db name)")}`);
+    log(`    ${colors.dim("--pg <major>")}      PostgreSQL major for a NEW project ${colors.dim("(default: match the source, capped at 17)")}`);
+    log(`    ${colors.dim("--yes, -y")}         Proceed even if the target already has tables`);
+    log(`    ${colors.dim("--json")}            Machine-readable result`);
+    log();
+    log(`  ${colors.bold("Prerequisites")}`);
+    log(`    Local ${colors.cyan("pg_dump")} + ${colors.cyan("psql")} whose major ≥ the source server's.`);
+    log(`    ${colors.dim("macOS:")} ${colors.cyan("brew install libpq")}   ${colors.dim("Ubuntu:")} ${colors.cyan("sudo apt install postgresql-client-17")}`);
+    log();
+    log(`  ${colors.bold("Examples")}`);
+    log(`    ${colors.cyan('bata import --source "postgresql://…@ep-x.neon.tech/neondb"')}`);
+    log(`    ${colors.cyan('bata import --source "$NEON_URL" --name my-app --yes --json')}`);
+    log();
+    log(`  ${colors.dim("BataDB runs PostgreSQL 16 and 17. A new target defaults to the source's")}`);
+    log(`  ${colors.dim("major (capped at 17); features newer than the target fail loudly during")}`);
+    log(`  ${colors.dim("restore (nothing is hidden).")}`);
+    log();
+}
+export async function importDb(args) {
+    const parsed = parseImportArgs(args);
+    if ("error" in parsed) {
+        emitError("INVALID_FLAG", parsed.error, "Run `bata import --help` for usage.");
+        return;
+    }
+    if (parsed.help) {
+        printHelp();
+        return;
+    }
+    if (!parsed.source) {
+        emitError("MISSING_ARG", "A source database is required.", "Pass --source <postgres-uri>. Run `bata import --help` for usage.");
+        return;
+    }
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    const config = loadConfig();
+    const source = parsed.source;
+    const phase = (msg) => {
+        if (!jsonMode)
+            log(`  ${colors.cyan("›")} ${msg}`);
+    };
+    if (!jsonMode)
+        heading("Import into BataDB");
+    // Ask the control plane for the current platform-scaffolding list (tables/
+    // sequences/schemas provisioning seeds into every project) and merge it into
+    // the baked-in defaults, so every downstream consumer — the source-collision
+    // warning, the --yes non-empty guard, and verification — keeps excluding the
+    // platform's own furniture even when it grows after this CLI was installed.
+    // Best-effort: any failure — older server (404), network error, or a transport
+    // THROW (timeout/DNS) — silently keeps the defaults; it must never abort the run.
+    try {
+        const scaffRes = await api.get("/v1/platform/import-scaffolding", token);
+        if (scaffRes.ok && scaffRes.data && typeof scaffRes.data === "object") {
+            applyServerScaffolding(scaffRes.data);
+        }
+    }
+    catch {
+        // baked-in defaults stay in effect
+    }
+    // The client tools are needed to even inspect the source, so verify they're on
+    // PATH up front (the pg_dump-major-vs-source-major gate stays in phase 2, once
+    // the source major is known).
+    if (!hasTool("pg_dump") || !hasTool("psql")) {
+        emitError("TOOLS_MISSING", "pg_dump and psql are required but were not found on PATH.", "macOS: brew install libpq  ·  Ubuntu: sudo apt install postgresql-client", 1);
+        return;
+    }
+    // ── Phase 1: preflight the source ──────────────────────────────────────────
+    phase("Inspecting source database");
+    const summarySql = "SELECT json_build_object(" +
+        "'database', current_database()," +
+        "'server_version', current_setting('server_version')," +
+        "'server_version_num', current_setting('server_version_num')," +
+        "'size', pg_size_pretty(pg_database_size(current_database()))," +
+        "'tables', (SELECT count(*) FROM pg_tables WHERE schemaname NOT IN ('pg_catalog','information_schema'))" +
+        ")";
+    const srcRes = runPsql(source, summarySql);
+    if (srcRes.code !== 0) {
+        emitError("SOURCE_UNREACHABLE", `Could not read the source database: ${sourcePreflightErrorMessage(srcRes.stderr)}`, "Check the --source URI (host, credentials, sslmode) and that the server is reachable.", 1);
+        return;
+    }
+    let sourceSummary;
+    try {
+        sourceSummary = JSON.parse(srcRes.stdout.trim());
+    }
+    catch {
+        emitError("SOURCE_UNREACHABLE", "Unexpected response from the source database.", "", 1);
+        return;
+    }
+    const extRes = runPsql(source, "SELECT extname FROM pg_extension ORDER BY extname");
+    const sourceExtensions = extRes.code === 0
+        ? extRes.stdout.split("\n").map((s) => s.trim()).filter(Boolean)
+        : [];
+    const sourceMajor = parsePgMajor(sourceSummary.server_version_num || sourceSummary.server_version);
+    phase(`Source: ${sourceSummary.database} · PostgreSQL ${sourceSummary.server_version} · ` +
+        `${sourceSummary.size} · ${sourceSummary.tables} tables`);
+    // Warn up front if the SOURCE contains anything sharing a name with BataDB's
+    // seeded platform scaffolding — the named public.health_check table, or ANY
+    // object in a scaffolding schema (neon_migration), e.g. when migrating FROM
+    // another BataDB. Its CREATE will clash with the furniture the target is
+    // provisioned with, so the restore will likely fail later with "relation already
+    // exists" — flagging it now makes that error unsurprising. We do NOT touch source
+    // accounting; a source health_check / neon_migration object is treated as real
+    // data and verifies normally if it does restore.
+    const scaffoldingBareTables = PLATFORM_SCAFFOLDING_TABLES.filter((n) => n.startsWith("public."))
+        .map((n) => quoteLiteral(n.slice("public.".length)))
+        .join(",");
+    const scaffoldingSchemaLits = PLATFORM_SCAFFOLDING_SCHEMAS.map((s) => quoteLiteral(s)).join(",");
+    const srcCollisionRes = runPsql(source, "SELECT schemaname||'.'||tablename FROM pg_tables " +
+        `WHERE (schemaname = 'public' AND tablename IN (${scaffoldingBareTables})) ` +
+        `OR schemaname IN (${scaffoldingSchemaLits}) ORDER BY 1`);
+    const sourceScaffoldingHits = srcCollisionRes.code === 0
+        ? scaffoldingCollisions(srcCollisionRes.stdout.split("\n").map((s) => s.trim()).filter(Boolean))
+        : [];
+    if (sourceScaffoldingHits.length > 0 && !jsonMode) {
+        warn(`Source contains ${sourceScaffoldingHits.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.');
+    }
+    // ── 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
+    // able to restore the stream THIS pg_dump produces — pg_dump 17 emits
+    // \restrict/\unrestrict regardless of the source version, so psql 16 + pg_dump
+    // 17 fails even against a PG16 source. checkClientVersions() encodes the full
+    // rule (psql ≥ max(source, pg_dump)); without it the restore would fail late,
+    // after a target was already created and warmed.
+    phase("Checking pg_dump / psql versions");
+    const dumpMajor = pgDumpMajor();
+    if (dumpMajor === null) {
+        emitError("TOOLS_MISSING", "Could not determine the pg_dump version.", "", 1);
+        return;
+    }
+    const psqlVer = psqlMajor();
+    if (psqlVer === null) {
+        emitError("TOOLS_MISSING", "Could not determine the psql version.", "", 1);
+        return;
+    }
+    const versionVerdict = checkClientVersions(dumpMajor, psqlVer, sourceMajor);
+    if (!versionVerdict.ok) {
+        emitError("PG_VERSION_TOO_OLD", versionVerdict.message, "macOS: brew install libpq  ·  Ubuntu: sudo apt install postgresql-client-" + versionVerdict.needMajor, 1);
+        return;
+    }
+    // ── Phase 3: resolve / create the target ───────────────────────────────────
+    const teamId = await resolveTeamId(token);
+    let targetProjectId;
+    let created = false;
+    // The target's PostgreSQL major (for messaging + the JSON result). For a new
+    // project this is what we asked for; for --project it's read from the record.
+    let targetPg;
+    if (parsed.projectId) {
+        phase(`Resolving target project ${parsed.projectId}`);
+        const q = {};
+        if (teamId)
+            q.team_id = teamId;
+        const projRes = await api.get(`/v1/projects/${parsed.projectId}`, token, q);
+        if (!projRes.ok) {
+            emitError(projRes.status === 404 ? "NOT_FOUND"
+                : projRes.status === 401 || projRes.status === 403 ? "INVALID_KEY"
+                    : projRes.status >= 500 || projRes.status === 0 ? "API_UNAVAILABLE"
+                        : "CLI_ERROR", apiError(projRes, "Target project not found"), "");
+            return;
+        }
+        targetProjectId = parsed.projectId;
+        // Older control planes may omit pgVersion; fall back to the platform's
+        // historical default rather than guessing anything newer.
+        targetPg = projRes.data.pgVersion ?? "16";
+    }
+    else {
+        const name = parsed.name ?? defaultProjectName(sourceSummary.database, source);
+        // An unparseable source version keeps the conservative historical default.
+        targetPg = parsed.pg ?? (sourceMajor === null ? "16" : defaultTargetPg(sourceMajor));
+        phase(`Creating project ${name} (serverless · PostgreSQL ${targetPg})`);
+        if (sourceMajor !== null && sourceMajor > Number(targetPg) && !jsonMode) {
+            warn(`source is PG${sourceMajor}, BataDB target is PG${targetPg} — standard schemas migrate cleanly; ` +
+                `PG${sourceMajor}-only features will fail loudly during restore`);
+        }
+        const body = {
+            name,
+            region: "us-east-1",
+            compute: { tier: "serverless", size_cu: 1 },
+            pg_version: targetPg,
+        };
+        if (teamId)
+            body.team_id = teamId;
+        const res = await api.post("/v1/projects", body, token);
+        if (!res.ok) {
+            const explicitPg = parsed.pg !== undefined;
+            emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR", apiError(res, "Failed to create target project"), 
+            // A 400 on an explicit --pg is almost always an unsupported major.
+            explicitPg && res.status === 400 ? "Try --pg 16 (or omit --pg for the default)." : "");
+            return;
+        }
+        targetProjectId = res.data.id;
+        created = true;
+    }
+    // Resolve the usable target URI (the deliverable) via the API — never local.
+    const targetUri = await getTargetUri(targetProjectId, token);
+    if (!targetUri) {
+        emitError("API_UNAVAILABLE", "Could not fetch the target connection string.", "", 6);
+        return;
+    }
+    phase("Waiting for target compute to be ready");
+    const ready = await waitForReady(targetProjectId, targetUri, token, teamId, (secs) => {
+        if (!jsonMode && secs > 0 && secs % 15 === 0)
+            phase(`  …still waiting (${secs}s)`);
+    });
+    if (!ready) {
+        emitError("COMPUTE_STARTING", "Target compute did not become ready within 180s.", `Retry once it warms: bata status --project ${targetProjectId}`, 6);
+        return;
+    }
+    // For an existing target, ANY pre-existing user OBJECT risks a collision in a
+    // non-transactional restore — not just relations. This ONE fail-closed query
+    // counts: relations (table/partitioned/view/matview/sequence/foreign table),
+    // user-created schemas (excluding public), user types (enums, domains, and
+    // free-standing composites — NOT a table's implicit row type), and user
+    // functions (excluding extension-owned ones). If the query itself errors we must
+    // NOT treat the target as empty and silently proceed.
+    if (parsed.projectId) {
+        // BataDB seeds public.health_check (+ its sequence) into every project and our
+        // compute exposes an internal neon_migration schema, so a target holding ONLY
+        // scaffolding is effectively empty — exclude those from the counts so the --yes
+        // guard doesn't trip on our own furniture. Derived from the same constants as
+        // the rest of the scaffolding handling.
+        const scaffoldingPublicRelnames = [...PLATFORM_SCAFFOLDING_TABLES, ...PLATFORM_SCAFFOLDING_SEQUENCES]
+            .filter((n) => n.startsWith("public."))
+            .map((n) => quoteLiteral(n.slice("public.".length)))
+            .join(",");
+        const scaffoldingSchemaLiterals = PLATFORM_SCAFFOLDING_SCHEMAS.map((s) => quoteLiteral(s)).join(",");
+        const cnt = runPsql(targetUri, "SELECT" +
+            // relations, in any non-system namespace (incl. public), minus scaffolding:
+            // named public objects AND everything in a scaffolding schema.
+            " (SELECT count(*) FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace" +
+            "  WHERE c.relkind IN ('r','p','v','m','S','f')" +
+            "  AND n.nspname NOT IN ('pg_catalog','information_schema') AND n.nspname NOT LIKE 'pg_%'" +
+            `  AND n.nspname NOT IN (${scaffoldingSchemaLiterals})` +
+            `  AND NOT (n.nspname = 'public' AND c.relname IN (${scaffoldingPublicRelnames})))` +
+            // user-created schemas (public is a default, not user-created; scaffolding
+            // schemas are platform furniture)
+            " + (SELECT count(*) FROM pg_namespace n" +
+            "  WHERE n.nspname NOT IN ('public','pg_catalog','information_schema') AND n.nspname NOT LIKE 'pg_%'" +
+            `  AND n.nspname NOT IN (${scaffoldingSchemaLiterals}))` +
+            // user types: enums, domains, and standalone composites (relkind 'c'),
+            // but not a table's implicit row type
+            " + (SELECT count(*) FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace" +
+            "  WHERE n.nspname NOT IN ('pg_catalog','information_schema') AND n.nspname NOT LIKE 'pg_%'" +
+            `  AND n.nspname NOT IN (${scaffoldingSchemaLiterals})` +
+            "  AND (t.typtype IN ('e','d')" +
+            "       OR (t.typtype = 'c' AND EXISTS (SELECT 1 FROM pg_class cc WHERE cc.oid = t.typrelid AND cc.relkind = 'c'))))" +
+            // user functions, excluding extension-owned (pg_depend deptype 'e')
+            " + (SELECT count(*) FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace" +
+            "  WHERE n.nspname NOT IN ('pg_catalog','information_schema') AND n.nspname NOT LIKE 'pg_%'" +
+            `  AND n.nspname NOT IN (${scaffoldingSchemaLiterals})` +
+            "  AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = p.oid AND d.classid = 'pg_proc'::regclass AND d.deptype = 'e'))" +
+            " AS n");
+        if (cnt.code !== 0) {
+            emitError("CLI_ERROR", "Could not verify whether the target project is empty before importing.", "Retry once the target compute is warm, or check the target connection.", 1);
+            return;
+        }
+        const existingObjects = parseInt(cnt.stdout.trim(), 10) || 0;
+        if (existingObjects > 0 && !isYes()) {
+            emitError("INVALID_FLAG", `Target project already has ${existingObjects} user object(s). Importing may collide with existing objects.`, "Re-run with --yes to import into it anyway.");
+            return;
+        }
+        if (existingObjects > 0 && !jsonMode) {
+            warn(`Target already has ${existingObjects} user object(s) — proceeding because --yes was set.`);
+        }
+    }
+    // Extension preflight — BEFORE the dump. With ON_ERROR_STOP=1 the restore
+    // would die at the first `CREATE EXTENSION <x>;` the target can't provide, so
+    // checking availability up front lets us fail loudly with the full list
+    // instead of a cryptic mid-restore error (and a half-imported target). Fail
+    // CLOSED: if we can't even query availability, don't start a restore we know
+    // might half-apply.
+    if (sourceExtensions.length > 0) {
+        phase("Checking target extension availability");
+        // We reach this AFTER (possibly) creating the project and waiting for its
+        // compute — so a failure here would strand an empty project. If THIS run
+        // created it, delete it before exiting and say so; if the delete fails, tell
+        // the user the id to clean up. A pre-existing --project target is never
+        // touched (created === false).
+        const failWithCleanup = async (message, baseHint) => {
+            let hint = baseHint;
+            if (created) {
+                const removed = await deleteCreatedProject(targetProjectId, token, teamId);
+                hint += removed
+                    ? " Removed the empty project that was created for this import."
+                    : ` Could not remove the project created for this import — delete it manually: bata projects delete ${targetProjectId}`;
+            }
+            emitError("EXTENSION_UNSUPPORTED", message, hint, 1);
+            throw new Error("unreachable"); // emitError exits; satisfy the `never` return
+        };
+        const availRes = runPsql(targetUri, "SELECT name FROM pg_available_extensions ORDER BY name");
+        if (availRes.code !== 0) {
+            await failWithCleanup("Could not verify which extensions the target supports.", "Retry once the target compute is warm — a restore isn't safe to start until this is known.");
+        }
+        const available = availRes.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+        const unsupported = missingExtensions(sourceExtensions, available);
+        if (unsupported.length > 0) {
+            await failWithCleanup(`The source uses extension(s) the target can't provide: ${unsupported.join(", ")}.`, "BataDB may not offer these yet. Drop them on the source (DROP EXTENSION …) before importing, or contact BataDB support to request them.");
+        }
+    }
+    // Once we're past target creation + restore start, a failure leaves a
+    // partially-populated target. We DELIBERATELY do NOT auto-delete it here
+    // (unlike the extension preflight, which fails before any data moves): a
+    // partial restore can represent significant transfer time and is useful for
+    // diagnosis and retry, so destroying it silently would be worse. Instead every
+    // post-restore failure path NAMES the project and gives actionable next steps.
+    const strandedTargetJson = () => ({
+        project_id: targetProjectId,
+        created,
+        connection: targetUri,
+    });
+    const printStrandedTargetHints = () => {
+        log(`  ${colors.dim("The target project was left in place for diagnosis/retry:")}`);
+        kvList([["Project ID", colors.dim(targetProjectId)]]);
+        log();
+        log(`  ${colors.dim("Retry into the SAME target after fixing the issue:")}`);
+        log(`    ${colors.cyan(`bata import --source <source> --project ${targetProjectId} --yes`)}`);
+        if (created) {
+            log(`  ${colors.dim("…or remove the partial project:")}`);
+            log(`    ${colors.cyan(`bata projects delete ${targetProjectId} --yes`)}`);
+        }
+        log();
+    };
+    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.` : ".");
+    // ── Phase 4: migrate ───────────────────────────────────────────────────────
+    phase("Migrating schema + data (pg_dump | psql)");
+    const migration = await runMigration(source, targetUri);
+    if (!migration.ok) {
+        if (jsonMode) {
+            json({
+                error: "Restore failed — the target rejected part of the dump.",
+                code: "RESTORE_FAILED",
+                hint: `Schema features newer than the target's PostgreSQL ${targetPg} aren't supported there. ` +
+                    "Review the errors below. " +
+                    strandedHintJson,
+                errors: migration.errors,
+                target: strandedTargetJson(),
+            });
+        }
+        else {
+            log();
+            emitErrorHuman("Restore failed — the target rejected part of the dump.", migration.errors);
+            printStrandedTargetHints();
+        }
+        process.exit(1);
+        return;
+    }
+    // ── Phase 5: verify ────────────────────────────────────────────────────────
+    // Fail CLOSED: a verify query that can't run must never read as "no mismatch"
+    // (that would report a false success). Any failed query, or an unexpectedly
+    // empty result for a non-empty input, is a hard failure that tells the user
+    // verification couldn't run — never silent success.
+    phase("Verifying row counts + sequences");
+    let verifyFailed = null;
+    const tableListRes = runPsql(source, "SELECT COALESCE(json_agg(json_build_object('schema', schemaname, 'table', tablename) " +
+        "ORDER BY schemaname, tablename), '[]') " +
+        "FROM pg_tables WHERE schemaname NOT IN ('pg_catalog','information_schema')");
+    if (tableListRes.code !== 0)
+        verifyFailed = "could not list source tables";
+    const sourceTables = tableListRes.code === 0 ? safeJsonArray(tableListRes.stdout) : [];
+    const srcCounts = new Map();
+    const tgtCounts = new Map();
+    if (!verifyFailed && sourceTables.length > 0) {
+        // Chunk into batches so a huge table list can't blow psql's statement limit
+        // (which would fail the whole UNION ALL and leave both maps empty).
+        for (const batch of chunk(sourceTables, 100)) {
+            const countsSql = batch
+                .map((t) => `SELECT ${quoteLiteral(`${t.schema}.${t.table}`)} AS t, count(*)::text AS c ` +
+                `FROM ${quoteIdent(t.schema)}.${quoteIdent(t.table)}`)
+                .join("\nUNION ALL\n");
+            const sRes = runPsql(source, countsSql);
+            const tRes = runPsql(targetUri, countsSql);
+            if (sRes.code !== 0 || tRes.code !== 0) {
+                verifyFailed = "row-count query failed";
+                break;
+            }
+            const sMap = parseKvRows(sRes.stdout);
+            const tMap = parseKvRows(tRes.stdout);
+            // A query that returned fewer rows than tables didn't run cleanly.
+            if (sMap.size !== batch.length || tMap.size !== batch.length) {
+                verifyFailed = "row-count query returned an incomplete result";
+                break;
+            }
+            for (const [k, v] of sMap)
+                srcCounts.set(k, v);
+            for (const [k, v] of tMap)
+                tgtCounts.set(k, v);
+        }
+    }
+    const tableMismatches = verifyFailed ? [] : diffCounts(srcCounts, tgtCounts);
+    const seqSql = "SELECT schemaname||'.'||sequencename AS s, COALESCE(last_value::text,'') AS v " +
+        "FROM pg_sequences ORDER BY 1";
+    const srcSeq = new Map();
+    const tgtSeq = new Map();
+    if (!verifyFailed) {
+        const sSeqRes = runPsql(source, seqSql);
+        const tSeqRes = runPsql(targetUri, seqSql);
+        if (sSeqRes.code !== 0 || tSeqRes.code !== 0) {
+            verifyFailed = "sequence query failed";
+        }
+        else {
+            for (const [k, v] of parseKvRows(sSeqRes.stdout))
+                srcSeq.set(k, v);
+            for (const [k, v] of parseKvRows(tSeqRes.stdout))
+                tgtSeq.set(k, v);
+        }
+    }
+    // Target-only sequences (present on target, absent from source) get the SAME
+    // treatment as target-only tables: on a --project --yes existing target they're
+    // expected leftovers (e.g. a pre-existing serial/identity table contributes one),
+    // so they're excluded from the mismatch diff and surfaced as untouched — NOT a
+    // failure. Source-only sequences and value drift on shared ones stay mismatches.
+    let targetOnlySequences = [];
+    let seqMismatches = [];
+    if (!verifyFailed) {
+        // The RAW set (incl. BataDB scaffolding) is what we exclude from the mismatch
+        // diff — a target-only sequence must never read as a mismatch. The REPORTED
+        // list + the created-project hard-fail then drop platform scaffolding (BataDB
+        // seeds public.health_check_id_seq into every project, so it's expected on any
+        // target and must not false-positive a freshly created one).
+        const rawTargetOnlySeq = targetOnlyNames([...srcSeq.keys()], [...tgtSeq.keys()]);
+        const rawTargetOnlySet = new Set(rawTargetOnlySeq);
+        seqMismatches = diffCounts(srcSeq, tgtSeq).filter((r) => !rawTargetOnlySet.has(r.name));
+        targetOnlySequences = excludeScaffolding(rawTargetOnlySeq);
+        // A freshly created project must have no NON-scaffolding sequences the source lacks.
+        if (created && targetOnlySequences.length > 0) {
+            verifyFailed =
+                `freshly created target unexpectedly has ${targetOnlySequences.length} sequence(s) absent ` +
+                    `from the source: ${targetOnlySequences.join(", ")}`;
+        }
+    }
+    // Enumerate the TARGET's tables too — verify only counts SOURCE tables, so a
+    // --project --yes import into a non-empty target has pre-existing target-only
+    // tables our row-count check never sees. Fail closed like the rest of verify.
+    let targetOnly = [];
+    if (!verifyFailed) {
+        const tgtTablesRes = runPsql(targetUri, "SELECT schemaname||'.'||tablename FROM pg_tables " +
+            "WHERE schemaname NOT IN ('pg_catalog','information_schema') ORDER BY 1");
+        if (tgtTablesRes.code !== 0) {
+            verifyFailed = "could not list target tables";
+        }
+        else {
+            const targetQualified = tgtTablesRes.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+            const sourceQualified = sourceTables.map((t) => `${t.schema}.${t.table}`);
+            // Drop BataDB scaffolding (public.health_check + the neon_migration schema) —
+            // seeded/created on every project, so never a real "target-only" leftover and
+            // must not false-positive a freshly created target. (Target-only tables never
+            // enter the count mismatch diff, so no raw/reported split is needed here.)
+            targetOnly = excludeScaffolding(targetOnlyNames(sourceQualified, targetQualified));
+            // A FRESHLY CREATED project should have no NON-scaffolding tables the source
+            // lacks. If it does, something is genuinely wrong (wrong target, contaminated
+            // template) — hard-fail rather than wave it through as an expected leftover.
+            if (created && targetOnly.length > 0) {
+                verifyFailed =
+                    `freshly created target unexpectedly has ${targetOnly.length} table(s) absent ` +
+                        `from the source: ${targetOnly.join(", ")}`;
+            }
+        }
+    }
+    const tgtExtRes = runPsql(targetUri, "SELECT extname FROM pg_extension ORDER BY extname");
+    const targetExtensions = tgtExtRes.code === 0
+        ? tgtExtRes.stdout.split("\n").map((s) => s.trim()).filter(Boolean)
+        : [];
+    // Residual check only: unsupported extensions were already hard-failed in the
+    // pre-restore preflight, so this now catches only the oddity of an extension
+    // that IS available on the target but somehow didn't get installed.
+    const residualMissingExtensions = missingExtensions(sourceExtensions, targetExtensions);
+    // Verification couldn't run — the data was restored but we can't confirm it
+    // matches. Hard-fail rather than imply success.
+    if (verifyFailed) {
+        if (jsonMode) {
+            json({
+                error: `Verification could not run: ${verifyFailed}.`,
+                code: "VERIFY_FAILED",
+                hint: "The dump/restore reported success, but the CLI could not confirm row counts/sequences match. " +
+                    "Verify manually before relying on the target. " +
+                    strandedHintJson,
+                target: strandedTargetJson(),
+            });
+        }
+        else {
+            log();
+            log(`  ${colors.red("Verification could not run")} — ${verifyFailed}.`);
+            log(`  ${colors.dim("The data was restored, but counts/sequences were NOT confirmed. Verify manually before relying on it.")}`);
+            log();
+            printStrandedTargetHints();
+        }
+        process.exit(1);
+        return;
+    }
+    if (tableMismatches.length > 0 || seqMismatches.length > 0) {
+        if (jsonMode) {
+            json({
+                error: "Verification failed — source and target differ after import.",
+                code: "VERIFY_MISMATCH",
+                hint: "The dump/restore reported success but row counts or sequences don't match. " + strandedHintJson,
+                mismatches: {
+                    tables: tableMismatches,
+                    sequences: seqMismatches,
+                },
+                target: strandedTargetJson(),
+            });
+        }
+        else {
+            log();
+            log(`  ${colors.red("Verification failed")} — source and target differ:`);
+            log();
+            table(["OBJECT", "SOURCE", "TARGET"], mismatchRows(tableMismatches, seqMismatches));
+            log();
+            printStrandedTargetHints();
+        }
+        process.exit(1);
+        return;
+    }
+    // ── Phase 6: done ──────────────────────────────────────────────────────────
+    if (jsonMode) {
+        json({
+            ok: true,
+            source: {
+                database: sourceSummary.database,
+                server_version: sourceSummary.server_version,
+                server_major: sourceMajor,
+                size: sourceSummary.size,
+                tables: sourceSummary.tables,
+                extensions: sourceExtensions,
+            },
+            target: {
+                project_id: targetProjectId,
+                created,
+                pg_version: targetPg,
+                connection: targetUri,
+            },
+            verify: {
+                tables_checked: sourceTables.length,
+                sequences_checked: srcSeq.size,
+                extensions_missing_on_target: residualMissingExtensions,
+                // Pre-existing target tables/sequences the source doesn't have — left
+                // untouched and NOT covered by verification (only possible on --project
+                // --yes into a non-empty target).
+                target_only_tables: targetOnly,
+                target_only_sequences: targetOnlySequences,
+            },
+        });
+        return;
+    }
+    if (targetOnly.length > 0) {
+        warn(`${targetOnly.length} pre-existing table(s) on the target were left untouched and are ` +
+            `NOT covered by verification: ${targetOnly.join(", ")}`);
+    }
+    if (targetOnlySequences.length > 0) {
+        warn(`${targetOnlySequences.length} pre-existing sequence(s) on the target were left untouched and are ` +
+            `NOT covered by verification: ${targetOnlySequences.join(", ")}`);
+    }
+    if (residualMissingExtensions.length > 0) {
+        warn(`Extensions on the source not installed on the target: ${residualMissingExtensions.join(", ")} ` +
+            "(available but not created during restore — install them manually if needed).");
+    }
+    log();
+    success(`Imported into ${colors.cyan(targetProjectId)} — ${sourceSummary.tables} tables verified.`);
+    log();
+    kvList([
+        ["Project ID", colors.dim(targetProjectId)],
+        ["PostgreSQL", targetPg],
+        ["Connection", colors.dim(targetUri)],
+    ]);
+    log();
+    log(`  ${colors.dim("Connect:")} ${colors.cyan(`bata connect ${targetProjectId}`)}`);
+    log();
+}
+/** Print a restore failure with its first errors (human mode). */
+function emitErrorHuman(message, errors) {
+    log(`  ${colors.red("Error:")} ${message}`);
+    if (errors.length > 0) {
+        log();
+        for (const e of errors)
+            log(`    ${colors.dim(e)}`);
+    }
+    log();
+    log(`  ${colors.dim("Schema features newer than the target's PostgreSQL major aren't supported there.")}`);
+    log();
+}
+function safeJsonArray(stdout) {
+    try {
+        const v = JSON.parse(stdout.trim());
+        return Array.isArray(v) ? v : [];
+    }
+    catch {
+        return [];
+    }
+}