{"id":11025,"library":"hdb","title":"SAP HANA Database Client for Node.js (hdb)","description":"The `hdb` package provides a pure JavaScript client for connecting to SAP HANA Cloud and SAP HANA Platform servers from Node.js applications. Currently at stable version 2.27.1, the library typically sees patch releases addressing bug fixes, dependency updates, and minor feature enhancements. While `hdb` is fully supported by SAP for existing projects, for new development, SAP strongly encourages the use of the `@sap/hana-client` driver, which offers a more comprehensive feature set including automatic reconnect, connection pooling, and client-side data encryption, features explicitly marked as absent in `hdb`. This differentiation positions `hdb` as a viable client for established applications but a less feature-rich option compared to its C++ based counterpart for new projects.","status":"maintenance","version":"2.27.1","language":"javascript","source_language":"en","source_url":"git://github.com/SAP/node-hdb","tags":["javascript","sap","hana","database","in-memory"],"install":[{"cmd":"npm install hdb","lang":"bash","label":"npm"},{"cmd":"yarn add hdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add hdb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { hdb } from 'hdb';","symbol":"hdb","correct":"import hdb from 'hdb';"},{"note":"This is the traditional CommonJS import pattern for the entire module's exports, common in older Node.js projects.","wrong":"const { hdb } = require('hdb');","symbol":"hdb (CommonJS)","correct":"const hdb = require('hdb');"},{"note":"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.","wrong":"import { ConnectionOptions } from 'hdb';","symbol":"ConnectionOptions (TypeScript Type)","correct":"import type { ConnectionOptions } from 'hdb';"}],"quickstart":{"code":"import hdb from 'hdb';\n\nconst client = hdb.createConnection({\n  host: process.env.HANA_HOST ?? 'localhost',\n  port: parseInt(process.env.HANA_PORT ?? '30015', 10),\n  user: process.env.HANA_USER ?? 'DBADMIN',\n  password: process.env.HANA_PASSWORD ?? 'password',\n  encrypt: true, // Use TLS encryption\n  sslValidateCertificate: true // Validate server certificate\n});\n\nclient.on('error', (err) => {\n  console.error('SAP HANA Client Network Error:', err);\n  client.end(); // Ensure connection is closed on error\n});\n\nclient.connect((err) => {\n  if (err) {\n    return console.error('SAP HANA Connection Error:', err);\n  }\n  console.log('Connected to SAP HANA.');\n\n  const sql = 'SELECT CURRENT_USER, CURRENT_SCHEMA FROM DUMMY;';\n  client.exec(sql, (execErr, rows) => {\n    if (execErr) {\n      console.error('SAP HANA Query Execution Error:', execErr);\n    } else {\n      console.log('Query result:', rows);\n      console.log('Current User:', rows[0].CURRENT_USER);\n      console.log('Current Schema:', rows[0].CURRENT_SCHEMA);\n    }\n    client.end(); // Always close the connection\n    console.log('Connection to SAP HANA closed.');\n  });\n});","lang":"typescript","description":"Demonstrates establishing an encrypted connection to SAP HANA, executing a simple SQL query, and handling errors and connection closure using environment variables for credentials."},"warnings":[{"fix":"Review the full changelog on GitHub for major version updates or consider migrating to `@sap/hana-client` for new feature development.","message":"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.","severity":"breaking","affected_versions":">=0.x <2.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.19.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":"<2.26.3"},{"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.","message":"An uncaught exception could occur when attempting to close an already closed `ResultSet` object, leading to application crashes.","severity":"gotcha","affected_versions":"<2.26.2"},{"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.","message":"The `util.os_user` function could lead to an uncaught exception in secured Docker container environments due to restrictions on accessing OS user information.","severity":"gotcha","affected_versions":"<2.26.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Connect error Error: unable to get local issuer certificate"},{"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.","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.","error":"TypeError: hdb.createConnection is not a function"},{"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.","cause":"The executed SQL statement or large object (LOB) parameters exceed the default maximum packet size configured for the `hdb` driver.","error":"Error: SQL statement is too large"}],"ecosystem":"npm"}