@batadata/cli 0.2.7 → 0.2.9

package/dist/commands/powdb.d.ts

@@ -37,7 +37,7 @@ interface IndexInfo {
     name: string;
     definition: string;
 }
-interface TableSchema {
+export interface TableSchema {
     schema: string;
     name: string;
     columns: ColumnInfo[];
@@ -62,14 +62,22 @@ export declare function mapPgType(dataType: string): TypeMapping;
 /**
  * Sanitize a Postgres identifier into a valid PowQL identifier (leading
  * alpha/underscore, then alphanumeric/underscore). Reports whether it had to be
- * changed and whether it collides with a PowQL keyword, so the caller can flag
- * the rename honestly rather than emit a name that means something else.
+ * changed and whether it collides with a PowQL keyword. A keyword collision is
+ * NOT renamed — the name is kept and `renderPowqlIdent` backtick-quotes it at
+ * emit time (PowDB 0.10+ syntax), so exported columns keep their source names.
  */
 export declare function powqlIdentifier(name: string): {
     ident: string;
     changed: boolean;
     keyword: boolean;
 };
+/**
+ * Render an identifier for emitted PowQL: backtick-quoted when it collides
+ * with a reserved word (the 0.10 lexer accepts `` `name` `` in every
+ * identifier position), bare otherwise. Identifiers are pre-sanitized by
+ * `powqlIdentifier`, so no other escaping is needed inside the backticks.
+ */
+export declare function renderPowqlIdent(ident: string): string;
 /**
  * Escape a string for a PowQL double-quoted literal. The engine lexer honors
  * `\" \\ \n \t`; every other character passes through verbatim. Returns the

package/dist/commands/powdb.js

@@ -3,16 +3,29 @@ 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 (from the
-// engine lexer keyword set). A colliding name is renamed and flagged rather
-// than silently producing a broken `type`/`insert`.
+// 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
+// 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.
 const POWQL_KEYWORDS = new Set([
-    "type", "filter", "order", "limit", "offset", "insert", "update", "delete",
-    "default", "upsert", "returning", "group", "having", "distinct", "and", "or",
-    "not", "is", "null", "true", "false", "asc", "desc", "like", "in", "between",
-    "required", "unique", "auto", "count", "sum", "avg", "min", "max",
+    "abs", "add", "alter", "and", "as", "asc", "auto", "avg", "begin",
+    "between", "case", "cast", "ceil", "column", "commit", "concat", "conflict",
+    "count", "cross", "date_add", "date_diff", "default", "delete",
+    "dense_rank", "desc", "describe", "distinct", "drop", "else", "end",
+    "exists", "explain", "extract", "false", "filter", "floor", "group",
+    "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",
+    "required", "returning", "right", "rollback", "round", "row_number",
+    "schema", "select", "sqrt", "substring", "sum", "then", "transaction",
+    "trim", "true", "type", "union", "unique", "update", "upper", "upsert",
+    "view", "when",
 ]);
 /**
  * Map a Postgres data type (as reported by schema introspection) to the PowDB
@@ -73,8 +86,9 @@ export function mapPgType(dataType) {
 /**
  * Sanitize a Postgres identifier into a valid PowQL identifier (leading
  * alpha/underscore, then alphanumeric/underscore). Reports whether it had to be
- * changed and whether it collides with a PowQL keyword, so the caller can flag
- * the rename honestly rather than emit a name that means something else.
+ * changed and whether it collides with a PowQL keyword. A keyword collision is
+ * NOT renamed — the name is kept and `renderPowqlIdent` backtick-quotes it at
+ * emit time (PowDB 0.10+ syntax), so exported columns keep their source names.
  */
 export function powqlIdentifier(name) {
     let ident = name.replace(/[^A-Za-z0-9_]/g, "_");
@@ -82,11 +96,17 @@ export function powqlIdentifier(name) {
         ident = "_" + ident;
     }
     const keyword = POWQL_KEYWORDS.has(ident.toLowerCase());
-    if (keyword) {
-        ident = ident + "_";
-    }
     return { ident, changed: ident !== name, keyword };
 }
+/**
+ * Render an identifier for emitted PowQL: backtick-quoted when it collides
+ * with a reserved word (the 0.10 lexer accepts `` `name` `` in every
+ * identifier position), bare otherwise. Identifiers are pre-sanitized by
+ * `powqlIdentifier`, so no other escaping is needed inside the backticks.
+ */
+export function renderPowqlIdent(ident) {
+    return POWQL_KEYWORDS.has(ident.toLowerCase()) ? `\`${ident}\`` : ident;
+}
 /**
  * Escape a string for a PowQL double-quoted literal. The engine lexer honors
  * `\" \\ \n \t`; every other character passes through verbatim. Returns the
@@ -221,7 +241,10 @@ export function planTable(t) {
     const warnings = [];
     const { ident: tPowName, changed: nameChanged, keyword } = powqlIdentifier(t.name);
     if (nameChanged) {
-        warnings.push(`table renamed to \`${tPowName}\`${keyword ? " (collides with a PowQL keyword)" : " (name not a valid PowQL identifier)"}`);
+        warnings.push(`table renamed to \`${tPowName}\` (name not a valid PowQL identifier)`);
+    }
+    else if (keyword) {
+        warnings.push(`table name "${t.name}" is a PowQL reserved word — emitted backtick-quoted (requires PowDB 0.10+)`);
     }
     // Single-column UNIQUE constraints → the PowQL `unique` modifier.
     const singleUniqueCols = new Set();
@@ -263,7 +286,10 @@ export function planTable(t) {
         }
         const { ident: colPowName, changed: colChanged, keyword: colKeyword } = powqlIdentifier(col.name);
         if (colChanged) {
-            warnings.push(`column ${col.name} renamed to \`${colPowName}\`${colKeyword ? " (collides with a PowQL keyword)" : ""}`);
+            warnings.push(`column ${col.name} renamed to \`${colPowName}\` (name not a valid PowQL identifier)`);
+        }
+        else if (colKeyword) {
+            warnings.push(`column "${col.name}" is a PowQL reserved word — emitted backtick-quoted (requires PowDB 0.10+)`);
         }
         const def = parsePgDefault(col.defaultValue, mapping.powType);
         let auto = false;
@@ -297,7 +323,7 @@ export function planTable(t) {
 }
 /** Render a table plan as a PowQL `type` DDL block. */
 export function renderTypeDdl(plan) {
-    const lines = [`type ${plan.powName} {`];
+    const lines = [`type ${renderPowqlIdent(plan.powName)} {`];
     const fieldLines = plan.columns.map((c) => {
         const mods = [];
         if (c.required)
@@ -308,7 +334,7 @@ export function renderTypeDdl(plan) {
             mods.push("auto");
         const prefix = mods.length ? mods.join(" ") + " " : "";
         const def = c.defaultLiteral ? ` default ${c.defaultLiteral}` : "";
-        return `  ${prefix}${c.powName}: ${c.powType}${def}`;
+        return `  ${prefix}${renderPowqlIdent(c.powName)}: ${c.powType}${def}`;
     });
     lines.push(fieldLines.join(",\n"));
     lines.push("}");
@@ -337,14 +363,14 @@ export function buildInserts(plan, rows) {
             }
             if (res.risky)
                 loadRisk = true;
-            assigns.push(`${col.powName} := ${res.literal}`);
+            assigns.push(`${renderPowqlIdent(col.powName)} := ${res.literal}`);
             anyField = true;
         }
         if (!anyField) {
             skippedRows++;
             continue;
         }
-        statements.push(`insert ${plan.powName} { ${assigns.join(", ")} };`);
+        statements.push(`insert ${renderPowqlIdent(plan.powName)} { ${assigns.join(", ")} };`);
     }
     const warnings = [];
     for (const [col, reason] of skipNotes) {
@@ -603,6 +629,7 @@ 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)",
         "#",
         `# Source project : ${o.projectName} (${o.projectId})`,
         `# Source branch  : ${o.branchName} (${o.branchId})`,
@@ -834,7 +861,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 ──────────────────────────────────────────────────────────
@@ -857,6 +934,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")}`);
@@ -892,10 +971,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.7",
+  "version": "0.2.9",
   "description": "CLI for BataDB — serverless Postgres platform",
   "bin": {
     "bata": "./dist/index.js"