@batadata/cli 0.2.8 → 0.2.10

package/dist/commands/powdb.d.ts

@@ -45,7 +45,7 @@ export interface TableSchema {
     constraints: ConstraintInfo[];
 }
 /** The Stage-A PowDB types a static PowQL artifact can carry. */
-export type PowType = "int" | "float" | "str" | "bool" | "datetime";
+export type PowType = "int" | "float" | "str" | "bool" | "datetime" | "json";
 export interface TypeMapping {
     /** null → PowDB has no Stage-A representation; the column is DROPPED. */
     powType: PowType | null;
@@ -133,8 +133,16 @@ export interface TablePlan {
     pgName: string;
     powName: string;
     columns: ColumnPlan[];
+    /** powNames of carried single-column secondary (non-unique) indexes. */
+    secondaryIndexes: string[];
     warnings: string[];
 }
+/**
+ * Extract the single plain column of a non-unique btree index definition, or
+ * null when the index can't be carried (multi-column, expression, partial,
+ * non-btree). Exported for unit testing.
+ */
+export declare function parseSingleColumnIndex(definition: string): string | null;
 /**
  * Build the per-table PowQL `type` plan from a Postgres table's schema,
  * accumulating an honesty note for every column/constraint that can't be
@@ -143,6 +151,12 @@ export interface TablePlan {
 export declare function planTable(t: TableSchema): TablePlan;
 /** Render a table plan as a PowQL `type` DDL block. */
 export declare function renderTypeDdl(plan: TablePlan): string;
+/**
+ * Render a plan's carried secondary indexes as `alter T add index .col;`
+ * statements (PowQL DDL, valid since 0.1.1; keyword columns backtick-quote
+ * inside the path, e.g. `alter Post add index .\`order\``).
+ */
+export declare function renderIndexDdl(plan: TablePlan): string[];
 export interface InsertResult {
     statements: string[];
     warnings: string[];

package/dist/commands/powdb.js

@@ -3,11 +3,12 @@ import * as path from "node:path";
 import { api, apiError } from "../api.js";
 import { requireToken, isJsonMode, loadConfig } from "../config.js";
 import { colors, log, json, spinner, heading, table } from "../utils/logger.js";
+import { confirmDestructive } from "../utils/prompts.js";
 import { emitError, isRetryable } from "../utils/errors.js";
 import { resolveProjectId, resolveBranchId } from "../link.js";
 // PowQL reserved words a column/table name must not collide with. Mirrors the
 // FULL engine lexer keyword set (crates/query/src/lexer.rs POWQL_KEYWORDS as
-// of PowDB 0.10.0 — which added `schema`/`describe`). A colliding name is
+// of PowDB 0.13.0 — which added `raw`, `json_type`, `json_text`). A colliding name is
 // emitted backtick-quoted (0.10+ syntax) rather than renamed, so the exported
 // column keeps its source name. Keep this list in sync on PowDB upgrades: a
 // missing word here means a bare identifier that fails to parse on load.
@@ -20,7 +21,8 @@ const POWQL_KEYWORDS = new Set([
     "having", "in", "index", "inner", "insert", "is", "join", "left", "length",
     "let", "like", "limit", "link", "lower", "match", "materialize",
     "materialized", "max", "min", "multi", "not", "now", "null", "offset", "on",
-    "or", "order", "outer", "over", "partition", "pow", "rank", "refresh",
+    "json_text", "json_type", "or", "order", "outer", "over", "partition",
+    "pow", "rank", "raw", "refresh",
     "required", "returning", "right", "rollback", "round", "row_number",
     "schema", "select", "sqrt", "substring", "sum", "then", "transaction",
     "trim", "true", "type", "union", "unique", "update", "upper", "upsert",
@@ -74,9 +76,14 @@ export function mapPgType(dataType) {
     if (t === "bytea") {
         return { powType: "str", note: "bytea carried as hex text (str) — PowDB has no static bytes literal for a script load" };
     }
-    // json/jsonb — carried as text; no JSON operators.
+    // json/jsonb → native PowDB `json` (0.12+): canonical binary (PJ1), `->`
+    // path querying. Canonicalization is honest-but-lossy for exact text: object
+    // keys re-sort bytewise and duplicate keys collapse last-wins (same as pg jsonb).
     if (t === "json" || t === "jsonb") {
-        return { powType: "str", note: `${t} carried as text (str) — no JSON operators in PowDB Stage A` };
+        return {
+            powType: "json",
+            note: `${t} stored as native PowDB json (requires PowDB 0.12+; canonical form — key order normalized${t === "json" ? ", duplicate keys last-wins" : ""})`,
+        };
     }
     // Everything else (arrays, enums, ranges, geometry, network, tsvector,
     // composite/user-defined) has no honest Stage-A representation.
@@ -182,6 +189,16 @@ export function powqlLiteral(value, powType) {
             const raw = typeof value === "string" ? value : JSON.stringify(value);
             return { literal: `"${escapePowqlString(raw)}"`, risky: isLoadRiskyString(raw) };
         }
+        case "json": {
+            // PowQL inserts JSON as a string literal (validated + canonicalized by
+            // the engine). Rows arrive as parsed JSON over SQL-over-HTTP, so
+            // re-stringify the VALUE — a JS string here is a JSON string scalar
+            // document and must be emitted quoted-inside-the-document.
+            const doc = JSON.stringify(value);
+            if (doc === undefined)
+                return { skip: true, reason: `value has no JSON representation` };
+            return { literal: `"${escapePowqlString(doc)}"`, risky: isLoadRiskyString(doc) };
+        }
     }
 }
 /**
@@ -228,9 +245,49 @@ export function parsePgDefault(defaultValue, powType) {
             return { kind: "literal", text: `"${escapePowqlString(m[1].replace(/''/g, "'"))}"` };
         return { kind: "drop", note: `expression default dropped (${raw})` };
     }
+    // json: a quoted literal default ('{}'::jsonb) carries as a string-literal
+    // default only if its content is valid JSON — the engine would reject the
+    // whole type DDL otherwise.
+    if (powType === "json") {
+        const m = /^'([\s\S]*)'$/.exec(noCast);
+        if (m) {
+            const text = m[1].replace(/''/g, "'");
+            try {
+                JSON.parse(text);
+                return { kind: "literal", text: `"${escapePowqlString(text)}"` };
+            }
+            catch {
+                return { kind: "drop", note: `non-JSON default on json column dropped (${raw})` };
+            }
+        }
+        return { kind: "drop", note: `expression default dropped (${raw})` };
+    }
     // datetime defaults are expressions (now(), CURRENT_TIMESTAMP) — never scalar.
     return { kind: "drop", note: `expression default dropped (${raw})` };
 }
+/**
+ * Extract the single plain column of a non-unique btree index definition, or
+ * null when the index can't be carried (multi-column, expression, partial,
+ * non-btree). Exported for unit testing.
+ */
+export function parseSingleColumnIndex(definition) {
+    if (/\bWHERE\b/i.test(definition))
+        return null; // partial
+    if (/\bINCLUDE\b/i.test(definition))
+        return null; // covering — the trailing parens are the INCLUDE list, not the key
+    if (/\bUSING\s+(?!btree\b)/i.test(definition))
+        return null; // gin/gist/hash/...
+    const m = /\(([^()]*)\)\s*$/.exec(definition);
+    if (!m)
+        return null; // expression index
+    const cols = m[1].split(",");
+    if (cols.length !== 1)
+        return null; // multi-column
+    const col = /^\s*(?:"([^"]+)"|([A-Za-z_][A-Za-z0-9_$]*))\s*(?:ASC|DESC)?\s*(?:NULLS\s+(?:FIRST|LAST))?\s*$/i.exec(cols[0]);
+    if (!col)
+        return null;
+    return col[1] ?? col[2];
+}
 /**
  * Build the per-table PowQL `type` plan from a Postgres table's schema,
  * accumulating an honesty note for every column/constraint that can't be
@@ -263,14 +320,30 @@ export function planTable(t) {
             warnings.push(`foreign key ${c.name} → ${c.foreignTableName ?? "?"} dropped — PowDB Stage A has no foreign keys`);
         }
         else if (type.includes("CHECK")) {
+            // PG17+ surfaces NOT NULL as synthetic check constraints named
+            // <reloid>_<attnum>_..._not_null (all-numeric prefix). Those ARE carried
+            // (as `required`), so warning about them would be noise — but a
+            // USER-named check that merely ends in _not_null must still warn.
+            if (/^\d+(_\d+)*_not_null$/.test(c.name))
+                continue;
             warnings.push(`check constraint ${c.name} dropped — PowDB Stage A has no check constraints`);
         }
     }
-    // Secondary (non-unique) indexes aren't carried — the type definition only
-    // expresses uniqueness, not standalone indexes.
+    // Single-column plain btree indexes carry as `alter T add index .col`
+    // statements (resolved against carried columns after the column loop below);
+    // anything else (multi-column, expression, partial, non-btree) is warned.
+    const pendingIndexCols = [];
     for (const idx of t.indexes ?? []) {
-        if (!/unique/i.test(idx.definition)) {
-            warnings.push(`index ${idx.name} not carried — PowDB Stage A expresses only unique constraints, not secondary indexes`);
+        // Only a leading CREATE UNIQUE INDEX is a unique index — a bare substring
+        // match would silently skip an index whose NAME merely contains "unique".
+        if (/^\s*CREATE\s+UNIQUE\s+INDEX\b/i.test(idx.definition))
+            continue;
+        const pgCol = parseSingleColumnIndex(idx.definition);
+        if (pgCol) {
+            pendingIndexCols.push({ idxName: idx.name, pgCol });
+        }
+        else {
+            warnings.push(`index ${idx.name} not carried — only single-column plain btree indexes map to PowDB \`add index\``);
         }
     }
     const columns = [];
@@ -311,12 +384,27 @@ export function planTable(t) {
             defaultLiteral: auto ? null : defaultLiteral,
         });
     }
+    // Resolve carried secondary indexes against the columns that survived the
+    // mapping; an index on a dropped column is warned, not silently lost.
+    const byPgName = new Map(columns.map((c) => [c.pgName, c]));
+    const secondaryIndexes = [];
+    for (const { idxName, pgCol } of pendingIndexCols) {
+        const col = byPgName.get(pgCol);
+        if (!col) {
+            warnings.push(`index ${idxName} not carried — its column ${pgCol} was not representable`);
+            continue;
+        }
+        if (col.unique)
+            continue; // already an index via the unique modifier
+        secondaryIndexes.push(col.powName);
+    }
     return {
         pgQualified: `"${t.schema}"."${t.name}"`,
         pgSchema: t.schema,
         pgName: t.name,
         powName: tPowName,
         columns,
+        secondaryIndexes,
         warnings,
     };
 }
@@ -339,6 +427,14 @@ export function renderTypeDdl(plan) {
     lines.push("}");
     return lines.join("\n");
 }
+/**
+ * Render a plan's carried secondary indexes as `alter T add index .col;`
+ * statements (PowQL DDL, valid since 0.1.1; keyword columns backtick-quote
+ * inside the path, e.g. `alter Post add index .\`order\``).
+ */
+export function renderIndexDdl(plan) {
+    return plan.secondaryIndexes.map((powName) => `alter ${renderPowqlIdent(plan.powName)} add index .${renderPowqlIdent(powName)};`);
+}
 /**
  * Render rows for one table as PowQL `insert` statements against its plan.
  * Values that can't be represented are omitted (the field falls back to
@@ -498,6 +594,7 @@ async function powdbPull(args) {
     const reports = [];
     let totalRows = 0;
     let anyLoadRisk = false;
+    let anyJson = false;
     for (const t of tables) {
         s?.update(`Exporting ${t.schema}.${t.name}`);
         const plan = planTable(t);
@@ -521,6 +618,8 @@ async function powdbPull(args) {
         }
         if (inserts.loadRisk)
             anyLoadRisk = true;
+        if (plan.columns.some((c) => c.powType === "json"))
+            anyJson = true;
         // Emit the type DDL, its honesty notes, and the inserts for this table.
         // Comments are `;`/newline-sanitized so they survive the `--exec` split.
         parts.push(commentSafe(`# ── ${t.schema}.${t.name} → ${plan.powName} (${inserts.statements.length} row(s)) ──`));
@@ -532,6 +631,9 @@ async function powdbPull(args) {
         }
         else {
             parts.push(ddl + ";");
+            const indexDdl = renderIndexDdl(plan);
+            if (indexDdl.length)
+                parts.push(indexDdl.join("\n"));
             parts.push("");
             if (inserts.statements.length) {
                 parts.push(inserts.statements.join("\n"));
@@ -556,6 +658,7 @@ async function powdbPull(args) {
         tableCount: tables.length,
         rowCount: totalRows,
         loadRisk: anyLoadRisk,
+        usesJson: anyJson,
         limit,
     });
     const artifact = header + "\n" + parts.join("\n") + "\n";
@@ -628,7 +731,9 @@ function buildArtifactHeader(o) {
     // which lexes as two minus signs and fails to parse).
     const lines = [
         "# PowDB Stage A export — generated by `bata powdb pull`",
-        "# Target: PowDB 0.10+ (reserved identifiers are backtick-quoted)",
+        o.usesJson
+            ? "# Target: PowDB 0.12+ (native json columns; reserved identifiers are backtick-quoted)"
+            : "# Target: PowDB 0.10+ (reserved identifiers are backtick-quoted)",
         "#",
         `# Source project : ${o.projectName} (${o.projectId})`,
         `# Source branch  : ${o.branchName} (${o.branchId})`,
@@ -641,7 +746,8 @@ function buildArtifactHeader(o) {
         "#",
         "# COMPAT-HONEST: `# WARN:` lines below name every Postgres feature that",
         "# PowDB Stage A cannot carry faithfully (foreign keys, check constraints,",
-        "# secondary indexes, unmapped types, expression defaults, lossy numerics).",
+        "# multi-column/expression/partial indexes, unmapped types, expression",
+        "# defaults, lossy numerics).",
         "# PowDB is NOT Postgres-compatible beyond this mapping; nothing here claims",
         "# otherwise, and no engine-speed comparison is implied.",
     ];
@@ -860,7 +966,57 @@ async function powdbLifecycle(action, args) {
         return;
     }
     log();
-    log(`  ${colors.green(">")} ${colors.cyan(projectId)} ${colors.dim("engine=powdb state=")}${res.data.state}`);
+    const ver = res.data.server_version;
+    log(`  ${colors.green(">")} ${colors.cyan(projectId)} ${colors.dim("engine=powdb state=")}${res.data.state}${ver ? colors.dim(" server=") + ver : ""}`);
+    log();
+}
+/**
+ * `bata powdb upgrade --to <version>` — pin the project's server to a new
+ * engine version. Server-side this is park→backup→flip→wake→verify with
+ * automatic rollback to the pre-upgrade backup on failure. Storage-format
+ * releases (0.11+) make a verified upgrade a ONE-WAY door once new-format
+ * data is written, so this always confirms unless --yes/--json.
+ */
+async function powdbUpgrade(args) {
+    const token = requireToken();
+    const jsonMode = isJsonMode();
+    let toVersion;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--to")
+            toVersion = args[++i];
+        else if (a.startsWith("--to="))
+            toVersion = a.slice("--to=".length);
+        else
+            rest.push(a);
+    }
+    const positional = rest.find((a) => !a.startsWith("-"));
+    const projectId = powdbProjectFlag(rest) ?? positional ?? resolvePowdbProject(rest);
+    if (!toVersion || !/^\d+\.\d+\.\d+$/.test(toVersion)) {
+        emitError("MISSING_ARG", "A target version is required.", "Usage: bata powdb upgrade --to <x.y.z> [--project <id>]");
+    }
+    const ok = await confirmDestructive(`Upgrade ${colors.cyan(projectId)} to powdb-server ${colors.cyan(toVersion)}? A format-changing release cannot be downgraded once new data is written.`);
+    if (!ok) {
+        log("  Aborted.");
+        return;
+    }
+    const s = jsonMode ? null : spinner(`Upgrading ${projectId} to ${toVersion} (park -> backup -> flip -> wake -> verify)`);
+    const res = await api.post(`/v1/powdb/${encodeURIComponent(projectId)}/upgrade`, { to_version: toVersion }, token);
+    s?.stop();
+    if (!res.ok) {
+        emitError(res.status === 404 ? "NOT_FOUND"
+            : res.status === 401 || res.status === 403 ? "INVALID_KEY"
+                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR", apiError(res, "PowDB upgrade failed (instance rolled back to its pre-upgrade state)"), "");
+        return;
+    }
+    if (jsonMode) {
+        json({ project_id: projectId, ...res.data });
+        return;
+    }
+    log();
+    log(`  ${colors.green(">")} ${colors.cyan(projectId)} upgraded to powdb-server ${colors.cyan(res.data.server_version)} ${colors.dim("(verified)")}`);
     log();
 }
 // ─── Help + dispatch ──────────────────────────────────────────────────────────
@@ -883,6 +1039,8 @@ function powdbHelp() {
     log(`    ${colors.cyan("status")}  Show the server state (running | parked)  [--project <id>]`);
     log(`    ${colors.cyan("park")}    Scale the server to zero (WAL is durable)  [--project <id>]`);
     log(`    ${colors.cyan("wake")}    Start a parked server (~tens of ms)  [--project <id>]`);
+    log(`    ${colors.cyan("upgrade")} Pin the server to a new engine version  --to <x.y.z> [--project <id>]`);
+    log(`    ${colors.dim("            park -> backup -> flip -> wake -> verify, auto-rollback on failure")}`);
     log();
     log(`  ${colors.dim("Options (pull):")}`);
     log(`    ${colors.dim("--project <id>       override the linked/default project")}`);
@@ -918,10 +1076,12 @@ export async function handlePowdb(args) {
             return powdbLifecycle("park", args.slice(1));
         case "wake":
             return powdbLifecycle("wake", args.slice(1));
+        case "upgrade":
+            return powdbUpgrade(args.slice(1));
         case undefined:
             powdbHelp();
             return;
         default:
-            emitError("INVALID_FLAG", `Unknown subcommand: powdb ${sub}`, "Available: pull, query, exec, status, park, wake. Run `bata powdb --help`.");
+            emitError("INVALID_FLAG", `Unknown subcommand: powdb ${sub}`, "Available: pull, query, exec, status, park, wake, upgrade. Run `bata powdb --help`.");
     }
 }

package/package.json

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