@saptools/cf-hana 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.4 - 2026-06-23
+
+- Add automatic local CSV backups before CLI `query` runs an `UPDATE` or
+  `DELETE`.
+- Derive the backup `SELECT` from the write target and top-level `WHERE`
+  clause, preserving only the WHERE parameters for `UPDATE` statements.
+- Save each backup in its own non-expiring folder with `statement.sql` and
+  `backup.csv`, and add `--no-backup` for explicit CLI opt-out.
+
+## 0.1.3 - 2026-06-23
+
+- Add local SQL history for successful direct `query` and `execute` calls under
+  `~/.saptools/cf-hana/histories/YYYY-MM-DD.jsonl`.
+- Rotate SQL history with five-day retention and keep parameter values,
+  credentials, certificates, and result rows out of the history file.
+- Keep helper-driven catalog SQL out of user SQL history and document the new
+  local state behavior.
+
 ## 0.1.2 - 2026-06-23
 
 - Harden connection pooling so queued callers continue after transient reconnect failures.

package/README.md

@@ -22,6 +22,10 @@ login on the hot path) and connections are pooled and reused within a process.
 - **Query-builder shorthands** — `selectFrom`, `count`, `insertInto`, `update`,
   `deleteFrom` — query a table by name without writing SQL.
 - **Schema introspection** — list schemas, tables, and columns.
+- **Local SQL history** — direct SQL calls are appended to dated JSONL files
+  under `~/.saptools/cf-hana/histories/` with five-day retention.
+- **Write backups** — CLI `UPDATE` and `DELETE` statements create a local CSV
+  backup of matching rows before the write runs.
 - **Safety guard** — opt-in read-only mode and a destructive-statement guard
   (blocks `DROP`/`TRUNCATE`/`ALTER` and unscoped `UPDATE`/`DELETE`).
 - **Typed results** — `query<TRow>()` returns typed rows.
@@ -44,7 +48,7 @@ driver is bundled as a dependency — there is no native build step.
 import { connect, query } from "@saptools/cf-hana";
 
 // Open a reusable, pooled client for one CF app's HANA database.
-const db = await connect("eu10/acme/dev/orders-api");
+const db = await connect("eu10/example-org/space-demo/app-demo");
 
 const open = await db.query("SELECT ID, STATUS FROM ORDERS WHERE STATUS = ?", ["OPEN"]);
 console.log(open.rows);
@@ -58,16 +62,16 @@ await db.transaction(async (tx) => {
 await db.close();
 
 // One-shot: connect, run one query, close.
-const rows = await query("orders-api", "SELECT COUNT(*) AS N FROM ORDERS");
+const rows = await query("app-demo", "SELECT COUNT(*) AS N FROM ORDERS");
 ```
 
 ## The selector
 
 Every entry point takes a selector as its first argument:
 
-- **Explicit** — `region/org/space/app` (e.g. `eu10/acme/dev/orders-api`). Works
-  without any cached topology.
-- **Bare app name** — `orders-api`. Resolved against the topology cached by
+- **Explicit** — `region/org/space/app` (e.g.
+  `eu10/example-org/space-demo/app-demo`). Works without any cached topology.
+- **Bare app name** — `app-demo`. Resolved against the topology cached by
   `cf-sync sync`; throws if the name is ambiguous across spaces.
 
 ## CLI
@@ -84,14 +88,17 @@ cf-hana info    <selector>                  Print the resolved connection metada
 Common options: `--format <table|json|csv>`, `--refresh`, `--role <runtime|hdi>`,
 `--binding <name>` / `--binding-index <n>`, `--timeout <ms>`, `--read-only`,
 `--allow-destructive`, `--limit <n>`, `--no-auto-limit`. The `query` command also
-accepts `--param <value>` (repeatable) to bind `?` placeholders.
+accepts `--param <value>` (repeatable) to bind `?` placeholders and
+`--no-backup` to skip the default write backup.
 
 ```bash
-cf-hana query eu10/acme/dev/orders-api "SELECT ID, STATUS FROM ORDERS WHERE STATUS = ?" \
+cf-hana query eu10/example-org/space-demo/app-demo "SELECT ID, STATUS FROM ORDERS WHERE STATUS = ?" \
   --param OPEN --format json
-cf-hana tables orders-api
-cf-hana columns orders-api ORDERS_APP.ORDERS
-cf-hana ping eu10/acme/dev/orders-api
+cf-hana query app-demo "UPDATE ORDERS SET STATUS = ? WHERE ID = ?" \
+  --param DONE --param 42 --format json
+cf-hana tables app-demo
+cf-hana columns app-demo ORDERS_APP.ORDERS
+cf-hana ping eu10/example-org/space-demo/app-demo
 ```
 
 ## Programmatic API
@@ -101,7 +108,7 @@ cf-hana ping eu10/acme/dev/orders-api
 | `connect(selector, options?)` | Open a reusable, pooled `HanaClient`. |
 | `query(selector, sql, params?, options?)` | One-shot: connect, query, close. |
 | `withConnection(selector, work, options?)` | Run `work` with a client that auto-closes. |
-| `HanaClient` | `query`, `execute`, `selectFrom`, `count`, `insertInto`, `update`, `deleteFrom`, `transaction`, `listSchemas`, `listTables`, `listColumns`, `explain`, `close`. |
+| `HanaClient` | `query`, `execute`, `backupWriteStatement`, `selectFrom`, `count`, `insertInto`, `update`, `deleteFrom`, `transaction`, `listSchemas`, `listTables`, `listColumns`, `explain`, `close`. |
 | `createDriver`, `formatResult`, `build*` | Lower-level building blocks. |
 
 `ConnectOptions` highlights: `role` (`runtime` | `hdi`), `bindingName` /
@@ -117,11 +124,58 @@ Credentials are resolved **cache-first**:
    live from Cloud Foundry. The live fetch needs `SAP_EMAIL` and `SAP_PASSWORD`
    (or the `email` / `password` options) and never persists anything to disk.
 
-`cf-hana` itself writes nothing under `~/.saptools/` — it only reads what
+Credential resolution writes nothing under `~/.saptools/` — it only reads what
 `cf-sync` cached. The connection pool is in-process and in-memory only, so it is
 safe to run many `cf-hana` processes in parallel and alongside any `cf-sync`
 command.
 
+## SQL history
+
+Successful direct SQL calls are appended to daily JSONL files:
+
+```text
+~/.saptools/cf-hana/histories/YYYY-MM-DD.jsonl
+```
+
+Each entry includes the timestamp, package version, selector, app name, schema,
+role, operation (`query` or `execute`), statement kind, SQL text, parameter
+count, row count, truncation flag, and elapsed time. Parameter values,
+credentials, certificates, and result rows are not stored.
+
+History retention runs opportunistically after each append and deletes dated
+history files older than five days. Helper-driven catalog SQL such as `tables`
+and `columns` is not recorded as user SQL history.
+
+## Write backups
+
+When `cf-hana query` receives an `UPDATE` or `DELETE`, it first builds and runs a
+matching `SELECT`:
+
+- `UPDATE <target> SET ... WHERE ...` becomes
+  `SELECT * FROM <target> WHERE ...`.
+- `DELETE FROM <target> WHERE ...` becomes
+  `SELECT * FROM <target> WHERE ...`.
+
+The backup is saved before the write runs:
+
+```text
+~/.saptools/cf-hana/backups/<timestamp>-<operation>-<hash>/
+  statement.sql
+  backup.csv
+```
+
+`statement.sql` contains the original write statement. `backup.csv` contains the
+rows returned by the derived `SELECT`. Backup folders are not deleted by
+`cf-hana`; clean them up manually when they are no longer needed. The backup path
+is printed to stderr so JSON and CSV stdout remain parseable.
+
+Use `--no-backup` when an external backup or transaction workflow already covers
+the write:
+
+```bash
+cf-hana query app-demo "DELETE FROM ORDERS WHERE ID = ?" --param 42 --no-backup
+```
+
 ## Safety
 
 - **Read-only mode** (`readOnly` / `--read-only`) rejects every DML and DDL statement.