SAP HANA Node.js and Java Integration: A Practical On-Premise Guide

SAP HANA applications commonly use Node.js or Java as the application layer while SAP HANA handles transactional SQL, calculation views, procedures, and persistence. The integration design should make connection ownership, authentication, transaction boundaries, and error handling explicit from the beginning.

This guide focuses on SAP HANA on-premise. It covers direct database connections from Node.js and Java, service-layer patterns, the relationship between XSJS and Node.js, and a practical troubleshooting sequence.

01Choose the integration pattern

The right pattern depends on where application logic belongs and how much control the application needs over database access.

For a broader view of the development landscape, see the SAP HANA development overview. It provides useful context for deciding whether database artifacts, application services, or both should own a business operation.

02Prepare SAP HANA access

Create a dedicated technical database user or application-specific users with only the privileges required by the service. Keep administrative identities out of application configuration. The application identity may need object privileges on tables, views, procedures, or schemas, depending on the chosen design.

Record the following connection properties in a secret-management system or protected deployment configuration:

• SAP HANA host name or virtual host
• SQL port or configured service endpoint
• Database name when connecting to a tenant database
• User name
• Password or another configured authentication method
• TLS requirements and trust material
• Connection-pool limits and timeout values

SAP HANA database explorer and SAP HANA cockpit are useful for validating the target database, checking users and privileges, and reviewing operational symptoms. Use a low-privilege test identity to verify the exact application access path.

For applications built around database artifacts, the SAP HANA HDI containers guide is relevant when the deployment model uses isolated design-time and runtime containers.

03Connect Node.js to SAP HANA

A Node.js service normally uses the SAP HANA client for Node.js. The application creates a connection or pool, executes parameterized statements, reads the result, and releases the connection back to the pool.

A minimal pattern looks like this:

const hana = require('@sap/hdbext');

const options = {
  host: process.env.HANA_HOST,
  port: Number(process.env.HANA_PORT),
  user: process.env.HANA_USER,
  password: process.env.HANA_PASSWORD,
  encrypt: true
};

hana.createConnection(options, (error, connection) => {
  if (error) {
    console.error('HANA connection failed', error);
    return;
  }

  connection.exec(
    'SELECT CURRENT_USER FROM DUMMY',
    (queryError, result) => {
      if (queryError) {
        console.error('HANA query failed', queryError);
      } else {
        console.log(result);
      }
      connection.disconnect();
    }
  );
});

Use the client library and API version supported by the application runtime. In production, use a pool rather than opening a new database connection for every request. Set pool size according to application concurrency and database capacity, then monitor wait time and failed acquisitions.

Use parameter binding for values supplied by users or external systems. Keep SQL structure separate from data values, and return only the columns required by the API. For multi-step operations, define the transaction boundary explicitly and roll back when a later operation fails.

04Connect Java to SAP HANA

Java applications connect through the SAP HANA JDBC driver. A JDBC URL identifies the host, port, and connection options, while the application supplies credentials through protected configuration.

A simple JDBC pattern is:

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;

public class HanaCheck {
    public static void main(String[] args) throws Exception {
        String url = System.getenv("HANA_JDBC_URL");
        String user = System.getenv("HANA_USER");
        String password = System.getenv("HANA_PASSWORD");

        try (Connection connection = DriverManager.getConnection(url, user, password);
             PreparedStatement statement = connection.prepareStatement(
                 "SELECT CURRENT_USER FROM DUMMY");
             ResultSet result = statement.executeQuery()) {
            while (result.next()) {
                System.out.println(result.getString(1));
            }
        }
    }
}

For a long-running service, configure a JDBC connection pool through the application framework or container. Set connection validation, acquisition timeout, idle timeout, maximum lifetime, and pool size deliberately. Align transaction management with the service boundary so that the application does not leave borrowed connections in an open transaction.

Use prepared statements for input values, close JDBC resources with try-with-resources, and log a correlation identifier rather than passwords or complete sensitive payloads. When the application uses Spring, keep datasource and transaction configuration in the deployment configuration rather than embedding credentials in source code.

05Use database procedures and views

A service can call procedures, table functions, calculation views, or ordinary SQL depending on the required behavior. Database-side logic is useful when several clients need the same set-based operation or when data locality materially reduces application-side processing.

A procedure interface should document input types, output structures, transaction expectations, and required privileges. Keep result shapes stable for consumers, and test null handling, empty result sets, authorization failures, and large result sets.

The SAP HANA SQLScript procedures guide is a useful companion when the service delegates reusable data logic to SQLScript. For semantic modeling and reusable analytical consumption, see the SAP HANA CDS views guide.

For large result sets, stream or page data where the client library and query design support it. Avoid selecting unused columns and avoid transferring intermediate data to Node.js or Java when the database can perform the operation efficiently.

06Understand XSJS and Node.js

XSJS is the JavaScript-based application model associated with XS classic. It runs within that legacy application environment and commonly accesses SAP HANA through APIs provided by the XS runtime.

Node.js is a general server-side JavaScript runtime. A Node.js service runs as an application process and connects to SAP HANA through a client library, JDBC bridge, framework integration, or an intermediate service. Its deployment, dependency management, logging, and scaling model therefore differ from XSJS.

When maintaining an existing XSJS application, document its runtime dependencies, database access, authentication model, and exposed endpoints before changing the code. For new services, choose the runtime that matches the organization’s deployment platform, observability standards, security controls, and support model.

07Secure the connection

Use encrypted connections when traffic crosses hosts, networks, or security zones. Configure the client trust store or certificate chain so that the application validates the SAP HANA server identity. Test certificate renewal before the current certificate approaches expiration.

Store passwords, private keys, and trust-store passwords outside source control. Restrict file permissions for local secret material, rotate credentials through an operational process, and remove diagnostic logging that exposes connection properties or query parameters containing sensitive data.

Apply the same least-privilege design to Node.js and Java. Separate deployment identities from runtime identities when the deployment process requires broader access, and grant access to database artifacts rather than broad schema privileges whenever practical.

08Troubleshoot connection failures

Start by identifying the failing layer instead of changing several settings at once.

1. Network path: Confirm that the application host resolves the SAP HANA host name and can reach the configured port.
2. Database target: Confirm the database name and endpoint, especially in a multitenant system with a system database and tenant databases.
3. Authentication: Verify the user, password, account state, and authentication method.
4. Authorization: Run the smallest representative query with the application identity and inspect the required object privileges.
5. TLS: Check certificate trust, host-name validation, protocol settings, and certificate expiry.
6. Pool behavior: Check pool exhaustion, stale connections, acquisition timeouts, and database connection limits.
7. SQL behavior: Reproduce the statement in SAP HANA database explorer and compare parameters, transaction state, and execution time.

The SAP HANA application testing and debugging guide complements this sequence when the connection succeeds but the service returns incorrect results or intermittent failures.

09Monitor the integration

Capture structured application logs for connection failures, query duration, pool acquisition time, transaction rollback, and downstream response status. Avoid logging passwords, tokens, private keys, or unrestricted result data.

Correlate application requests with database activity using a request identifier. Monitor both the application pool and SAP HANA resource behavior so that a slow response can be distinguished from network latency, pool contention, authorization failure, or expensive SQL execution.

Set alerts for sustained connection failures, pool exhaustion, repeated transaction rollbacks, and certificate expiration windows. A healthy integration has observable failure boundaries and a tested recovery procedure.

10Apply a production checklist

Before releasing a Node.js or Java service that connects to SAP HANA, verify:

• The service uses a dedicated least-privilege identity.
• Secrets are stored outside source control and are rotated operationally.
• TLS and certificate validation are configured according to the environment.
• A bounded connection pool is configured.
• Queries use parameter binding.
• Transactions have explicit commit and rollback behavior.
• Large results are paged or streamed where appropriate.
• Application and database errors are correlated without exposing secrets.
• Deployment and runtime identities are separated where required.
• The team has tested database restart, network interruption, expired credentials, and certificate renewal.

A small connectivity check is useful during deployment, but it should be followed by a representative authorization and transaction test. This distinguishes a reachable database from a service that can perform its actual business operation.