🗄️ @saptools/sqltools

Stop copy-pasting HANA credentials out of VCAP_SERVICES.

One command turns a SAP BTP Cloud Foundry HANA service binding into a ready-to-use VS Code SQLTools connection — no cockpit clicking, no JSON surgery.

Install • Quick Start • CLI • API • FAQ

✨ Features

• 🔌 One-shot export — pulls VCAP_SERVICES from any CF app and writes .vscode/settings.json with a valid SAPHana connection
• 🪄 Four input paths — read from a real CF app, a saved JSON file, stdin, or an already-targeted CF session
• 🧷 Non-destructive — preserves unrelated VS Code settings and, with --merge, unrelated SQLTools connections too
• 💾 Backup JSON — drops a hana-credentials.json beside the settings so HDI users / URLs / certificates stay within reach
• 🔒 Type-safe — shipped with full TypeScript definitions for every input and output shape
• 🪶 Tiny — two runtime deps (@saptools/cf-sync, commander) and zero runtime magic

📦 Install

# Global CLI
npm install -g @saptools/sqltools

# Or as a dependency
npm install @saptools/sqltools
# pnpm add @saptools/sqltools
# yarn add @saptools/sqltools

[!NOTE] Requires Node.js ≥ 20. The from-cf / from-app commands also need the cf CLI on PATH. For from-app, set SAP_EMAIL and SAP_PASSWORD so the tool can authenticate and target the org/space for you.

🚀 Quick Start

# Already logged in and targeted with `cf login`? One command is enough.
sqltools-export from-cf \
  --app my-srv --region eu10 --org my-org --space dev

Result:

✔ Updated SQLTools connections (1) → /workspace/.vscode/settings.json
  Credentials JSON saved → /workspace/hana-credentials.json
  • my-srv (eu10) host.hana.ondemand.com:443 schema=SCHEMA_MY_SRV

Open the workspace in VS Code, install the SQLTools + SQLTools SAP HANA driver extensions, and the new connection is already wired up.

🧰 CLI

Every command identifies an app with the same four labels — they are written into the SQLTools connection name as "<app> (<region>)".

| Flag | Description | Example | | --- | --- | --- | | --app <name> | CF app name (also the label) | my-srv | | --region <key> | CF region key | ap10, eu10, us10 | | --org <name> | CF org name | my-org | | --space <name> | CF space name | dev |

Common output options:

| Flag | Description | | --- | --- | | --cwd <dir> | Workspace root that owns .vscode/settings.json (default: cwd) | | --merge | Merge with existing connections by name (default: overwrite) | | --credentials-out <path> | Custom path for the backup JSON | | --no-credentials-file | Skip writing hana-credentials.json |

🌐 sqltools-export from-app

Full end-to-end: cf api → cf auth → cf target → cf env → write settings. Great for CI and fresh machines.

export SAP_EMAIL="[email protected]"
export SAP_PASSWORD="your-sap-password"

sqltools-export from-app \
  --app my-srv --region eu10 --org my-org --space dev

📡 sqltools-export from-cf

Assumes you are already targeted (cf login && cf target -o ... -s ...). Shells out to cf env <app> and writes the settings.

sqltools-export from-cf --app my-srv --region eu10 --org my-org --space dev

📄 sqltools-export from-file

Already have a VCAP_SERVICES JSON saved somewhere? Point to it.

sqltools-export from-file --input ./vcap.json \
  --app my-srv --region eu10 --org my-org --space dev

📥 sqltools-export from-stdin

Classic pipe:

cf env my-srv | jq '."VCAP_SERVICES"' | sqltools-export from-stdin \
  --app my-srv --region eu10 --org my-org --space dev

🔁 sqltools-export convert

Print a single SQLTools connection JSON to stdout — no files written. Perfect for scripting.

sqltools-export convert --input ./vcap.json \
  --app my-srv --region eu10 --org my-org --space dev

[!TIP] Use --merge to keep hand-crafted connections in .vscode/settings.json untouched while only overwriting the one matching <app> (<region>).

🧑‍💻 Programmatic Usage

import {
  exportFromApp,
  exportFromCf,
  exportFromFile,
  exportFromVcap,
  toSqlToolsConnection,
  buildEntryFromVcap,
} from "@saptools/sqltools";

const context = {
  app: "my-srv",
  region: "eu10",
  org: "my-org",
  space: "dev",
} as const;

// Full login → target → env → write flow
await exportFromApp(
  { context, email: process.env["SAP_EMAIL"]!, password: process.env["SAP_PASSWORD"]! },
  { merge: true },
);

// Or: already targeted, just run `cf env`
await exportFromCf({ context });

// Or: in-memory VCAP from your own source
const vcapServices = JSON.stringify({ hana: [/* … */] });
const result = await exportFromVcap({ vcapServices, context });
console.log(result.settingsPath, result.connectionCount);

// Or: one-off convert without touching the workspace
const entry = buildEntryFromVcap({ vcapServices, context });
if (entry !== null) {
  console.log(toSqlToolsConnection(entry));
}

| Export | Description | | --- | --- | | exportFromApp(input, options?) | CF login + target + env + write settings | | exportFromCf(input, options?) | Shell cf env <app> and write settings | | exportFromFile(input, options?) | Read VCAP JSON from disk and write settings | | exportFromVcap(input, options?) | Accept in-memory VCAP JSON and write settings | | buildEntryFromVcap(input) | Parse a VCAP payload into a typed AppHanaEntry | | toSqlToolsConnection(entry) | Convert an entry into a single SQLTools connection | | updateVscodeConnections(entries, options?) | Low-level .vscode/settings.json writer | | writeCredentials(entries, options?) | Low-level hana-credentials.json writer | | parseVcapServices(raw) | Strict VCAP JSON parser | | extractHanaCredentials(binding) | Map snake_case → camelCase | | extractVcapServicesSection(stdout) | Isolate the VCAP block from cf env output | | cfLoginAndTarget(input) | cf api + cf auth + cf target -o -s | | cfAppVcapServices(app) | Run cf env and return the VCAP JSON | | assertRegionKey(region) | Guard an unknown string as a known CF region | | Constants | DRIVER, HANA_OPTIONS, CONNECTION_TIMEOUT, PREVIEW_LIMIT, SQLTOOLS_CONNECTIONS_KEY, SQLTOOLS_USE_NODE_RUNTIME_KEY, VSCODE_SETTINGS_REL_PATH, OUTPUT_FILENAME |

📁 Output Files

After a successful export you get two files in the workspace root:

.vscode/settings.json     # SQLTools connections + sqltools.useNodeRuntime
hana-credentials.json     # Backup of every extracted binding (HDI user, URL, cert…)

{
  "sqltools.useNodeRuntime": true,
  "sqltools.connections": [
    {
      "name": "my-srv (eu10)",
      "driver": "SAPHana",
      "server": "host.hana.ondemand.com",
      "port": 443,
      "username": "USER_1",
      "password": "…",
      "database": "SCHEMA_MY_SRV",
      "connectionTimeout": 30,
      "previewLimit": 50,
      "hanaOptions": {
        "encrypt": true,
        "sslValidateCertificate": true,
        "sslCryptoProvider": "openssl"
      }
    }
  ]
}

[!IMPORTANT] Both files contain live HANA credentials. They live inside your workspace, not under ~ — keep them out of git (add to .gitignore if your repo doesn't already exclude hana-credentials.json).

❓ FAQ

Yes. @saptools/sqltools only writes the connection definition. You still need the SQLTools extension and the SQLTools SAP HANA driver to actually run queries.

By default, yes — sqltools.connections is replaced with the newly-exported entries, while every other key in settings.json is preserved. Pass --merge to keep existing connections whose name does not match <app> (<region>).

No. hana-credentials.json contains the HANA password, schema, HDI user, and the certificate payload. Add it to .gitignore.

They are only read by from-app. The tool forwards them directly to cf auth — no storage, no logging. from-cf assumes you are already targeted and ignores both env vars.

Not yet. The parser looks for the hana service label (the default for SAP HANA Cloud / HDI service bindings on BTP). If you have a bespoke label, open an issue and we'll add support.

🛠️ Development

From the monorepo root:

pnpm install
pnpm --filter @saptools/sqltools... build
pnpm --filter @saptools/sqltools typecheck
pnpm --filter @saptools/sqltools lint
pnpm --filter @saptools/sqltools test:unit
pnpm --filter @saptools/sqltools test:e2e:fake
pnpm --filter @saptools/sqltools test:e2e:live   # needs SAP_EMAIL / SAP_PASSWORD

The live e2e suite auto-discovers a real CF app with a hana service binding by scoring candidates from ~/.saptools/cf-structure.json (populated by cf-sync). To pin a specific target:

export E2E_TARGET="eu10/my-org/my-space/my-srv"

Live e2e only performs read-only CF operations (cf api, cf auth, cf target, cf env) — nothing is created, updated, or deleted in Cloud Foundry.

🌐 Related

• 📦 @saptools/cf-sync — sync the CF region → org → space → app tree to disk
• 🔐 @saptools/cf-xsuaa — fetch XSUAA client credentials and OAuth2 tokens
• 🗂️ saptools monorepo — the full toolbox

Made with ❤️ for SAP BTP developers who want to query HANA in VS Code without leaving the editor.

License · MIT