SAP HANA Database Client for Node.js (hdb)

Common errors

• Connect error Error: unable to get local issuer certificate

  cause The SAP HANA server's TLS/SSL certificate is not trusted by the Node.js client, often due to missing or outdated root CA certificates in the client's trust store.
  fix Ensure your Node.js environment has the necessary root certificates. You can specify trusted CAs in the `createConnection` options using the `ca` property, or set `sslValidateCertificate: false` (not recommended for production). Upgrading `hdb` to `2.26.3` or higher can help as it includes additional fallback certificates.

• TypeError: hdb.createConnection is not a function

  cause Incorrect import of the `hdb` module, leading to `hdb` being `undefined` or not the expected object with the `createConnection` method. This often happens with incorrect named imports in ESM or destructuring in CJS.
  fix For ESM, use `import hdb from 'hdb';`. For CommonJS, use `const hdb = require('hdb');`. Ensure you are not attempting to destructure `createConnection` directly if `hdb` only exports it as a property of its default export.

• Error: SQL statement is too large

  cause The executed SQL statement or large object (LOB) parameters exceed the default maximum packet size configured for the `hdb` driver.
  fix Increase the `packetSize` and `packetSizeLimit` options in the `hdb.createConnection()` configuration. For example: `packetSize: Math.pow(2, 17), packetSizeLimit: Math.pow(2, 20)` to allow larger packets.

Warnings

• breaking The package underwent a major version jump from `0.x` to `2.x`. While specific breaking changes from this transition are not detailed in recent changelogs, such a leap typically indicates significant API overhauls, requiring careful migration for older projects.
  Fix: Review the full changelog on GitHub for major version updates or consider migrating to `@sap/hana-client` for new feature development.
• gotcha SAP officially encourages new projects to use the `@sap/hana-client` driver due to its more extensive feature set (e.g., connection pooling, automatic reconnect, client-side data encryption) and full support for SAP HANA server features. `hdb` is maintained but less feature-rich.
  Fix: For new SAP HANA Node.js projects, evaluate the `@sap/hana-client` package. For existing `hdb` projects, understand the feature limitations and consider migrating if advanced features are required.
• gotcha Users may encounter TLS/SSL connection issues due to outdated or missing root certificates. Recent versions have added fallback certificates (e.g., DigiCert TLS RSA4096 Root G5, DigiCert Global Root G2).
  Fix: Ensure your Node.js environment has up-to-date root certificates. For older `hdb` versions, upgrade to at least `2.26.3` or configure `ca` options manually if connecting to servers using specific certificate authorities. Using `useTLS: true` can leverage Node.js's trusted certificates.
• gotcha An uncaught exception could occur when attempting to close an already closed `ResultSet` object, leading to application crashes.
  Fix: Upgrade to `hdb` version `2.26.2` or newer. Implement defensive checks to ensure `ResultSet` objects are valid and open before attempting to close them.
• gotcha The `util.os_user` function could lead to an uncaught exception in secured Docker container environments due to restrictions on accessing OS user information.
  Fix: Upgrade to `hdb` version `2.26.1` or newer to resolve the `util.os_user` issue. Ensure your Docker containers are configured with appropriate permissions if custom OS user information is required.

Install

• npm install hdb npm
• yarn add hdb yarn
• pnpm add hdb pnpm

Imports

• hdb
  wrong:

  import { hdb } from 'hdb';

  correct:

  import hdb from 'hdb';

  For Node.js environments supporting ESM, this leverages CommonJS interop to import the default `module.exports` object. Alternatively, `import * as hdb from 'hdb';` also works.
• hdb (CommonJS)
  wrong:

  const { hdb } = require('hdb');

  correct:

  const hdb = require('hdb');

  This is the traditional CommonJS import pattern for the entire module's exports, common in older Node.js projects.
• ConnectionOptions (TypeScript Type)
  wrong:

  import { ConnectionOptions } from 'hdb';

  correct:

  import type { ConnectionOptions } from 'hdb';

  For TypeScript projects, `ConnectionOptions` provides type safety for the configuration object passed to `hdb.createConnection()`. This type is typically available via `@types/hdb` if not bundled with the package directly.

Quickstart

Demonstrates establishing an encrypted connection to SAP HANA, executing a simple SQL query, and handling errors and connection closure using environment variables for credentials.

import hdb from 'hdb';

const client = hdb.createConnection({
  host: process.env.HANA_HOST ?? 'localhost',
  port: parseInt(process.env.HANA_PORT ?? '30015', 10),
  user: process.env.HANA_USER ?? 'DBADMIN',
  password: process.env.HANA_PASSWORD ?? 'password',
  encrypt: true, // Use TLS encryption
  sslValidateCertificate: true // Validate server certificate
});

client.on('error', (err) => {
  console.error('SAP HANA Client Network Error:', err);
  client.end(); // Ensure connection is closed on error
});

client.connect((err) => {
  if (err) {
    return console.error('SAP HANA Connection Error:', err);
  }
  console.log('Connected to SAP HANA.');

  const sql = 'SELECT CURRENT_USER, CURRENT_SCHEMA FROM DUMMY;';
  client.exec(sql, (execErr, rows) => {
    if (execErr) {
      console.error('SAP HANA Query Execution Error:', execErr);
    } else {
      console.log('Query result:', rows);
      console.log('Current User:', rows[0].CURRENT_USER);
      console.log('Current Schema:', rows[0].CURRENT_SCHEMA);
    }
    client.end(); // Always close the connection
    console.log('Connection to SAP HANA closed.');
  });
});