Logali HANA Guard for n8n

n8n-nodes-hana-secure is a security-first n8n community node for governed reads from SAP HANA Platform and SAP HANA Cloud. The package name stays descriptive and searchable; the node appears in n8n as Logali HANA Guard.

Status: 0.9.7 is the current public npm release with provenance and installs by name on self-hosted n8n. The direct connection, governed reads, table-function discovery, and parameterized ABAP CDS runtime recognition have been verified against SAP HANA 2.00.088 on a non-production system. The HANA Cloud / HDI profile, strict TLS gate, generated-schema catalog discovery, object allowlist, column policy, and structured count read were also verified end to end against a real non-production SAP HANA Cloud free-tier instance and HDI container.

Why this node exists

Direct database access can be useful for reporting, reconciliation, data-quality checks, and controlled integration scenarios. It also needs a stricter contract than a generic SQL text box. Logali HANA Guard therefore makes structured read operations the default and places advanced SQL behind an explicit credential-level switch.

This package:

• reads data only;
• binds filter values through prepared statements;
• validates and quotes schema, object, and column identifiers;
• supports credential-level schema, object, and column allowlists;
• can force object-specific filters that callers and AI agents cannot remove;
• supports typed filters, literal text matching, lists, ranges, and AND/OR logic;
• loads governed schema, object, and column choices in the n8n editor;
• reads exactly one row by a typed simple or composite key;
• supports stable composite-key keyset pagination, opaque continuation tokens, and bounded automatic page collection;
• recognizes SQL runtime views, calculation views, and virtual tables that may expose remote CDS runtime objects;
• discovers positional view parameters and named calculation-view placeholders, then binds their values through prepared statements;
• discovers, describes, and invokes governed HANA table functions with catalog-validated scalar inputs and prepared values;
• provides Exists, Count, Distinct, five-row Preview, and multiple aggregates per query;
• discovers primary and unique keys, reports database information, and exposes a sanitized active governance policy summary;
• returns each row as an item, all rows in one item, or enriches the incoming item;
• converts BIGINT, dates/timestamps, and binary values with explicit lossless output modes;
• reuses one HANA connection per node execution and returns safe query diagnostics;
• classifies and redacts database errors, including whether retry may be appropriate;
• enforces query timeouts plus hard row, page, and serialized-result limits;
• escapes catalog-name wildcards and supports a literal object-name prefix;
• enables TLS and certificate validation by default;
• keeps manually written SQL disabled by default;
• can be attached directly to an n8n AI Agent as Logali HANA Guard Tool;
• requires a separate credential opt-in for AI Tool use;
• blocks advanced SQL in the Tool variant even when normal workflows may use it;
• requires a separate opt-in before an AI Tool may discover catalog metadata;
• caps every Tool response by both rows and serialized bytes.

These controls are defense in depth. A least-privilege HANA user remains the primary security boundary.

HANA SQL or OData?

| Requirement | Prefer direct HANA SQL | Prefer OData / released SAP API | | ------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- | | Reconciliation, diagnostics, private reporting | Yes, through an approved view or exact read grant | Also valid when the released API contains the fields | | Read technical metadata or large analytical projections | Often | Sometimes | | Preserve SAP business validations and authorizations | No | Yes | | Create or change S/4 business documents | No | Yes | | Write into an integration-owned staging or queue table | Possible with a separate write credential and reviewed procedure | Optional |

Never use generic INSERT, UPDATE, or DELETE against internal S/4 application tables. Basic writes can be appropriate only for objects the integration owns, such as a staging table, queue, or audited stored procedure. Business changes belong behind released OData APIs, BAPIs, CAP services, or another SAP-supported transactional contract.

Compatibility

• Self-hosted n8n only
• Node.js 22 or later
• SAP HANA Platform or SAP HANA Cloud with an accessible SQL endpoint
• TCP connectivity from the n8n host or container to the HANA SQL port

This is not an OData node. SAP HANA Cloud SQL endpoints normally use TLS over TCP port 443, so 443 is valid when it belongs to the HANA Cloud SQL endpoint. An arbitrary web/OData endpoint on the same port is not interchangeable with a HANA SQL endpoint.

The node uses the Apache-2.0-licensed hdb driver maintained by SAP contributors. The driver is bundled into the published artifact, so users do not need to install a native HANA client. Version 2.27.1 is pinned because the 2.29.x topology/physical-connection rewrite stalled authentication through the tested NAT endpoint. Compatibility with newer driver versions will be re-evaluated before a stable release.

Installation

Install from the n8n editor

On a self-hosted n8n instance, sign in as an Owner or Admin and open Settings → Community Nodes → Install. Enter:

n8n-nodes-hana-secure

Accept the community-node warning and select Install. Create or open a workflow and search for Logali HANA Guard. To update later, return to Settings → Community Nodes and use the package's Update action.

The instance must allow public community packages:

N8N_COMMUNITY_PACKAGES_ENABLED=true
N8N_UNVERIFIED_PACKAGES_ENABLED=true
N8N_COMMUNITY_PACKAGES_PREVENT_LOADING=false

Persist /home/node/.n8n when n8n runs in Docker so the installed package survives container recreation. In queue mode, ensure the package is available to the main process and every worker.

Local development test

From this repository:

npm install
npm test
npm run lint
npm run build

Run npm pack to create an installable tarball for a non-production test before publishing.

Install a test tarball in Docker

Copy the tarball to the Docker host and replace <n8n-container> with the development container name:

docker cp n8n-nodes-hana-secure-0.9.7.tgz <n8n-container>:/tmp/

docker exec -u node -it <n8n-container> sh
mkdir -p /home/node/.n8n/nodes
cd /home/node/.n8n/nodes
npm install --omit=dev /tmp/n8n-nodes-hana-secure-0.9.7.tgz
exit

docker restart <n8n-container>

The /home/node/.n8n directory must be backed by a persistent volume. After the restart, refresh n8n and search for Logali HANA Guard. Verify the installed version from the Docker host:

docker exec -u node <n8n-container> sh -lc \
  'cd /home/node/.n8n/nodes && npm ls n8n-nodes-hana-secure'

To uninstall the test tarball:

docker exec -u node <n8n-container> sh -lc \
  'cd /home/node/.n8n/nodes && npm uninstall n8n-nodes-hana-secure'
docker restart <n8n-container>

The direct SQL implementation requires TCP/TLS runtime capabilities and is intended for self-hosted n8n. It is not currently available as a verified n8n Cloud node.

Credential configuration

Create a Logali HANA Guard API credential with:

| Field | Purpose | | ---------------------------- | ------------------------------------------------------------------------------------------------ | | Connection Profile | Direct HANA Platform connection or guided HANA Cloud / HDI setup | | Host | HANA SQL endpoint hostname or IP address | | SQL Port | Tenant SQL endpoint port; SAP HANA Cloud normally uses TCP 443 | | Database Name | Optional SQL tenant name; leave empty for a standard HDI service key | | Default Schema | Optional fallback when a node leaves Schema empty; still checked against Allowed Schemas | | SAP Client | Optional three-digit ABAP client; sets both CLIENT and CDS_CLIENT for client-dependent CDS | | Ignore Server Topology | Keeps NAT, forwarded, proxy, and managed endpoints on the configured host; enabled by default | | Username / Password | Dedicated technical user; never use a broad administrator | | Use TLS | Encrypts the connection; mandatory for the HANA Cloud / HDI profile | | Validate TLS Certificate | Rejects untrusted certificates; mandatory for the HANA Cloud / HDI profile | | Custom CA Certificate | Optional PEM CA for a private certificate authority | | Allowed Schemas | Optional comma-separated schema allowlist | | Allowed Objects | Optional comma- or line-separated exact SCHEMA.OBJECT allowlist | | Column Policies JSON | Optional map of each object to the only columns it may expose or use | | Required Filters JSON | Object-specific row predicates always enforced with AND | | Allow Advanced Read-Only SQL | Opt-in switch for trusted workflows; disabled by default | | Allow AI Tool Use | Separate opt-in required before an AI Agent can call the Tool variant | | Allow AI Catalog Discovery | Separate opt-in for schema, object, and column discovery; disabled by default | | AI Tool Row Limit | Credential-level cap for each Tool call; 100 by default, maximum 1,000 | | AI Tool Result Size Limit | Serialized response cap; 256 KiB by default, maximum 5 MiB | | Connection / Query Timeout | Upper bounds for connection and query execution; connection defaults to 60 seconds for remote TLS endpoints |

Use Test in the credential dialog, or the node's Connection → Test Connection operation.

For an HDI service key, choose SAP HANA Cloud / HDI and copy only its individual connection values into the credential: SQL host, port, user, password, certificate, and schema as Default Schema. Leave Database Name empty for a standard HDI service key: database_id identifies the managed HANA Cloud instance and is not the SQL database name expected by the driver. Do not paste or retain the complete service-key JSON in n8n. This profile fails closed unless both TLS and server-certificate validation are enabled. It changes onboarding only: the same read-only operations, allowlists, prepared values, limits, and database grants remain in force.

For NAT or port-forwarded laboratory endpoints, leave Database Name empty when the published port already targets the tenant and keep Ignore Server Topology enabled. Pre-release 0.1.6 was verified on SAP HANA 2.00.088 with connection metadata, schema listing, and a structured read from SYS.M_DATABASE. The same test account could see that the SAPHANADB schema and its tables existed but received insufficient privilege when it attempted to read SAPHANADB.T001. That is the intended lesson: catalog visibility and network reachability do not grant access to S/4 business rows.

Governance policy example

Policies use exact, unquoted HANA identifiers. For example:

{
	"allowedSchemas": "TRAINING",
	"allowedObjects": "TRAINING.GL_ITEMS,TRAINING.OPEN_ORDERS,TRAINING.GET_OPEN_ORDERS",
	"columnPoliciesJson": "{\"TRAINING.GL_ITEMS\":[\"MANDT\",\"COMPANY_CODE\",\"AMOUNT\",\"CURRENCY\"]}",
	"requiredFiltersJson": "{\"TRAINING.GL_ITEMS\":[{\"column\":\"MANDT\",\"operator\":\"eq\",\"value\":\"250\"}]}"
}

When a column policy exists, Columns = * expands to the approved projection. The same policy also checks filter, sort, group, aggregate, and cursor columns. Required filters are parameterized and cannot be weakened by choosing OR; the node groups user filters separately and joins the credential filters with AND. A reusable sanitized file is available at examples/hana-guard-governance-policy.example.json. The credential test also rejects malformed JSON, policies outside the configured schema/object allowlists, required filters on forbidden columns, and invalid AI result limits before connecting.

Recommended database account

Ask the HANA administrator for a dedicated technical user or role with:

• connection permission;
• SELECT only on the specific views or tables required, plus EXECUTE only on approved table functions when they are used;
• no INSERT, UPDATE, DELETE, DDL, unrestricted procedure/function execution, user administration, or system administration privileges.

Exact grants depend on the HANA model and organizational policy. Do not copy a production business user or database administrator account into n8n.

Operations

Connection

• Test Connection: returns the active user, schema, database, and TLS state.
• Get Database Information: returns the visible system ID, database name, version, usage, start time, and TLS state.

Catalog

• List Schemas: lists visible non-system schemas and applies the credential allowlist.
• List Tables and Views: lists tables, SQL/calculation views, and virtual tables in one allowed schema, with an optional literal prefix and a result limit of 1–1,000 (100 by default).
• List Table Functions / Parameterized CDS: lists visible, valid table functions and generated parameterized ABAP CDS runtimes, prioritizing custom Y* and Z* names when a schema contains more than 500 functions. Results include input counts and SQL security mode and use the same exact object allowlist.
• Describe Table Function / Parameterized CDS: returns scalar inputs, output columns, SQL security mode, owner, determinism, and creation metadata without exposing implementation text.
• Describe Table or View: returns approved column metadata, including comments and defaults when the HANA catalog version exposes them.
• Inspect Semantic/CDS Runtime View: classifies SQL runtime views, calculation views, HANA virtual tables, and table functions that may represent a parameterized ABAP CDS runtime without claiming access to unavailable ABAP source definitions.
• List Semantic View Parameters: returns ordered SQL/virtual-view parameters, named calculation-view placeholders, or table-function inputs, including defaults and mandatory flags where HANA exposes them.
• List Keys and Constraints: discovers governed primary-key and unique-key columns.

Schema, object, filter-column, sort-column, cursor-column, aggregate-column, and key-column fields load their choices from HANA. The choices apply the same schema, object, and column policies as execution, so the editor does not advertise objects the credential is not allowed to use. When Default Schema is configured, it appears first in the schema list and is used only when the node's Schema field is empty; an explicit node value always wins.

Row

• Select Rows: choose governed columns, typed filters, sorting, a row limit, and optional composite-key pagination without writing SQL. Use Automatic (Bounded) to follow pages up to both row and page caps, or pass the opaque nextCursor token to Continue From Cursor Token. Cursor columns are always placed first in the deterministic sort order.
• Get One by Key: provide one or more typed equality fields for a simple or composite key. The operation returns at most one row and fails when an incomplete key matches multiple rows.
• Aggregate Rows: combine up to ten COUNT, COUNT DISTINCT, SUM, AVG, MIN, or MAX calculations, with optional grouping and filters.
• Count Rows, Exists, Distinct Values, and Preview Rows provide bounded structured alternatives for common checks without handwritten SQL.

For a parameterized runtime object, choose Runtime View Parameters:

• Auto Detect (Recommended) inspects the governed runtime object and chooses the appropriate positional, calculation-placeholder, or parameterless form;
• Positional SQL / Virtual CDS View Parameters builds "SCHEMA"."VIEW"(?, ...);
• Calculation View Placeholders builds validated PLACEHOLDER."$$P_NAME$$" => ? bindings;
• No Input Parameters reads a normal table or view.

Node version 1.4 adds Row Source → Table Function / Parameterized ABAP CDS. Choose a valid function, add every scalar input by its catalog name, and then use the normal Select, Preview, Count, Exists, Distinct, Aggregate, key lookup, filters, output-column policy, required filters, limits, and composite pagination controls over the returned table. Table/array inputs are intentionally rejected in this guarded contract. For AI Tool execution, the function must be named explicitly in Allowed Objects; an empty object allowlist is not accepted for discovery or invocation.

The node executes the HANA object that actually exists at SQL runtime. It does not parse or execute ABAP CDS DDL source. A non-parameterized CDS with a generated SQL view is read as a view. A parameterized classic CDS is commonly generated as a HANA table function and is invoked through the table-function source. A remotely exposed parameterized object can also appear as a configured HANA virtual table. CDS view entities without an SQL-visible runtime object must be consumed through a released OData/API or an ABAP-side contract.

ABAP CDS laboratory example

examples/abap/ZI_N8N_COUNTRY_P.ddls.asddls is a small parameterized ABAP CDS training view over the public local API I_Country. It generates the runtime HANA table function ZN8NCOUNTRYP and accepts p_country as its only input. The example was created, syntax-checked, and activated through ADT on a non-production S/4HANA practice system. Live HANA catalog discovery then identified SAPHANADB.ZN8NCOUNTRYP as a valid table function with one input parameter.

To consume it through Logali HANA Guard, choose Row Source → Table Function / Parameterized ABAP CDS, select ZN8NCOUNTRYP, bind P_COUNTRY = DE, and set SAP Client to the practice client (250 in this example). The credential configures both HANA session variables required by client-dependent ABAP CDS runtimes. Direct HANA access still requires a separately reviewed SQL endpoint and database grant to the generated runtime function; ABAP authorization and ADT access do not create that HANA grant. The live least-privilege account correctly reached this database privilege boundary until that explicit grant was reviewed. The SAP client is execution context, not an authorization boundary, so database grants and governance policies remain mandatory.

User filters support AND or OR, equality and comparison operators, LIKE/NOT LIKE, literal contains/starts-with/ends-with matching, IN/NOT IN lists, BETWEEN, and null checks. Values remain prepared-statement parameters; identifiers remain validated and quoted.

Node version 1.3+ provides three output modes plus explicit BIGINT, date/timestamp, and binary conversion. Every execution also has a serialized-size cap:

• Each Row as an Item for normal n8n item-by-item processing;
• All Rows in One Item for a bounded array such as a report or AI context input;
• Add Rows to Input Item to preserve upstream context and enrich it under a chosen field.

SQL (Advanced)

• Execute Read-Only SQL: executes one SELECT with positional ? parameters.

The advanced operation rejects semicolons, comments, caller-provided LIMIT/TOP, and write, administrative, procedure, and transaction keywords. The SQL field does not accept n8n expressions. Parameter values are provided as a JSON array.

Example:

SELECT "COMPANY_CODE", "FISCAL_YEAR", "AMOUNT"
FROM "TRAINING"."GL_ITEMS"
WHERE "COMPANY_CODE" = ? AND "FISCAL_YEAR" = ?

["1010", 2026]

The guard is not a substitute for database permissions. Enable advanced SQL only for trusted workflow editors. In node v1.1+, advanced SQL refuses credentials that contain schema, object, column, or required-filter policies: arbitrary SQL cannot reliably promise those structured boundaries. Use structured Row operations, or a separate database account whose exact grants are the only boundary for advanced reads.

AI Agent Tool

Version 0.6.0+ lets n8n generate Logali HANA Guard Tool from the same node. Add it from an AI Agent's Tool connector and configure one approved operation exactly as you would configure the normal node.

Recommended pattern:

1. Use a HANA account with exact SELECT grants plus schema, object, column, and row policies.
2. Enable Allow AI Tool Use and set conservative row and byte limits in the credential.
3. Choose a structured Row operation such as Select Rows, Get One by Key, Aggregate Rows, Count Rows, Distinct Values, Exists, or Preview Rows in the Tool node.
4. Fix the schema, table/view, columns, sorting, and ordinary filters in the workflow.
5. Let the model supply only narrowly described filter values when needed; keep identifiers fixed.
6. Give the Tool a specific description that says what data it returns and when to call it.

The Tool variant supports Connection and structured Row operations. Catalog operations require the additional Allow AI Catalog Discovery switch. SQL (Advanced) is rejected at runtime for every AI Tool call, even if the same credential permits advanced SQL in a normal workflow. Credential-level row and byte limits prevent a workflow editor, imported template, or unexpectedly wide value from silently expanding the agent's database or context surface.

Example workflows

examples/415_hana_secure_readonly.json contains a sanitized workflow with no credentials, hosts, user names, or internal identifiers. After import, attach your own credential and replace the training schema and view names.

examples/hana-guard-demo-0.5.json demonstrates a composite key lookup and input-item enrichment with node version 1.2. It is sanitized and intentionally contains no credential binding.

examples/hana-guard-complete-0.6.json demonstrates semantic/CDS runtime inspection, parameter discovery, prepared positional parameters, and bounded automatic composite pagination with node version 1.3.

examples/hana-guard-table-function-0.7.json demonstrates function discovery, description, prepared named inputs, governed output columns, and bounded composite pagination with node version 1.4. The corresponding reviewed lab DDL template is sql/setup_table_function_demo.sql.

examples/hana-guard-cds-country-0.7.json demonstrates recognition and governed invocation of the parameterized ABAP CDS runtime table function ZN8NCOUNTRYP.

The webinar examples are also sanitized:

• examples/webinar_catalog_discovery.json verifies the session and discovers visible schemas;
• examples/webinar_object_inventory.json checks three pre-approved demo objects through SYS.M_TABLES, without reading business rows;
• examples/webinar_data_samples.json contains the bounded T001, VBAK, and ACDOCA reads to run only after the dedicated account receives reviewed grants.
• examples/webinar_hana_external_ai_agent.json attaches Logali HANA Guard directly to an AI Agent and combines its bounded HANA read with released OData and external evidence tools.

sql/setup_webinar_readonly.sql is a reviewable lab template for the exact role and object grants. It contains placeholders only and must be executed by the object owner or an administrator with the required grant option.

MCP pattern

Direct AI Tool support does not turn the node into a generic SQL agent. For MCP, continue to wrap fixed sub-workflows behind n8n's MCP Server Trigger and publish narrow tools such as:

• get_company_codes — fixed object, fixed columns, fixed row limit;
• get_recent_sales_orders — approved projection and deterministic sorting;
• get_ledger_sample — fixed company/year filters and bounded output.

Do not publish a run_sql tool. The HANA credential, schema allowlist, node limits, sub-workflow input schema, and MCP authentication are separate layers and should all remain in place.

Development and release

The project was scaffolded with the official n8n node CLI. The build compiles the node and bundles the pure-JavaScript HANA driver while leaving n8n-workflow external.

Before a release:

npm run lint
npm test
npm run build
npm pack --dry-run

See CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md.

The public repository is https://github.com/Logali-Group/n8n-nodes-hana-secure. npm Trusted Publishing is configured for the public GitHub repository and publish.yml; version tags publish through short-lived OIDC credentials with provenance instead of a long-lived npm token.

License and trademarks

This project is licensed under the MIT License. See LICENSE.md.

The bundled hdb driver is licensed under Apache License 2.0. See THIRD_PARTY_NOTICES.md.

SAP and SAP HANA are trademarks or registered trademarks of SAP SE in Germany and other countries. This independent community project is not affiliated with, sponsored by, or endorsed by SAP SE or n8n.