@saptools/cf-hana 0.3.4 → 0.4.0

package/dist/index.js

@@ -5,6 +5,44 @@ import { mkdir, writeFile } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
 
+// src/config.ts
+var CLI_VERSION = "0.4.0";
+var ENV_PREFIX = "CF_HANA";
+var DEFAULT_QUERY_TIMEOUT_MS = 6e4;
+var DEFAULT_CONNECT_TIMEOUT_MS = 6e4;
+var DEFAULT_POOL_MAX = 4;
+var DEFAULT_POOL_IDLE_MS = 6e4;
+var DEFAULT_AUTO_LIMIT = 100;
+var DEFAULT_MAX_RESULT_STORE_BYTES = 256 * 1024 * 1024;
+var MAX_RESULT_STORE_BYTES = resolveMaxResultStoreBytes();
+function resolveMaxResultStoreBytes() {
+  if (readEnv(envName("DRIVER")) !== "fake") {
+    return DEFAULT_MAX_RESULT_STORE_BYTES;
+  }
+  const raw = readEnv(envName("FAKE_MAX_STORE_BYTES"));
+  const parsed = raw === void 0 ? Number.NaN : Number(raw);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_RESULT_STORE_BYTES;
+}
+function envName(suffix) {
+  return `${ENV_PREFIX}_${suffix}`;
+}
+function readEnv(name) {
+  const value = process.env[name];
+  if (value === void 0) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? void 0 : trimmed;
+}
+function readSapCredentials(overrides) {
+  const email = overrides?.email ?? readEnv("SAP_EMAIL");
+  const password = overrides?.password ?? readEnv("SAP_PASSWORD");
+  if (email === void 0 || password === void 0) {
+    return void 0;
+  }
+  return { email, password };
+}
+
 // src/errors.ts
 var CfHanaError = class extends Error {
   code;
@@ -31,6 +69,12 @@ var QueryError = class extends CfHanaError {
     this.databaseCode = options?.databaseCode;
   }
 };
+var BackupRequiredError = class extends CfHanaError {
+  constructor(message, options) {
+    super("BACKUP_REQUIRED", message, options);
+    this.name = "BackupRequiredError";
+  }
+};
 function isDatabaseErrorShape(error) {
   return typeof error === "object" && error !== null && "code" in error;
 }
@@ -146,6 +190,16 @@ function formatJson(result) {
   });
   return JSON.stringify(rows, null, 2);
 }
+function formatJsonCompact(result, preferredColumn) {
+  const singleColumn = result.columns.length === 1 ? result.columns[0]?.name : void 0;
+  const columnName = preferredColumn ?? singleColumn;
+  if (columnName === void 0) {
+    return formatJson(result);
+  }
+  const column = result.columns.find((item) => item.name === columnName);
+  const values = result.rows.map((row) => serializeCell(row[columnName] ?? null, column));
+  return JSON.stringify(values, null, 2);
+}
 function formatCsv(result) {
   const headers = result.columns.map((column) => column.name);
   const lines = [headers.map((header) => csvEscape(header)).join(",")];
@@ -156,115 +210,20 @@ function formatCsv(result) {
   }
   return lines.join("\r\n");
 }
-function formatResult(result, format) {
+function formatResult(result, format, compactColumn) {
   switch (format) {
     case "table":
       return formatTable(result);
     case "json":
       return formatJson(result);
+    case "json-compact":
+      return formatJsonCompact(result, compactColumn);
     case "csv":
       return formatCsv(result);
   }
 }
 
-// src/statements.ts
-var LEADING_NOISE = /^(?:\s|--[^\n]*\n?|\/\*[\s\S]*?\*\/)+/;
-var SELECT_KEYWORDS = /* @__PURE__ */ new Set(["SELECT", "WITH"]);
-var DML_KEYWORDS = /* @__PURE__ */ new Set(["INSERT", "UPDATE", "DELETE", "MERGE", "UPSERT", "REPLACE"]);
-var DDL_KEYWORDS = /* @__PURE__ */ new Set(["CREATE", "DROP", "ALTER", "TRUNCATE", "RENAME", "COMMENT"]);
-function firstKeyword(sql) {
-  const stripped = sql.replace(LEADING_NOISE, "");
-  const match = /^[A-Za-z]+/.exec(stripped);
-  return (match?.[0] ?? "").toUpperCase();
-}
-function classifyStatement(sql) {
-  const keyword = firstKeyword(sql);
-  if (SELECT_KEYWORDS.has(keyword)) {
-    return "select";
-  }
-  if (DML_KEYWORDS.has(keyword)) {
-    return "dml";
-  }
-  if (DDL_KEYWORDS.has(keyword)) {
-    return "ddl";
-  }
-  return "unknown";
-}
-function quoteIdentifier(identifier) {
-  if (identifier.length === 0) {
-    throw new QueryError("A SQL identifier must not be empty");
-  }
-  if (identifier.includes("\0")) {
-    throw new QueryError("A SQL identifier must not contain a NUL character");
-  }
-  return `"${identifier.replace(/"/g, '""')}"`;
-}
-function qualifiedName(schema, table) {
-  return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
-}
-function countPlaceholders(sql) {
-  let count = 0;
-  let index = 0;
-  const length = sql.length;
-  while (index < length) {
-    const char = sql[index];
-    if (char === "'" || char === '"') {
-      const quote = char;
-      index += 1;
-      while (index < length) {
-        if (sql[index] === quote) {
-          if (sql[index + 1] === quote) {
-            index += 2;
-            continue;
-          }
-          index += 1;
-          break;
-        }
-        index += 1;
-      }
-      continue;
-    }
-    if (char === "-" && sql[index + 1] === "-") {
-      index += 2;
-      while (index < length && sql[index] !== "\n") {
-        index += 1;
-      }
-      continue;
-    }
-    if (char === "/" && sql[index + 1] === "*") {
-      index += 2;
-      while (index < length && !(sql[index] === "*" && sql[index + 1] === "/")) {
-        index += 1;
-      }
-      index += 2;
-      continue;
-    }
-    if (char === "?") {
-      count += 1;
-    }
-    index += 1;
-  }
-  return count;
-}
-function assertParamArity(sql, params) {
-  const expected = countPlaceholders(sql);
-  if (expected !== params.length) {
-    throw new QueryError(
-      `SQL expects ${String(expected)} bound parameter(s) but received ${String(params.length)} value(s)`
-    );
-  }
-}
-
-// 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();
-}
+// src/003-backup-sql-parser.ts
 function isIdentifierChar(char) {
   return char !== void 0 && /[A-Za-z0-9_$#]/.test(char);
 }
@@ -310,6 +269,105 @@ function skipNonCode(sql, index) {
   }
   return void 0;
 }
+function skipTrivia(sql, start, end) {
+  let index = start;
+  while (index < end) {
+    if (/\s/.test(sql.charAt(index))) {
+      index += 1;
+      continue;
+    }
+    if (sql[index] === "-" && sql[index + 1] === "-") {
+      index = skipLineComment(sql, index);
+      continue;
+    }
+    if (sql[index] === "/" && sql[index + 1] === "*") {
+      index = skipBlockComment(sql, index);
+      continue;
+    }
+    break;
+  }
+  return index;
+}
+function readIdentifierPart(sql, start, end) {
+  const index = skipTrivia(sql, start, end);
+  if (sql[index] === '"') {
+    const next2 = skipQuotedText(sql, index);
+    return next2 <= end && sql[next2 - 1] === '"' ? { sql: sql.slice(index, next2), end: next2 } : void 0;
+  }
+  if (!/[A-Za-z_#$]/.test(sql.charAt(index))) {
+    return void 0;
+  }
+  let next = index + 1;
+  while (next < end && /[A-Za-z0-9_#$]/.test(sql.charAt(next))) {
+    next += 1;
+  }
+  return { sql: sql.slice(index, next), end: next };
+}
+function readQualifiedTarget(sql, start, end) {
+  const first = readIdentifierPart(sql, start, end);
+  if (first === void 0) {
+    return void 0;
+  }
+  const parts = [first.sql];
+  let cursor = first.end;
+  while (parts.length < 3) {
+    const dot = skipTrivia(sql, cursor, end);
+    if (sql[dot] !== ".") {
+      break;
+    }
+    const part = readIdentifierPart(sql, dot + 1, end);
+    if (part === void 0) {
+      return void 0;
+    }
+    parts.push(part.sql);
+    cursor = part.end;
+  }
+  return { sql: parts.join("."), reference: parts.at(-1) ?? first.sql, end: cursor };
+}
+function topLevelTokens(sql) {
+  const tokens = [];
+  let index = 0;
+  let depth = 0;
+  while (index < sql.length) {
+    const skipped = skipNonCode(sql, index);
+    if (skipped !== void 0) {
+      index = skipped;
+      continue;
+    }
+    const char = sql.charAt(index);
+    if (char === "(") {
+      depth += 1;
+      index += 1;
+      continue;
+    }
+    if (char === ")") {
+      depth = Math.max(0, depth - 1);
+      index += 1;
+      continue;
+    }
+    if (!/[A-Za-z_#$]/.test(char)) {
+      index += 1;
+      continue;
+    }
+    let end = index + 1;
+    while (end < sql.length && /[A-Za-z0-9_#$]/.test(sql.charAt(end))) {
+      end += 1;
+    }
+    if (depth === 0) {
+      tokens.push({ keyword: sql.slice(index, end).toUpperCase(), start: index, end });
+    }
+    index = end;
+  }
+  return tokens;
+}
+function findToken(tokens, keyword, start = 0) {
+  for (let index = start; index < tokens.length; index += 1) {
+    if (tokens[index]?.keyword === keyword) {
+      return 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]);
@@ -357,6 +415,158 @@ function findTopLevelChar(sql, target, startIndex, endIndex) {
   }
   return void 0;
 }
+
+// src/statements.ts
+var SELECT_KEYWORDS = /* @__PURE__ */ new Set(["SELECT", "WITH"]);
+var DML_KEYWORDS = /* @__PURE__ */ new Set(["INSERT", "UPDATE", "DELETE", "MERGE", "UPSERT", "REPLACE"]);
+var DDL_KEYWORDS = /* @__PURE__ */ new Set(["CREATE", "DROP", "ALTER", "TRUNCATE", "RENAME", "COMMENT"]);
+function firstKeyword(sql) {
+  let index = 0;
+  while (index < sql.length) {
+    const char = sql.charAt(index);
+    if (char.trim().length === 0) {
+      index += 1;
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      index += 2;
+      while (index < sql.length && sql[index] !== "\n") {
+        index += 1;
+      }
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      const commentEnd = sql.indexOf("*/", index + 2);
+      if (commentEnd === -1) {
+        return "";
+      }
+      index = commentEnd + 2;
+      continue;
+    }
+    break;
+  }
+  let keywordEnd = index;
+  while (keywordEnd < sql.length) {
+    const code = sql.charCodeAt(keywordEnd);
+    const isUpperCase = code >= 65 && code <= 90;
+    const isLowerCase = code >= 97 && code <= 122;
+    if (!isUpperCase && !isLowerCase) {
+      break;
+    }
+    keywordEnd += 1;
+  }
+  return sql.slice(index, keywordEnd).toUpperCase();
+}
+function classifyStatement(sql) {
+  const keyword = firstKeyword(sql);
+  if (SELECT_KEYWORDS.has(keyword)) {
+    return "select";
+  }
+  if (DML_KEYWORDS.has(keyword)) {
+    return "dml";
+  }
+  if (DDL_KEYWORDS.has(keyword)) {
+    return "ddl";
+  }
+  return "unknown";
+}
+function quoteIdentifier(identifier) {
+  if (identifier.length === 0) {
+    throw new QueryError("A SQL identifier must not be empty");
+  }
+  if (identifier.includes("\0")) {
+    throw new QueryError("A SQL identifier must not contain a NUL character");
+  }
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+function qualifiedName(schema, table) {
+  return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+}
+function countPlaceholders(sql) {
+  let count = 0;
+  let index = 0;
+  const length = sql.length;
+  while (index < length) {
+    const char = sql[index];
+    if (char === "'" || char === '"') {
+      const quote = char;
+      index += 1;
+      while (index < length) {
+        if (sql[index] === quote) {
+          if (sql[index + 1] === quote) {
+            index += 2;
+            continue;
+          }
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      index += 2;
+      while (index < length && sql[index] !== "\n") {
+        index += 1;
+      }
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      index += 2;
+      while (index < length && !(sql[index] === "*" && sql[index + 1] === "/")) {
+        index += 1;
+      }
+      index += 2;
+      continue;
+    }
+    if (char === "?") {
+      count += 1;
+    }
+    index += 1;
+  }
+  return count;
+}
+function assertParamArity(sql, params) {
+  const expected = countPlaceholders(sql);
+  if (expected !== params.length) {
+    throw new QueryError(
+      `SQL expects ${String(expected)} bound parameter(s) but received ${String(params.length)} value(s)`
+    );
+  }
+}
+
+// src/001-backup-planner.ts
+var WRITE_KEYWORDS = /* @__PURE__ */ new Set([
+  "UPDATE",
+  "UPSERT",
+  "REPLACE",
+  "MERGE",
+  "DELETE"
+]);
+var MERGE_MODIFY_ACTIONS = /* @__PURE__ */ new Set(["UPDATE", "DELETE"]);
+function trimStatementSql(sql) {
+  const trimmed = sql.trim();
+  let end = trimmed.length;
+  while (end > 0 && trimmed.charAt(end - 1) === ";") {
+    end -= 1;
+  }
+  return trimmed.slice(0, end).trim();
+}
+function isMergeClauseStart(tokens, index) {
+  if (tokens[index]?.keyword !== "WHEN") {
+    return false;
+  }
+  return tokens[index + 1]?.keyword === "MATCHED" || tokens[index + 1]?.keyword === "NOT" && tokens[index + 2]?.keyword === "MATCHED";
+}
+function mergeClauseIndexes(tokens, start) {
+  const indexes = [];
+  for (let index = start; index < tokens.length; index += 1) {
+    if (isMergeClauseStart(tokens, index)) {
+      indexes.push(index);
+    }
+  }
+  return indexes;
+}
 function selectParamsAfterWhere(statementSql, whereIndex, params) {
   return params.slice(countPlaceholders(statementSql.slice(0, whereIndex)));
 }
@@ -394,23 +604,178 @@ function buildUpdateBackupPlan(statementSql, params) {
     params
   );
 }
-function buildUpsertBackupPlan(statementSql, params) {
-  const upsertIndex = findTopLevelKeyword(statementSql, "UPSERT");
-  const valuesIndex = upsertIndex === void 0 ? void 0 : findTopLevelKeyword(statementSql, "VALUES", upsertIndex + "UPSERT".length);
-  if (upsertIndex === void 0 || valuesIndex === void 0) {
-    throw new QueryError("UPSERT backup requires UPSERT <target> VALUES syntax");
+function buildUpsertBackupPlan(statementSql, params, keyword) {
+  const operation = keyword === "UPSERT" ? "upsert" : "replace";
+  const keywordIndex = findTopLevelKeyword(statementSql, keyword);
+  const target = keywordIndex === void 0 ? void 0 : readQualifiedTarget(statementSql, keywordIndex + keyword.length, statementSql.length);
+  if (keywordIndex === void 0 || target === void 0) {
+    throw new BackupRequiredError(
+      `${keyword} write refused: cannot derive a trustworthy backup target`
+    );
+  }
+  const valuesIndex = findTopLevelKeyword(statementSql, "VALUES", target.end);
+  if (valuesIndex === void 0) {
+    const selectIndex = findTopLevelKeyword(statementSql, "SELECT", target.end);
+    const withIndex = findTopLevelKeyword(statementSql, "WITH", target.end);
+    if (selectIndex === void 0 && withIndex === void 0) {
+      throw new BackupRequiredError(
+        `${keyword} write refused: expected VALUES, WITH PRIMARY KEY, or a subquery`
+      );
+    }
+    return buildSelectPlan(operation, statementSql, target.sql, void 0, params);
   }
-  const targetStart = upsertIndex + "UPSERT".length;
-  const columnListIndex = findTopLevelChar(statementSql, "(", targetStart, valuesIndex);
-  const targetEnd = columnListIndex ?? valuesIndex;
   const whereIndex = findTopLevelKeyword(statementSql, "WHERE", valuesIndex + "VALUES".length);
-  return buildSelectPlan(
-    "upsert",
+  return buildSelectPlan(operation, statementSql, target.sql, whereIndex, params);
+}
+function mergeTargetReference(statementSql, target, usingStart) {
+  let suffix = statementSql.slice(target.end, usingStart).trim();
+  if (suffix.length === 0) {
+    return target.reference;
+  }
+  if (/^PARTITION\b/i.test(suffix)) {
+    const open = suffix.indexOf("(");
+    if (open === -1) {
+      return void 0;
+    }
+    const close = findTopLevelChar(suffix, ")", open + 1, suffix.length);
+    if (close === void 0) {
+      return void 0;
+    }
+    suffix = suffix.slice(close + 1).trim();
+    if (suffix.length === 0) {
+      return target.reference;
+    }
+  }
+  suffix = suffix.replace(/^AS\b/i, "").trim();
+  const alias = readIdentifierPart(suffix, 0, suffix.length);
+  if (alias === void 0 || skipTrivia(suffix, alias.end, suffix.length) !== suffix.length) {
+    return void 0;
+  }
+  return alias.sql;
+}
+function paramsInRange(sql, params, start, end) {
+  const offset = countPlaceholders(sql.slice(0, start));
+  const length = countPlaceholders(sql.slice(start, end));
+  return params.slice(offset, offset + length);
+}
+function wholeTargetPlan(operation, statementSql, target) {
+  return buildSelectPlan(operation, statementSql, target.sql, void 0, []);
+}
+function readRequiredMergeToken(tokens, keyword, start) {
+  const index = findToken(tokens, keyword, start);
+  const token = index === void 0 ? void 0 : tokens[index];
+  if (index === void 0 || token === void 0) {
+    throw new BackupRequiredError(
+      "MERGE write refused: cannot derive a trustworthy backup target"
+    );
+  }
+  return { index, token };
+}
+function parseMerge(statementSql) {
+  const tokens = topLevelTokens(statementSql);
+  const into = readRequiredMergeToken(tokens, "INTO", 1);
+  const using = readRequiredMergeToken(tokens, "USING", into.index + 1);
+  const on = readRequiredMergeToken(tokens, "ON", using.index + 1);
+  const target = readQualifiedTarget(statementSql, into.token.end, using.token.start);
+  if (target === void 0) {
+    throw new BackupRequiredError(
+      "MERGE write refused: cannot derive a trustworthy backup target"
+    );
+  }
+  const clauseIndexes = mergeClauseIndexes(tokens, on.index + 1);
+  if (clauseIndexes.length === 0) {
+    throw new BackupRequiredError("MERGE write refused: no supported WHEN clause was found");
+  }
+  const firstClause = tokens[clauseIndexes[0] ?? 0];
+  return {
+    tokens,
+    into: into.token,
+    using: using.token,
+    on: on.token,
+    target,
+    clauseIndexes,
+    matchedIndexes: clauseIndexes.filter((index) => tokens[index + 1]?.keyword === "MATCHED"),
+    targetClause: statementSql.slice(into.token.end, using.token.start).trim(),
+    sourceClause: statementSql.slice(using.token.end, on.token.start).trim(),
+    onCondition: statementSql.slice(on.token.end, firstClause?.start).trim()
+  };
+}
+function readMatchedActionTokens(tokens, matchedIndex) {
+  const thenIndex = findToken(tokens, "THEN", matchedIndex + 2);
+  if (thenIndex === void 0) {
+    return void 0;
+  }
+  const thenToken = tokens[thenIndex];
+  const actionToken = tokens[thenIndex + 1];
+  const matchedToken = tokens[matchedIndex + 1];
+  if (thenToken === void 0 || actionToken === void 0 || matchedToken === void 0) {
+    return void 0;
+  }
+  if (!MERGE_MODIFY_ACTIONS.has(actionToken.keyword)) {
+    return void 0;
+  }
+  const clauseToken = tokens[matchedIndex];
+  return {
+    thenToken,
+    conditionToken: tokens[matchedIndex + 2],
+    clauseStart: clauseToken === void 0 ? 0 : clauseToken.start
+  };
+}
+function parseMatchedClause(statementSql, params, tokens, matchedIndex) {
+  const action = readMatchedActionTokens(tokens, matchedIndex);
+  if (action?.conditionToken === void 0) {
+    return void 0;
+  }
+  if (action.conditionToken.keyword === "THEN") {
+    return { clauseStart: action.clauseStart, matchedCondition: "", conditionParams: [] };
+  }
+  if (action.conditionToken.keyword !== "AND") {
+    return void 0;
+  }
+  return {
+    clauseStart: action.clauseStart,
+    matchedCondition: statementSql.slice(action.conditionToken.end, action.thenToken.start).trim(),
+    conditionParams: paramsInRange(
+      statementSql,
+      params,
+      action.conditionToken.end,
+      action.thenToken.start
+    )
+  };
+}
+function buildExactMergePlan(statementSql, params, merge, matchedIndex) {
+  const targetReference = mergeTargetReference(statementSql, merge.target, merge.using.start);
+  const matchedClause = parseMatchedClause(statementSql, params, merge.tokens, matchedIndex);
+  if (targetReference === void 0 || matchedClause === void 0) {
+    return void 0;
+  }
+  const sourceParams = paramsInRange(
     statementSql,
-    statementSql.slice(targetStart, targetEnd),
-    whereIndex,
-    params
+    params,
+    merge.using.end,
+    matchedClause.clauseStart
   );
+  const conditionSql = matchedClause.matchedCondition.length === 0 ? "" : ` AND (${matchedClause.matchedCondition})`;
+  return {
+    operation: "merge",
+    statementSql,
+    selectSql: `SELECT ${targetReference}.* FROM ${merge.targetClause} WHERE EXISTS (SELECT 1 FROM ${merge.sourceClause} WHERE (${merge.onCondition})${conditionSql})`,
+    selectParams: [...sourceParams, ...matchedClause.conditionParams]
+  };
+}
+function buildMergeBackupPlan(statementSql, params) {
+  const merge = parseMerge(statementSql);
+  if (merge.matchedIndexes.length === 0) {
+    return void 0;
+  }
+  if (merge.matchedIndexes.length > 1) {
+    return wholeTargetPlan("merge", statementSql, merge.target);
+  }
+  if (merge.sourceClause.length === 0 || merge.onCondition.length === 0) {
+    return wholeTargetPlan("merge", statementSql, merge.target);
+  }
+  const matchedIndex = merge.matchedIndexes[0] ?? 0;
+  return buildExactMergePlan(statementSql, params, merge, matchedIndex) ?? wholeTargetPlan("merge", statementSql, merge.target);
 }
 function buildDeleteBackupPlan(statementSql, params) {
   const deleteIndex = findTopLevelKeyword(statementSql, "DELETE");
@@ -428,6 +793,49 @@ function buildDeleteBackupPlan(statementSql, params) {
     params
   );
 }
+function isWriteKeyword(keyword) {
+  return WRITE_KEYWORDS.has(keyword);
+}
+function buildMergeWriteBackupPlan(statementSql, params) {
+  const secondKeyword = topLevelTokens(statementSql)[1]?.keyword;
+  if (secondKeyword === "DELTA") {
+    return void 0;
+  }
+  if (secondKeyword !== "INTO") {
+    throw new BackupRequiredError("MERGE write refused: expected MERGE INTO syntax");
+  }
+  return buildMergeBackupPlan(statementSql, params);
+}
+function dispatchWriteBackupPlan(keyword, statementSql, params) {
+  switch (keyword) {
+    case "UPDATE":
+      return buildUpdateBackupPlan(statementSql, params);
+    case "UPSERT":
+    case "REPLACE":
+      return buildUpsertBackupPlan(statementSql, params, keyword);
+    case "MERGE":
+      return buildMergeWriteBackupPlan(statementSql, params);
+    case "DELETE":
+      return buildDeleteBackupPlan(statementSql, params);
+  }
+}
+function buildWriteBackupPlan(sql, params = []) {
+  const statementSql = trimStatementSql(sql);
+  const keyword = firstKeyword(statementSql);
+  if (!isWriteKeyword(keyword)) {
+    return void 0;
+  }
+  assertParamArity(statementSql, params);
+  return dispatchWriteBackupPlan(keyword, statementSql, 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 backupTimestamp(now) {
   return now.toISOString().replace(/:/g, "").replace(".", "");
 }
@@ -447,21 +855,6 @@ function backupBaseName(input, now) {
 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 !== "UPSERT" && keyword !== "DELETE") {
-    return void 0;
-  }
-  assertParamArity(statementSql, params);
-  if (keyword === "UPDATE") {
-    return buildUpdateBackupPlan(statementSql, params);
-  }
-  if (keyword === "UPSERT") {
-    return buildUpsertBackupPlan(statementSql, params);
-  }
-  return buildDeleteBackupPlan(statementSql, params);
-}
 async function writeSqlBackup(input, options = {}) {
   const now = options.now ?? /* @__PURE__ */ new Date();
   const directory = join(cfHanaBackupRoot(options.saptoolsRoot), backupMonth(now));
@@ -477,11 +870,17 @@ async function writeSqlBackup(input, options = {}) {
     rowCount: input.result.rowCount,
     createdAt: now.toISOString()
   };
+  const csv = formatCsv(input.result);
+  if (Buffer.byteLength(csv) > (options.maxBytes ?? MAX_RESULT_STORE_BYTES)) {
+    throw new BackupRequiredError(
+      "Write backup exceeds the storage limit; the write was refused"
+    );
+  }
   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 }),
+    writeFile(backupPath, csv, { encoding: "utf8", mode: 384 }),
     writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}
 `, {
       encoding: "utf8",
@@ -624,35 +1023,6 @@ async function listColumns(connection, schema, table) {
   }));
 }
 
-// src/config.ts
-var CLI_VERSION = "0.3.4";
-var ENV_PREFIX = "CF_HANA";
-var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
-var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
-var DEFAULT_POOL_MAX = 4;
-var DEFAULT_POOL_IDLE_MS = 6e4;
-var DEFAULT_AUTO_LIMIT = 100;
-var MAX_RESULT_STORE_BYTES = 256 * 1024 * 1024;
-function envName(suffix) {
-  return `${ENV_PREFIX}_${suffix}`;
-}
-function readEnv(name) {
-  const value = process.env[name];
-  if (value === void 0) {
-    return void 0;
-  }
-  const trimmed = value.trim();
-  return trimmed.length === 0 ? void 0 : trimmed;
-}
-function readSapCredentials(overrides) {
-  const email = overrides?.email ?? readEnv("SAP_EMAIL");
-  const password = overrides?.password ?? readEnv("SAP_PASSWORD");
-  if (email === void 0 || password === void 0) {
-    return void 0;
-  }
-  return { email, password };
-}
-
 // src/cf.ts
 import { execFile } from "child_process";
 import { mkdtemp, rm } from "fs/promises";
@@ -661,9 +1031,9 @@ import { join as join2 } from "path";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var MAX_BUFFER = 16 * 1024 * 1024;
-var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_TIMEOUT_MS = 6e4;
 var CF_RETRY_ATTEMPTS = 3;
-var CF_RETRY_BASE_DELAY_MS = 120;
+var CF_RETRY_BASE_DELAY_MS = 500;
 var REGION_API_MAP = {
   ae01: "https://api.cf.ae01.hana.ondemand.com",
   ap01: "https://api.cf.ap01.hana.ondemand.com",
@@ -785,29 +1155,45 @@ function buildEnv(ctx, overrides = {}) {
   env["CF_HOME"] = ctx.cfHome;
   return env;
 }
-async function runCf(args, ctx, overrides = {}) {
-  const { bin, argsPrefix } = resolveCfBin();
-  const env = buildEnv(ctx, overrides);
+async function execWithRetries(bin, args, env, timeoutMs = DEFAULT_TIMEOUT_MS) {
   let lastErr;
   for (let attempt = 0; attempt < CF_RETRY_ATTEMPTS; attempt++) {
     try {
-      const { stdout } = await execFileAsync(bin, [...argsPrefix, ...args], {
+      const { stdout } = await execFileAsync(bin, args, {
         env,
         maxBuffer: MAX_BUFFER,
-        timeout: DEFAULT_TIMEOUT_MS
+        timeout: timeoutMs,
+        killSignal: "SIGKILL"
       });
       return stdout;
     } catch (err) {
       lastErr = err;
+      const e = err;
+      const output = `${e.message ?? ""} ${e.stderr ? String(e.stderr) : ""}`.toLowerCase();
+      const isTimeout = e.killed === true;
+      const isNetworkFlake = output.includes("error performing request") || output.includes("timeout") || output.includes("connection reset") || output.includes("connection refused") || output.includes("eof") || output.includes("502 bad gateway") || output.includes("503 service unavailable") || output.includes("504 gateway timeout") || output.includes("dial tcp") || output.includes("no such host");
+      const isEnoent = e.code === "ENOENT";
+      if (isEnoent || !isTimeout && !isNetworkFlake) {
+        throw err;
+      }
       if (attempt < CF_RETRY_ATTEMPTS - 1) {
         await new Promise((r) => setTimeout(r, CF_RETRY_BASE_DELAY_MS * (attempt + 1)));
       }
     }
   }
-  const e = lastErr;
-  const detail = e?.stderr ? String(e.stderr) : e?.message ?? "";
-  const cmd = args[0] === "auth" ? "cf auth" : `cf ${args.join(" ")}`;
-  throw new Error(`${cmd} failed: ${detail}`.trim(), { cause: lastErr });
+  throw lastErr;
+}
+async function runCf(args, ctx, overrides = {}) {
+  const { bin, argsPrefix } = resolveCfBin();
+  const env = buildEnv(ctx, overrides);
+  try {
+    return await execWithRetries(bin, [...argsPrefix, ...args], env);
+  } catch (lastErr) {
+    const e = lastErr;
+    const detail = e?.stderr ? String(e.stderr) : e?.message ?? "";
+    const cmd = args[0] === "auth" ? "cf auth" : `cf ${args.join(" ")}`;
+    throw new Error(`${cmd} failed: ${detail}`.trim(), { cause: lastErr });
+  }
 }
 async function cfApi(apiEndpoint, ctx) {
   await runCf(["api", apiEndpoint], ctx);
@@ -829,12 +1215,7 @@ async function cfEnvDirect(appName) {
   const env = { ...process.env };
   delete env["SAP_EMAIL"];
   delete env["SAP_PASSWORD"];
-  const { stdout } = await execFileAsync(bin, [...argsPrefix, "env", appName], {
-    env,
-    maxBuffer: MAX_BUFFER,
-    timeout: DEFAULT_TIMEOUT_MS
-  });
-  return stdout;
+  return await execWithRetries(bin, [...argsPrefix, "env", appName], env);
 }
 async function readCurrentCfTarget() {
   const { bin, argsPrefix } = resolveCfBin();
@@ -842,11 +1223,7 @@ async function readCurrentCfTarget() {
   delete env["SAP_EMAIL"];
   delete env["SAP_PASSWORD"];
   try {
-    const { stdout } = await execFileAsync(bin, [...argsPrefix, "target"], {
-      env,
-      maxBuffer: MAX_BUFFER,
-      timeout: 1e4
-    });
+    const stdout = await execWithRetries(bin, [...argsPrefix, "target"], env);
     return parseCfTargetOutput(stdout);
   } catch {
     return void 0;
@@ -897,6 +1274,81 @@ function formatCurrentCfAppSelector(target, appName) {
   const region = target.regionKey ?? "current";
   return `${region}/${target.orgName}/${target.spaceName}/${name}`;
 }
+function findJsonObjectEnd(source, startIndex) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = startIndex; index < source.length; index++) {
+    const character = source[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (inString && character === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (character === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) {
+      continue;
+    }
+    if (character === "{") {
+      depth++;
+      continue;
+    }
+    if (character === "}" && --depth === 0) {
+      return index;
+    }
+  }
+  return -1;
+}
+function extractVcapApplicationJson(stdout) {
+  const marker = "VCAP_APPLICATION:";
+  const markerIndex = stdout.indexOf(marker);
+  if (markerIndex === -1) {
+    throw new Error("VCAP_APPLICATION section not found in cf env output");
+  }
+  const afterMarker = stdout.slice(markerIndex + marker.length);
+  const openIndex = afterMarker.indexOf("{");
+  if (openIndex === -1) {
+    throw new Error("VCAP_APPLICATION JSON payload not found in cf env output");
+  }
+  const closeIndex = findJsonObjectEnd(afterMarker, openIndex);
+  if (closeIndex === -1) {
+    throw new Error("Malformed VCAP_APPLICATION JSON in cf env output");
+  }
+  return afterMarker.slice(openIndex, closeIndex + 1);
+}
+function requireApplicationField(application, field) {
+  const value = application[field];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`VCAP_APPLICATION.${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+function extractCfEnvApplicationIdentity(stdout) {
+  let application;
+  try {
+    application = JSON.parse(extractVcapApplicationJson(stdout));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error("VCAP_APPLICATION is not valid JSON", { cause: error });
+    }
+    throw error;
+  }
+  if (!isRecord(application)) {
+    throw new Error("VCAP_APPLICATION must be an object");
+  }
+  return {
+    appName: requireApplicationField(application, "application_name"),
+    apiEndpoint: normalizeSapCfApiEndpoint(requireApplicationField(application, "cf_api")),
+    orgName: requireApplicationField(application, "organization_name"),
+    spaceName: requireApplicationField(application, "space_name")
+  };
+}
 function extractVcapSection(stdout) {
   const start = stdout.indexOf("VCAP_SERVICES:");
   if (start === -1) {
@@ -978,107 +1430,143 @@ function classifyCfError(stderr = "", stdout = "") {
 function errorMessageFromUnknown(error) {
   return error instanceof Error ? error.message : "Invalid or untrusted CF API endpoint.";
 }
-async function resolveAppBindings(rawSelector, options) {
-  const selector = rawSelector.trim();
-  if (!selector) {
-    throw new CfHanaError("CONFIG", "App selector is required");
+function parseExplicitTarget(selector) {
+  const [regionKey, orgName, spaceName, appName, extra] = selector.split("/").map((part) => part.trim());
+  if (extra !== void 0 || !regionKey || !orgName || !spaceName || !appName) {
+    throw new CfHanaError(
+      "CONFIG",
+      `Invalid selector "${selector}". Use region/org/space/app or a bare app name.`
+    );
   }
-  let target;
-  const isBare = !selector.includes("/");
-  if (isBare) {
-    const current = await readCurrentCfTarget();
-    if (!current) {
-      throw new CfHanaError(
-        "CONFIG",
-        "No current CF target found. Run `cf target -o <org> -s <space>` or pass a full region/org/space/app selector."
-      );
-    }
-    const displaySelector = current.regionKey ? formatCurrentCfAppSelector(current, selector) : `current/${current.orgName}/${current.spaceName}/${selector}`;
-    target = {
-      selector: displaySelector,
-      apiEndpoint: current.apiEndpoint,
-      orgName: current.orgName,
-      spaceName: current.spaceName,
-      appName: selector
+  const apiEndpoint = getApiEndpointForRegion(regionKey);
+  if (apiEndpoint === void 0) {
+    throw new CfHanaError(
+      "CONFIG",
+      `Unknown SAP CF region "${regionKey}". Verify the current SAP region list or use the current CF target.`
+    );
+  }
+  try {
+    return {
+      selector,
+      apiEndpoint: normalizeSapCfApiEndpoint(apiEndpoint),
+      orgName,
+      spaceName,
+      appName,
+      selectorSource: "explicit",
+      regionConfirmed: true,
+      selectorCanBePinned: true
     };
-  } else {
-    const parts = selector.split("/").map((p) => p.trim());
-    if (parts.length !== 4 || !parts[0] || !parts[1] || !parts[2] || !parts[3]) {
-      throw new CfHanaError(
-        "CONFIG",
-        `Invalid selector "${selector}". Use region/org/space/app or a bare app name.`
-      );
-    }
-    const [regionKey, orgName, spaceName, appName] = parts;
-    const apiEndpoint = getApiEndpointForRegion(regionKey);
-    if (!apiEndpoint) {
+  } catch (error) {
+    throw new CfHanaError("CONFIG", errorMessageFromUnknown(error), { cause: error });
+  }
+}
+async function resolveTarget(selector) {
+  if (selector.includes("/")) {
+    return parseExplicitTarget(selector);
+  }
+  const current = await readCurrentCfTarget();
+  if (current === void 0) {
+    throw new CfHanaError(
+      "CONFIG",
+      "No current CF target found. Run `cf target -o <org> -s <space>` or pass a full region/org/space/app selector."
+    );
+  }
+  return {
+    selector: formatCurrentCfAppSelector(current, selector),
+    apiEndpoint: current.apiEndpoint,
+    orgName: current.orgName,
+    spaceName: current.spaceName,
+    appName: selector,
+    selectorSource: "ambient",
+    regionConfirmed: current.regionKey !== void 0,
+    selectorCanBePinned: current.regionKey !== void 0 && getApiEndpointForRegion(current.regionKey) !== void 0
+  };
+}
+function commandErrorText(error) {
+  if (typeof error !== "object" || error === null) {
+    return "";
+  }
+  if ("stderr" in error && typeof error.stderr === "string" && error.stderr.length > 0) {
+    return error.stderr;
+  }
+  return "message" in error && typeof error.message === "string" ? error.message : "";
+}
+function isSameTarget(target, current) {
+  return current?.apiEndpoint === target.apiEndpoint && current.orgName === target.orgName && current.spaceName === target.spaceName;
+}
+async function assertAmbientTargetUnchanged(target) {
+  const current = await readCurrentCfTarget();
+  if (!isSameTarget(target, current)) {
+    throw new CfHanaError(
+      "CONFIG",
+      "CF target changed during binding discovery; no database connection was opened. Retry or use an explicit region/org/space/app selector."
+    );
+  }
+}
+function readCfEnvApplicationIdentity(stdout) {
+  try {
+    return extractCfEnvApplicationIdentity(stdout);
+  } catch (error) {
+    throw new CfHanaError(
+      "CONFIG",
+      "Could not verify cf env application identity for the ambient target; no database connection was opened. Retry or use an explicit region/org/space/app selector.",
+      { cause: error }
+    );
+  }
+}
+function assertCfEnvApplicationMatchesTarget(target, application) {
+  const matches = application.apiEndpoint === target.apiEndpoint && application.orgName === target.orgName && application.spaceName === target.spaceName && application.appName === target.appName;
+  if (matches) {
+    return;
+  }
+  throw new CfHanaError(
+    "CONFIG",
+    "CF env application identity did not match the resolved ambient target; no database connection was opened. Retry or use an explicit region/org/space/app selector."
+  );
+}
+async function readIsolatedBindings(target, sap) {
+  return await withCfSession(async (ctx) => {
+    await cfApi(target.apiEndpoint, ctx);
+    await cfAuth(sap.email, sap.password, ctx);
+    await cfTargetSpace(target.orgName, target.spaceName, ctx);
+    return extractHanaBindingsFromCfEnv(await cfEnv(target.appName, ctx));
+  });
+}
+async function readBareBindings(target, options) {
+  let stdout;
+  try {
+    stdout = await cfEnvDirect(target.appName);
+  } catch (directError) {
+    const classified = classifyCfError(commandErrorText(directError));
+    if (!classified.isAuthError) {
       throw new CfHanaError(
         "CONFIG",
-        `Unknown SAP CF region "${regionKey}". Verify the current SAP region list or use the current CF target.`
+        `Failed to get HANA bindings for bare app "${target.appName}" using current target (org=${target.orgName}, space=${target.spaceName}). Verify with "cf target" and "cf env ${target.appName}".`,
+        { cause: directError }
       );
     }
-    let normalizedApiEndpoint;
-    try {
-      normalizedApiEndpoint = normalizeSapCfApiEndpoint(apiEndpoint);
-    } catch (error) {
-      throw new CfHanaError("CONFIG", errorMessageFromUnknown(error), { cause: error });
-    }
-    target = { selector, apiEndpoint: normalizedApiEndpoint, orgName, spaceName, appName };
-  }
-  let bindings;
-  const source = "live";
-  if (isBare) {
-    try {
-      const stdout = await cfEnvDirect(target.appName);
-      bindings = extractHanaBindingsFromCfEnv(stdout);
-    } catch (directError) {
-      let stderr = "";
-      if (directError && typeof directError === "object") {
-        const e = directError;
-        stderr = (typeof e.stderr === "string" ? e.stderr : "") || (typeof e.message === "string" ? e.message : "");
-      }
-      const classified = classifyCfError(stderr);
-      if (classified.isAuthError) {
-        const sap = readSapCredentials({ email: options.email, password: options.password });
-        if (!sap) {
-          throw new CredentialsNotFoundError(
-            `Current CF session problem for bare app "${target.appName}" (${classified.reason}).
-Run "cf login" + "cf target", or provide SAP_EMAIL + SAP_PASSWORD.`,
-            { cause: directError }
-          );
-        }
-        const api = target.apiEndpoint;
-        bindings = await withCfSession(async (ctx) => {
-          await cfApi(api, ctx);
-          await cfAuth(sap.email, sap.password, ctx);
-          await cfTargetSpace(target.orgName, target.spaceName, ctx);
-          const stdout = await cfEnv(target.appName, ctx);
-          return extractHanaBindingsFromCfEnv(stdout);
-        });
-      } else {
-        throw new CfHanaError(
-          "CONFIG",
-          `Failed to get HANA bindings for bare app "${target.appName}" using current target (org=${target.orgName}, space=${target.spaceName}). Verify with "cf target" and "cf env ${target.appName}". ${stderr ? `Details: ${stderr}` : ""}`,
-          { cause: directError }
-        );
-      }
-    }
-  } else {
     const sap = readSapCredentials({ email: options.email, password: options.password });
-    if (!sap) {
+    if (sap === void 0) {
       throw new CredentialsNotFoundError(
-        `SAP_EMAIL and SAP_PASSWORD are required to fetch HANA bindings for explicit selector "${selector}".`
+        `Current CF session problem for bare app "${target.appName}" (${classified.reason}).
+Run "cf login" + "cf target", or provide SAP_EMAIL + SAP_PASSWORD.`,
+        { cause: directError }
       );
     }
-    const api = target.apiEndpoint;
-    bindings = await withCfSession(async (ctx) => {
-      await cfApi(api, ctx);
-      await cfAuth(sap.email, sap.password, ctx);
-      await cfTargetSpace(target.orgName, target.spaceName, ctx);
-      const stdout = await cfEnv(target.appName, ctx);
-      return extractHanaBindingsFromCfEnv(stdout);
-    });
+    return await readIsolatedBindings(target, sap);
+  }
+  const application = readCfEnvApplicationIdentity(stdout);
+  await assertAmbientTargetUnchanged(target);
+  assertCfEnvApplicationMatchesTarget(target, application);
+  return extractHanaBindingsFromCfEnv(stdout);
+}
+async function resolveAppBindings(rawSelector, options) {
+  const selector = rawSelector.trim();
+  if (selector.length === 0) {
+    throw new CfHanaError("CONFIG", "App selector is required");
   }
+  const target = await resolveTarget(selector);
+  const bindings = target.selectorSource === "ambient" ? await readBareBindings(target, options) : await readExplicitBindings(target, options);
   if (bindings.length === 0) {
     throw new CredentialsNotFoundError(`App "${target.selector}" has no HANA service binding.`);
   }
@@ -1086,9 +1574,21 @@ Run "cf login" + "cf target", or provide SAP_EMAIL + SAP_PASSWORD.`,
     selector: target.selector,
     appName: target.appName,
     bindings,
-    source
+    source: "live",
+    selectorSource: target.selectorSource,
+    regionConfirmed: target.regionConfirmed,
+    selectorCanBePinned: target.selectorCanBePinned
   };
 }
+async function readExplicitBindings(target, options) {
+  const sap = readSapCredentials({ email: options.email, password: options.password });
+  if (sap === void 0) {
+    throw new CredentialsNotFoundError(
+      `SAP_EMAIL and SAP_PASSWORD are required to fetch HANA bindings for explicit selector "${target.selector}".`
+    );
+  }
+  return await readIsolatedBindings(target, sap);
+}
 function selectBinding(bindings, selector) {
   if (selector.bindingName !== void 0) {
     const match = bindings.find((binding) => binding.name === selector.bindingName);
@@ -1159,42 +1659,82 @@ function tableColumns() {
     { COLUMN_NAME: "SCOPE_NAME", DATA_TYPE_NAME: "NVARCHAR", LENGTH: 255, SCALE: null, IS_NULLABLE: "TRUE", POSITION: 3 }
   ];
 }
-function fakeExec(sql) {
-  const kind = classifyStatement(sql);
+function throwForcedFailure(kind) {
   const forcedFailure = readEnv(envName("FAKE_FAIL_STATEMENT"))?.toLowerCase();
   if (forcedFailure === kind) {
     throw new Error(`fake driver forced ${kind.toUpperCase()} failure`);
   }
-  const upperSql = sql.toUpperCase();
+}
+function throwEarlyFixtureError(upperSql) {
+  if (upperSql.includes("PRIVILEGE_ERROR_CODE")) {
+    throw new QueryError("insufficient privilege: not authorized", { databaseCode: 258 });
+  }
+  if (upperSql.includes("PRIVILEGE_ERROR_MESSAGE")) {
+    throw new QueryError("insufficient privilege: grant is missing");
+  }
+  if (upperSql.includes("NON_PRIVILEGE_ERROR")) {
+    throw new QueryError("fake unrelated query failure", { databaseCode: 999 });
+  }
+  if (readEnv(envName("FAKE_PRIVILEGE_CATALOG")) === "1" && (upperSql.includes("SYS.TABLES") || upperSql.includes("SYS.TABLE_COLUMNS"))) {
+    throw new QueryError("insufficient privilege: catalog access denied", { databaseCode: 258 });
+  }
+}
+function catalogObjectsResult() {
+  return {
+    rows: catalogObjects(),
+    columns: [
+      { name: "SCHEMA_NAME", typeName: "NVARCHAR" },
+      { name: "OBJECT_NAME", typeName: "NVARCHAR" },
+      { name: "OBJECT_TYPE", typeName: "NVARCHAR" }
+    ],
+    affectedRows: 0
+  };
+}
+function tablesResult() {
+  return {
+    rows: [
+      { SCHEMA_NAME: "APP_SCHEMA", TABLE_NAME: "EXISTING_TABLE", TABLE_TYPE: "COLUMN TABLE" },
+      { SCHEMA_NAME: "APP_SCHEMA", TABLE_NAME: "STATUS_ITEMS", TABLE_TYPE: "ROW TABLE" }
+    ],
+    columns: [
+      { name: "SCHEMA_NAME", typeName: "NVARCHAR" },
+      { name: "TABLE_NAME", typeName: "NVARCHAR" },
+      { name: "TABLE_TYPE", typeName: "NVARCHAR" }
+    ],
+    affectedRows: 0
+  };
+}
+function tableColumnsResult() {
+  return {
+    rows: tableColumns(),
+    columns: [
+      { name: "COLUMN_NAME", typeName: "NVARCHAR" },
+      { name: "DATA_TYPE_NAME", typeName: "NVARCHAR" },
+      { name: "LENGTH", typeName: "INTEGER" },
+      { name: "SCALE", typeName: "INTEGER" },
+      { name: "IS_NULLABLE", typeName: "NVARCHAR" },
+      { name: "POSITION", typeName: "INTEGER" }
+    ],
+    affectedRows: 0
+  };
+}
+function matchCatalogFixture(upperSql) {
   if (upperSql.includes("SYS.TABLES") && upperSql.includes("SYS.VIEWS")) {
     if (readEnv(envName("FAKE_FAIL_CATALOG_ONCE")) === "1" && !catalogFailureInjected) {
       catalogFailureInjected = true;
       throw new QueryError("fake transient catalog metadata failure");
     }
-    return {
-      rows: catalogObjects(),
-      columns: [
-        { name: "SCHEMA_NAME", typeName: "NVARCHAR" },
-        { name: "OBJECT_NAME", typeName: "NVARCHAR" },
-        { name: "OBJECT_TYPE", typeName: "NVARCHAR" }
-      ],
-      affectedRows: 0
-    };
+    return catalogObjectsResult();
+  }
+  if (upperSql.includes("SYS.TABLES")) {
+    return tablesResult();
   }
   if (upperSql.includes("SYS.TABLE_COLUMNS")) {
-    return {
-      rows: tableColumns(),
-      columns: [
-        { name: "COLUMN_NAME", typeName: "NVARCHAR" },
-        { name: "DATA_TYPE_NAME", typeName: "NVARCHAR" },
-        { name: "LENGTH", typeName: "INTEGER" },
-        { name: "SCALE", typeName: "INTEGER" },
-        { name: "IS_NULLABLE", typeName: "NVARCHAR" },
-        { name: "POSITION", typeName: "INTEGER" }
-      ],
-      affectedRows: 0
-    };
+    return tableColumnsResult();
   }
+  return void 0;
+}
+function throwLateFixtureError(upperSql) {
   if (upperSql.includes("MISSING_TABLE") || upperSql.includes("MISSING_TABLES")) {
     throw new QueryError("invalid table name: MISSING_TABLE", { sqlState: "42S02" });
   }
@@ -1207,30 +1747,45 @@ function fakeExec(sql) {
   if (upperSql.includes("LOB_GROUP_ERROR")) {
     throw new QueryError("inconsistent datatype: LOB type is not allowed in GROUP BY clause", { databaseCode: 274 });
   }
-  if (sql.toUpperCase().includes("LOB_FIXTURE")) {
+}
+function lobFixtureResult() {
+  return {
+    rows: [
+      {
+        LOG_CONTENT: Buffer.from("Example log entry", "utf8"),
+        CLOB_CONTENT: Buffer.from("Clob log entry", "utf8"),
+        PAYLOAD: Buffer.from([0, 1, 2, 255])
+      }
+    ],
+    columns: [
+      { name: "LOG_CONTENT", typeName: "NCLOB" },
+      { name: "CLOB_CONTENT", typeName: "CLOB" },
+      { name: "PAYLOAD", typeName: "BLOB" }
+    ],
+    affectedRows: 0
+  };
+}
+function matchDataFixture(upperSql) {
+  if (upperSql.includes("LOB_FIXTURE")) {
+    return lobFixtureResult();
+  }
+  if (upperSql.includes("SINGLE_COLUMN_FIXTURE")) {
     return {
-      rows: [
-        {
-          LOG_CONTENT: Buffer.from("Example log entry", "utf8"),
-          CLOB_CONTENT: Buffer.from("Clob log entry", "utf8"),
-          PAYLOAD: Buffer.from([0, 1, 2, 255])
-        }
-      ],
-      columns: [
-        { name: "LOG_CONTENT", typeName: "NCLOB" },
-        { name: "CLOB_CONTENT", typeName: "CLOB" },
-        { name: "PAYLOAD", typeName: "BLOB" }
-      ],
+      rows: [{ VALUE: "alpha" }, { VALUE: "beta" }],
+      columns: [{ name: "VALUE", typeName: "NVARCHAR" }],
       affectedRows: 0
     };
   }
-  if (sql.toUpperCase().includes("DUMMY")) {
+  if (upperSql.includes("DUMMY")) {
     return {
       rows: [{ "1": 1 }],
       columns: [{ name: "1", typeName: "INTEGER" }],
       affectedRows: 0
     };
   }
+  return void 0;
+}
+function defaultResult(kind) {
   if (kind === "select") {
     return {
       rows: [
@@ -1249,6 +1804,18 @@ function fakeExec(sql) {
   }
   return { rows: [], columns: [], affectedRows: 0 };
 }
+function fakeExec(sql) {
+  const kind = classifyStatement(sql);
+  throwForcedFailure(kind);
+  const upperSql = sql.toUpperCase();
+  throwEarlyFixtureError(upperSql);
+  const catalogFixture = matchCatalogFixture(upperSql);
+  if (catalogFixture !== void 0) {
+    return catalogFixture;
+  }
+  throwLateFixtureError(upperSql);
+  return matchDataFixture(upperSql) ?? defaultResult(kind);
+}
 async function traceFakeExec(sql, params) {
   const tracePath = readEnv(envName("FAKE_TRACE_FILE"));
   if (tracePath === void 0) {
@@ -1679,8 +2246,30 @@ function maskIgnoredSqlText(sql) {
   }
   return masked;
 }
-function hasWhereClause(sql) {
-  return /\bwhere\b/i.test(maskIgnoredSqlText(sql));
+function hasTopLevelKeyword(sql, keyword) {
+  const masked = maskIgnoredSqlText(sql);
+  let depth = 0;
+  for (let index = 0; index < masked.length; index += 1) {
+    const char = masked[index];
+    if (char === "(") {
+      depth += 1;
+      continue;
+    }
+    if (char === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (depth === 0 && masked.slice(index, index + keyword.length).toUpperCase() === keyword && !/[A-Za-z0-9_$#]/.test(masked.charAt(index - 1)) && !/[A-Za-z0-9_$#]/.test(masked.charAt(index + keyword.length))) {
+      return true;
+    }
+  }
+  return false;
+}
+function isUnconditionalMergeDelete(sql) {
+  return /\bWHEN\s+MATCHED\s+THEN\s+DELETE\b/i.test(maskIgnoredSqlText(sql));
+}
+function isMalformedReplace(sql) {
+  return !hasTopLevelKeyword(sql, "VALUES") && !hasTopLevelKeyword(sql, "SELECT") && !hasTopLevelKeyword(sql, "WITH");
 }
 function trailingLineCommentIndex(sql) {
   let index = 0;
@@ -1723,9 +2312,10 @@ function inspectStatement(sql) {
     return { kind, destructive: DESTRUCTIVE_DDL_KEYWORDS.has(keyword) };
   }
   if (kind === "dml") {
+    const destructive = UNSCOPED_WRITE_KEYWORDS.has(keyword) && !hasTopLevelKeyword(sql, "WHERE") || keyword === "MERGE" && isUnconditionalMergeDelete(sql) || keyword === "REPLACE" && isMalformedReplace(sql);
     return {
       kind,
-      destructive: UNSCOPED_WRITE_KEYWORDS.has(keyword) && !hasWhereClause(sql)
+      destructive
     };
   }
   return { kind, destructive: false };
@@ -1745,7 +2335,7 @@ function evaluateGuard(sql, config) {
       allowed: false,
       destructive: true,
       violation: "destructive",
-      reason: "destructive statement blocked (DROP/TRUNCATE/ALTER or unscoped UPDATE/DELETE); allow it explicitly to proceed"
+      reason: "destructive statement blocked (DROP/TRUNCATE/ALTER, unscoped UPDATE/DELETE, or unconditional matched MERGE DELETE); allow it explicitly to proceed"
     };
   }
   return {
@@ -1785,6 +2375,57 @@ function boundedRows(rows, requestedLimit) {
     truncated: rows.length > requestedLimit
   };
 }
+function isBooleanColumn(column) {
+  return column.typeName.trim().toUpperCase() === "BOOLEAN";
+}
+function normalizeBooleanCell(value) {
+  if (value === 0) {
+    return false;
+  }
+  if (value === 1) {
+    return true;
+  }
+  if (typeof value !== "string") {
+    return value;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "0") {
+    return false;
+  }
+  if (normalized === "1") {
+    return true;
+  }
+  if (normalized === "false") {
+    return false;
+  }
+  if (normalized === "true") {
+    return true;
+  }
+  return value;
+}
+function normalizeBooleanRow(row, columns) {
+  let normalizedRow;
+  for (const column of columns) {
+    const value = row[column.name];
+    if (value === void 0) {
+      continue;
+    }
+    const normalizedValue = normalizeBooleanCell(value);
+    if (normalizedValue === value) {
+      continue;
+    }
+    normalizedRow ??= { ...row };
+    normalizedRow[column.name] = normalizedValue;
+  }
+  return normalizedRow ?? row;
+}
+function normalizeBooleanRows(rows, columns) {
+  const booleanColumns = columns.filter(isBooleanColumn);
+  if (booleanColumns.length === 0 || rows.length === 0) {
+    return rows;
+  }
+  return rows.map((row) => normalizeBooleanRow(row, booleanColumns));
+}
 async function withTimeout(work, timeoutMs, onTimeout) {
   let timer;
   const timeout = new Promise((_resolve, reject) => {
@@ -1870,7 +2511,8 @@ var Connection = class _Connection {
       }
     );
     const elapsedMs = Date.now() - started;
-    const selected = boundedRows(execResult.rows, limited.requestedLimit);
+    const normalizedRows = normalizeBooleanRows(execResult.rows, execResult.columns);
+    const selected = boundedRows(normalizedRows, limited.requestedLimit);
     return {
       rows: selected.rows,
       columns: execResult.columns,
@@ -2095,18 +2737,37 @@ function nextExplainStatementName() {
   explainStatementCounter = (explainStatementCounter + 1) % Number.MAX_SAFE_INTEGER;
   return `cf_hana_${String(process.pid)}_${String(Date.now())}_${String(explainStatementCounter)}`;
 }
+function toPoolOptions(options) {
+  if (options.pool === false) {
+    return { max: 1 };
+  }
+  return options.pool ?? {};
+}
+function toSelectedBindingInfo(bindings, selected) {
+  const availableBindingNames = bindings.flatMap(
+    (binding) => binding.name === void 0 ? [] : [binding.name]
+  );
+  return {
+    ...selected.name === void 0 ? {} : { bindingName: selected.name },
+    bindingIndex: bindings.indexOf(selected),
+    availableBindingNames
+  };
+}
 var HanaClient = class _HanaClient {
-  constructor(pool, info) {
+  constructor(pool, info, databaseUser = "") {
     this.pool = pool;
     this.info = info;
+    this.databaseUser = databaseUser;
   }
   pool;
   info;
+  databaseUser;
   /** Open a client for a `region/org/space/app` selector (or a bare app name). */
   static async connect(selector, options = {}) {
     const resolved = await resolveAppBindings(selector, options);
     const role = options.role ?? "runtime";
     const binding = selectBinding(resolved.bindings, options);
+    const bindingInfo = toSelectedBindingInfo(resolved.bindings, binding);
     const target = toConnectionTarget(binding, role);
     const driver = createDriver();
     const config = {
@@ -2122,7 +2783,7 @@ var HanaClient = class _HanaClient {
       allowDestructive: options.allowDestructive ?? false,
       autoLimit: options.autoLimit ?? DEFAULT_AUTO_LIMIT
     };
-    const poolOptions = options.pool === false ? { max: 1 } : options.pool ?? {};
+    const poolOptions = toPoolOptions(options);
     const info = {
       selector: resolved.selector,
       appName: resolved.appName,
@@ -2130,9 +2791,13 @@ var HanaClient = class _HanaClient {
       schema: target.schema,
       role,
       driver: driver.name,
-      credentialSource: resolved.source
+      credentialSource: resolved.source,
+      selectorSource: resolved.selectorSource,
+      regionConfirmed: resolved.regionConfirmed,
+      selectorCanBePinned: resolved.selectorCanBePinned,
+      ...bindingInfo
     };
-    return new _HanaClient(new ConnectionPool(driver, config, poolOptions), info);
+    return new _HanaClient(new ConnectionPool(driver, config, poolOptions), info, target.user);
   }
   /** Run a SELECT (or any read) statement and return typed rows. */
   async query(sql, params, options) {
@@ -2148,7 +2813,7 @@ var HanaClient = class _HanaClient {
     await this.recordSqlHistory("execute", sql, resolvedParams, result);
     return result;
   }
-  /** Back up rows matched by an UPDATE or DELETE before the caller runs it. */
+  /** Back up pre-image rows required by a supported write before the caller runs it. */
   async backupWriteStatement(sql, params, options) {
     const resolvedParams = params ?? [];
     const plan = buildWriteBackupPlan(sql, resolvedParams);
@@ -2329,6 +2994,7 @@ async function withConnection(selector, work, options) {
   }
 }
 export {
+  BackupRequiredError,
   CfHanaError,
   CredentialsNotFoundError,
   DestructiveStatementError,