@saptools/cf-hana 0.1.2 → 0.1.4

package/dist/cli.js

@@ -3,6 +3,12 @@
 // src/cli.ts
 import { Command } from "commander";
 
+// src/backup.ts
+import { createHash, randomUUID } from "crypto";
+import { mkdir, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+
 // src/errors.ts
 var CfHanaError = class extends Error {
   code;
@@ -46,6 +52,91 @@ function errorMessage(error) {
   return String(error);
 }
 
+// src/format.ts
+function cellText(value, nullText) {
+  if (value === null) {
+    return nullText;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Buffer.isBuffer(value)) {
+    return `0x${value.toString("hex")}`;
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return typeof value === "number" ? value.toString() : value;
+}
+function serializeCell(value) {
+  if (value === null) {
+    return null;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Buffer.isBuffer(value)) {
+    return `0x${value.toString("hex")}`;
+  }
+  return value;
+}
+function csvEscape(text) {
+  if (/[",\r\n]/.test(text)) {
+    return `"${text.replace(/"/g, '""')}"`;
+  }
+  return text;
+}
+function formatTable(result) {
+  if (result.columns.length === 0) {
+    return `(${String(result.rowCount)} row(s) affected)`;
+  }
+  const headers = result.columns.map((column) => column.name);
+  const rows = result.rows.map(
+    (row) => result.columns.map((column) => cellText(row[column.name] ?? null, "NULL"))
+  );
+  const widths = headers.map((header, index) => {
+    const widest = rows.reduce(
+      (max, cells) => Math.max(max, (cells[index] ?? "").length),
+      header.length
+    );
+    return widest;
+  });
+  const renderRow = (cells) => cells.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join(" | ");
+  const separator = widths.map((width) => "-".repeat(width)).join("-+-");
+  const body = rows.map((cells) => renderRow(cells));
+  return [renderRow(headers), separator, ...body].join("\n");
+}
+function formatJson(result) {
+  const rows = result.rows.map((row) => {
+    const serialized = {};
+    for (const [key, value] of Object.entries(row)) {
+      serialized[key] = serializeCell(value);
+    }
+    return serialized;
+  });
+  return JSON.stringify(rows, null, 2);
+}
+function formatCsv(result) {
+  const headers = result.columns.map((column) => column.name);
+  const lines = [headers.map((header) => csvEscape(header)).join(",")];
+  for (const row of result.rows) {
+    lines.push(
+      result.columns.map((column) => csvEscape(cellText(row[column.name] ?? null, ""))).join(",")
+    );
+  }
+  return lines.join("\r\n");
+}
+function formatResult(result, format) {
+  switch (format) {
+    case "table":
+      return formatTable(result);
+    case "json":
+      return formatJson(result);
+    case "csv":
+      return formatCsv(result);
+  }
+}
+
 // src/statements.ts
 var LEADING_NOISE = /^(?:\s|--[^\n]*\n?|\/\*[\s\S]*?\*\/)+/;
 var SELECT_KEYWORDS = /* @__PURE__ */ new Set(["SELECT", "WITH"]);
@@ -134,6 +225,182 @@ function assertParamArity(sql, params) {
   }
 }
 
+// src/backup.ts
+var SAPTOOLS_DIR_NAME = ".saptools";
+var CF_HANA_DIR_NAME = "cf-hana";
+var BACKUPS_DIR_NAME = "backups";
+function defaultSaptoolsRoot() {
+  return join(homedir(), SAPTOOLS_DIR_NAME);
+}
+function trimStatementSql(sql) {
+  return sql.trim().replace(/;+\s*$/, "").trim();
+}
+function isIdentifierChar(char) {
+  return char !== void 0 && /[A-Za-z0-9_$#]/.test(char);
+}
+function skipQuotedText(sql, index) {
+  const quote = sql[index];
+  let cursor = index + 1;
+  while (cursor < sql.length) {
+    if (sql[cursor] === quote) {
+      if (sql[cursor + 1] === quote) {
+        cursor += 2;
+        continue;
+      }
+      return cursor + 1;
+    }
+    cursor += 1;
+  }
+  return cursor;
+}
+function skipLineComment(sql, index) {
+  let cursor = index + 2;
+  while (cursor < sql.length && sql[cursor] !== "\n") {
+    cursor += 1;
+  }
+  return cursor;
+}
+function skipBlockComment(sql, index) {
+  let cursor = index + 2;
+  while (cursor < sql.length && !(sql[cursor] === "*" && sql[cursor + 1] === "/")) {
+    cursor += 1;
+  }
+  return Math.min(cursor + 2, sql.length);
+}
+function skipNonCode(sql, index) {
+  const char = sql[index];
+  if (char === "'" || char === '"') {
+    return skipQuotedText(sql, index);
+  }
+  if (char === "-" && sql[index + 1] === "-") {
+    return skipLineComment(sql, index);
+  }
+  if (char === "/" && sql[index + 1] === "*") {
+    return skipBlockComment(sql, index);
+  }
+  return void 0;
+}
+function keywordMatches(sql, index, keyword) {
+  const end = index + keyword.length;
+  return sql.slice(index, end).toUpperCase() === keyword && !isIdentifierChar(sql[index - 1]) && !isIdentifierChar(sql[end]);
+}
+function findTopLevelKeyword(sql, keyword, startIndex = 0) {
+  let index = startIndex;
+  let depth = 0;
+  while (index < sql.length) {
+    const skipped = skipNonCode(sql, index);
+    if (skipped !== void 0) {
+      index = skipped;
+      continue;
+    }
+    const char = sql[index];
+    if (char === "(") {
+      depth += 1;
+    } else if (char === ")" && depth > 0) {
+      depth -= 1;
+    } else if (depth === 0 && keywordMatches(sql, index, keyword)) {
+      return index;
+    }
+    index += 1;
+  }
+  return void 0;
+}
+function selectParamsAfterWhere(statementSql, whereIndex, params) {
+  return params.slice(countPlaceholders(statementSql.slice(0, whereIndex)));
+}
+function buildSelectPlan(operation, statementSql, targetSql, whereIndex, params) {
+  const target = targetSql.trim();
+  if (target.length === 0) {
+    throw new QueryError(`${operation.toUpperCase()} backup requires a target table`);
+  }
+  if (whereIndex === void 0) {
+    return { operation, statementSql, selectSql: `SELECT * FROM ${target}`, selectParams: [] };
+  }
+  const whereSql = statementSql.slice(whereIndex + "WHERE".length).trim();
+  if (whereSql.length === 0) {
+    throw new QueryError(`${operation.toUpperCase()} backup requires a non-empty WHERE clause`);
+  }
+  return {
+    operation,
+    statementSql,
+    selectSql: `SELECT * FROM ${target} WHERE ${whereSql}`,
+    selectParams: selectParamsAfterWhere(statementSql, whereIndex, params)
+  };
+}
+function buildUpdateBackupPlan(statementSql, params) {
+  const updateIndex = findTopLevelKeyword(statementSql, "UPDATE");
+  const setIndex = updateIndex === void 0 ? void 0 : findTopLevelKeyword(statementSql, "SET", updateIndex + "UPDATE".length);
+  if (updateIndex === void 0 || setIndex === void 0) {
+    throw new QueryError("UPDATE backup requires UPDATE <target> SET syntax");
+  }
+  const whereIndex = findTopLevelKeyword(statementSql, "WHERE", setIndex + "SET".length);
+  return buildSelectPlan(
+    "update",
+    statementSql,
+    statementSql.slice(updateIndex + "UPDATE".length, setIndex),
+    whereIndex,
+    params
+  );
+}
+function buildDeleteBackupPlan(statementSql, params) {
+  const deleteIndex = findTopLevelKeyword(statementSql, "DELETE");
+  const fromIndex = deleteIndex === void 0 ? void 0 : findTopLevelKeyword(statementSql, "FROM", deleteIndex + "DELETE".length);
+  if (deleteIndex === void 0 || fromIndex === void 0) {
+    throw new QueryError("DELETE backup requires DELETE FROM <target> syntax");
+  }
+  const whereIndex = findTopLevelKeyword(statementSql, "WHERE", fromIndex + "FROM".length);
+  const targetEnd = whereIndex ?? statementSql.length;
+  return buildSelectPlan(
+    "delete",
+    statementSql,
+    statementSql.slice(fromIndex + "FROM".length, targetEnd),
+    whereIndex,
+    params
+  );
+}
+function backupTimestamp(now) {
+  return now.toISOString().replace(/:/g, "").replace(".", "");
+}
+function backupHash(statementSql) {
+  return createHash("sha256").update(statementSql).update("\0").update(randomUUID()).digest("hex").slice(0, 12);
+}
+function cfHanaBackupRoot(saptoolsRoot) {
+  return join(saptoolsRoot ?? defaultSaptoolsRoot(), CF_HANA_DIR_NAME, BACKUPS_DIR_NAME);
+}
+function buildWriteBackupPlan(sql, params = []) {
+  const statementSql = trimStatementSql(sql);
+  const keyword = firstKeyword(statementSql);
+  if (keyword !== "UPDATE" && keyword !== "DELETE") {
+    return void 0;
+  }
+  assertParamArity(statementSql, params);
+  if (keyword === "UPDATE") {
+    return buildUpdateBackupPlan(statementSql, params);
+  }
+  return buildDeleteBackupPlan(statementSql, params);
+}
+async function writeSqlBackup(input, options = {}) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const directory = join(
+    cfHanaBackupRoot(options.saptoolsRoot),
+    `${backupTimestamp(now)}-${input.operation}-${backupHash(input.statementSql)}`
+  );
+  const statementPath = join(directory, "statement.sql");
+  const backupPath = join(directory, "backup.csv");
+  await mkdir(directory, { recursive: true, mode: 448 });
+  await Promise.all([
+    writeFile(statementPath, `${input.statementSql}
+`, { encoding: "utf8", mode: 384 }),
+    writeFile(backupPath, formatCsv(input.result), { encoding: "utf8", mode: 384 })
+  ]);
+  return {
+    directory,
+    statementPath,
+    backupPath,
+    rowCount: input.result.rowCount
+  };
+}
+
 // src/builder.ts
 function buildWhere(where) {
   if (where === void 0) {
@@ -247,7 +514,7 @@ async function listColumns(connection, schema, table) {
 
 // src/config.ts
 var CLI_NAME = "cf-hana";
-var CLI_VERSION = "0.1.2";
+var CLI_VERSION = "0.1.4";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -669,10 +936,85 @@ function createDriver(name) {
   }
 }
 
+// src/history.ts
+import { appendFile, mkdir as mkdir2, readdir, rm } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+var SAPTOOLS_DIR_NAME2 = ".saptools";
+var CF_HANA_DIR_NAME2 = "cf-hana";
+var HISTORIES_DIR_NAME = "histories";
+var HISTORY_RETENTION_DAYS = 5;
+var HISTORY_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
+function defaultSaptoolsRoot2() {
+  return join2(homedir2(), SAPTOOLS_DIR_NAME2);
+}
+function padDatePart(value) {
+  return value.toString().padStart(2, "0");
+}
+function dateKey(date) {
+  return [
+    date.getFullYear().toString(),
+    padDatePart(date.getMonth() + 1),
+    padDatePart(date.getDate())
+  ].join("-");
+}
+function retentionCutoffKey(now) {
+  const cutoff = new Date(now);
+  cutoff.setHours(0, 0, 0, 0);
+  cutoff.setDate(cutoff.getDate() - HISTORY_RETENTION_DAYS);
+  return dateKey(cutoff);
+}
+function resolveSaptoolsRoot(root) {
+  return root ?? defaultSaptoolsRoot2();
+}
+function cfHanaHistoryDirectory(saptoolsRoot) {
+  return join2(resolveSaptoolsRoot(saptoolsRoot), CF_HANA_DIR_NAME2, HISTORIES_DIR_NAME);
+}
+function sqlHistoryFilePath(now = /* @__PURE__ */ new Date(), saptoolsRoot) {
+  return join2(cfHanaHistoryDirectory(saptoolsRoot), `${dateKey(now)}.jsonl`);
+}
+async function pruneSqlHistory(now, saptoolsRoot) {
+  const historyDir = cfHanaHistoryDirectory(saptoolsRoot);
+  let files;
+  try {
+    files = await readdir(historyDir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  const cutoffKey = retentionCutoffKey(now);
+  await Promise.all(
+    files.filter((file) => HISTORY_FILE_PATTERN.test(file)).filter((file) => file.slice(0, 10) < cutoffKey).map(async (file) => {
+      await rm(join2(historyDir, file), { force: true });
+    })
+  );
+}
+async function appendSqlHistory(input, options = {}) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const historyDir = cfHanaHistoryDirectory(options.saptoolsRoot);
+  const entry = {
+    at: now.toISOString(),
+    ...input
+  };
+  await mkdir2(historyDir, { recursive: true, mode: 448 });
+  await appendFile(sqlHistoryFilePath(now, options.saptoolsRoot), `${JSON.stringify(entry)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+  try {
+    await pruneSqlHistory(now, options.saptoolsRoot);
+  } catch {
+  }
+  return entry;
+}
+
 // src/safety.ts
 var DESTRUCTIVE_DDL_KEYWORDS = /* @__PURE__ */ new Set(["DROP", "TRUNCATE", "ALTER"]);
 var UNSCOPED_WRITE_KEYWORDS = /* @__PURE__ */ new Set(["UPDATE", "DELETE"]);
-function skipQuotedText(sql, start) {
+function skipQuotedText2(sql, start) {
   const quote = sql[start];
   let index = start + 1;
   while (index < sql.length) {
@@ -688,14 +1030,14 @@ function skipQuotedText(sql, start) {
   }
   return index;
 }
-function skipLineComment(sql, start) {
+function skipLineComment2(sql, start) {
   let index = start + 2;
   while (index < sql.length && sql[index] !== "\n") {
     index += 1;
   }
   return index;
 }
-function skipBlockComment(sql, start) {
+function skipBlockComment2(sql, start) {
   let index = start + 2;
   while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/")) {
     index += 1;
@@ -708,19 +1050,19 @@ function maskIgnoredSqlText(sql) {
   while (index < sql.length) {
     const char = sql[index];
     if (char === "'" || char === '"') {
-      const end = skipQuotedText(sql, index);
+      const end = skipQuotedText2(sql, index);
       masked += " ".repeat(end - index);
       index = end;
       continue;
     }
     if (char === "-" && sql[index + 1] === "-") {
-      const end = skipLineComment(sql, index);
+      const end = skipLineComment2(sql, index);
       masked += " ".repeat(end - index);
       index = end;
       continue;
     }
     if (char === "/" && sql[index + 1] === "*") {
-      const end = skipBlockComment(sql, index);
+      const end = skipBlockComment2(sql, index);
       masked += " ".repeat(end - index);
       index = end;
       continue;
@@ -738,11 +1080,11 @@ function trailingLineCommentIndex(sql) {
   while (index < sql.length) {
     const char = sql[index];
     if (char === "'" || char === '"') {
-      index = skipQuotedText(sql, index);
+      index = skipQuotedText2(sql, index);
       continue;
     }
     if (char === "/" && sql[index + 1] === "*") {
-      index = skipBlockComment(sql, index);
+      index = skipBlockComment2(sql, index);
       continue;
     }
     if (char === "-" && sql[index + 1] === "-") {
@@ -1167,41 +1509,64 @@ var HanaClient = class _HanaClient {
   }
   /** Run a SELECT (or any read) statement and return typed rows. */
   async query(sql, params, options) {
-    return await this.pool.withConnection(
-      (connection) => connection.query(sql, params, options)
-    );
+    const resolvedParams = params ?? [];
+    const result = await this.runQuery(sql, resolvedParams, options);
+    await this.recordSqlHistory("query", sql, resolvedParams, result);
+    return result;
   }
   /** Run a DML/DDL statement and return its affected-row count. */
   async execute(sql, params, options) {
-    return await this.pool.withConnection(
-      (connection) => connection.execute(sql, params, options)
-    );
+    const resolvedParams = params ?? [];
+    const result = await this.runExecute(sql, resolvedParams, options);
+    await this.recordSqlHistory("execute", sql, resolvedParams, result);
+    return result;
+  }
+  /** Back up rows matched by an UPDATE or DELETE before the caller runs it. */
+  async backupWriteStatement(sql, params, options) {
+    const resolvedParams = params ?? [];
+    const plan = buildWriteBackupPlan(sql, resolvedParams);
+    if (plan === void 0) {
+      return void 0;
+    }
+    return await this.pool.withConnection(async (connection) => {
+      connection.assertAllowed(plan.statementSql, options);
+      const backupQueryOptions = {
+        autoLimit: false,
+        ...options?.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+      };
+      const result = await connection.query(plan.selectSql, plan.selectParams, backupQueryOptions);
+      return await writeSqlBackup({
+        operation: plan.operation,
+        statementSql: plan.statementSql,
+        result
+      });
+    });
   }
   /** Run a typed `SELECT` built from a spec. */
   async selectFrom(spec) {
     const built = buildSelect(spec);
-    return await this.query(built.sql, built.params);
+    return await this.runQuery(built.sql, built.params);
   }
   /** Count rows in a table, optionally filtered. */
   async count(spec) {
     const built = buildCount(spec);
-    const result = await this.query(built.sql, built.params);
+    const result = await this.runQuery(built.sql, built.params);
     return result.rows[0]?.COUNT ?? 0;
   }
   /** Insert a single row. */
   async insertInto(schema, table, values) {
     const built = buildInsert(schema, table, values);
-    return await this.execute(built.sql, built.params);
+    return await this.runExecute(built.sql, built.params);
   }
   /** Update rows matching a non-empty `where` filter. */
   async update(schema, table, values, where) {
     const built = buildUpdate(schema, table, values, where);
-    return await this.execute(built.sql, built.params);
+    return await this.runExecute(built.sql, built.params);
   }
   /** Delete rows matching a non-empty `where` filter. */
   async deleteFrom(schema, table, where) {
     const built = buildDelete(schema, table, where);
-    return await this.execute(built.sql, built.params);
+    return await this.runExecute(built.sql, built.params);
   }
   /** Run `work` inside a transaction, auto-committing on success. */
   async transaction(work) {
@@ -1280,6 +1645,35 @@ var HanaClient = class _HanaClient {
   async close() {
     await this.pool.drain();
   }
+  async runQuery(sql, params, options) {
+    return await this.pool.withConnection(
+      (connection) => connection.query(sql, params, options)
+    );
+  }
+  async runExecute(sql, params, options) {
+    return await this.pool.withConnection(
+      (connection) => connection.execute(sql, params, options)
+    );
+  }
+  async recordSqlHistory(operation, sql, params, result) {
+    try {
+      await appendSqlHistory({
+        version: CLI_VERSION,
+        operation,
+        selector: this.info.selector,
+        appName: this.info.appName,
+        schema: this.info.schema,
+        role: this.info.role,
+        statement: result.statement,
+        sql,
+        paramCount: params.length,
+        rowCount: result.rowCount,
+        truncated: result.truncated,
+        elapsedMs: result.elapsedMs
+      });
+    } catch {
+    }
+  }
 };
 
 // src/api.ts
@@ -1287,91 +1681,6 @@ async function connect(selector, options) {
   return await HanaClient.connect(selector, options);
 }
 
-// src/format.ts
-function cellText(value, nullText) {
-  if (value === null) {
-    return nullText;
-  }
-  if (value instanceof Date) {
-    return value.toISOString();
-  }
-  if (Buffer.isBuffer(value)) {
-    return `0x${value.toString("hex")}`;
-  }
-  if (typeof value === "boolean") {
-    return value ? "true" : "false";
-  }
-  return typeof value === "number" ? value.toString() : value;
-}
-function serializeCell(value) {
-  if (value === null) {
-    return null;
-  }
-  if (value instanceof Date) {
-    return value.toISOString();
-  }
-  if (Buffer.isBuffer(value)) {
-    return `0x${value.toString("hex")}`;
-  }
-  return value;
-}
-function csvEscape(text) {
-  if (/[",\r\n]/.test(text)) {
-    return `"${text.replace(/"/g, '""')}"`;
-  }
-  return text;
-}
-function formatTable(result) {
-  if (result.columns.length === 0) {
-    return `(${String(result.rowCount)} row(s) affected)`;
-  }
-  const headers = result.columns.map((column) => column.name);
-  const rows = result.rows.map(
-    (row) => result.columns.map((column) => cellText(row[column.name] ?? null, "NULL"))
-  );
-  const widths = headers.map((header, index) => {
-    const widest = rows.reduce(
-      (max, cells) => Math.max(max, (cells[index] ?? "").length),
-      header.length
-    );
-    return widest;
-  });
-  const renderRow = (cells) => cells.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join(" | ");
-  const separator = widths.map((width) => "-".repeat(width)).join("-+-");
-  const body = rows.map((cells) => renderRow(cells));
-  return [renderRow(headers), separator, ...body].join("\n");
-}
-function formatJson(result) {
-  const rows = result.rows.map((row) => {
-    const serialized = {};
-    for (const [key, value] of Object.entries(row)) {
-      serialized[key] = serializeCell(value);
-    }
-    return serialized;
-  });
-  return JSON.stringify(rows, null, 2);
-}
-function formatCsv(result) {
-  const headers = result.columns.map((column) => column.name);
-  const lines = [headers.map((header) => csvEscape(header)).join(",")];
-  for (const row of result.rows) {
-    lines.push(
-      result.columns.map((column) => csvEscape(cellText(row[column.name] ?? null, ""))).join(",")
-    );
-  }
-  return lines.join("\r\n");
-}
-function formatResult(result, format) {
-  switch (format) {
-    case "table":
-      return formatTable(result);
-    case "json":
-      return formatJson(result);
-    case "csv":
-      return formatCsv(result);
-  }
-}
-
 // src/cli.ts
 function print(text) {
   process.stdout.write(`${text}
@@ -1470,7 +1779,13 @@ async function runQuery(selector, sql, command) {
   const opts = command.opts();
   const client = await connect(selector, toConnectOptions(opts));
   try {
-    const result = await client.query(sql, opts.param ?? []);
+    const params = opts.param ?? [];
+    const backup = opts.backup ? await client.backupWriteStatement(sql, params) : void 0;
+    if (backup !== void 0) {
+      process.stderr.write(`${CLI_NAME}: backup saved to ${backup.directory}
+`);
+    }
+    const result = await client.query(sql, params);
     print(formatResult(result, parseFormat(opts.format)));
   } finally {
     await client.close();
@@ -1546,7 +1861,7 @@ function buildProgram() {
   const program = new Command();
   program.name(CLI_NAME).description("Run SQL against SAP HANA Cloud databases bound to a Cloud Foundry app").version(CLI_VERSION);
   withConnectionOptions(
-    program.command("query <selector> <sql>").description("run a single SQL statement").option("--param <value>", "bind a SQL parameter (repeatable)", collectParam, [])
+    program.command("query <selector> <sql>").description("run a single SQL statement").option("--param <value>", "bind a SQL parameter (repeatable)", collectParam, []).option("--no-backup", "skip the local CSV backup before UPDATE or DELETE")
   ).action(async (selector, sql, _options, command) => {
     await runQuery(selector, sql, command);
   });