{"id":13316,"library":"ibm_db","title":"IBM DB2 and Informix Database Driver for Node.js","description":"ibm_db is a native Node.js driver providing both asynchronous (Promise-based and async/await compatible) and synchronous interfaces for connecting to IBM DB2 and IBM Informix databases. The current stable version is 4.0.0. Releases are relatively frequent, addressing dependencies, platform support, and core driver updates. A key differentiator is its native C++ binding, offering direct high-performance access to IBM databases, and its automatic download of the necessary `clidriver`. It supports a wide array of platforms including Windows, macOS (Intel & ARM), Linux (x64, IBM Z, Power PC), and AIX, making it suitable for diverse enterprise environments. Since v4.0.0, it utilizes Node-API (N-API) for improved version independence.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/ibmdb/node-ibm_db","tags":["javascript","node","odbc","db2","driver","typescript"],"install":[{"cmd":"npm install ibm_db","lang":"bash","label":"npm"},{"cmd":"yarn add ibm_db","lang":"bash","label":"yarn"},{"cmd":"pnpm add ibm_db","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` works, ESM `import` is the preferred modern approach for Node.js development. ibm_db does not export a default.","wrong":"const ibmdb = require('ibm_db');","symbol":"ibmdb","correct":"import * as ibmdb from 'ibm_db';"},{"note":"Individual functions can be imported directly, but the module is typically imported as a namespace.","symbol":"open","correct":"import { open } from 'ibm_db';"},{"note":"There is no default export; functions and objects are exposed as named exports or properties of the main module object. Importing the full module as `ibmdb` is common.","wrong":"import ibmdb from 'ibm_db';","symbol":"open, query","correct":"import { open, query } from 'ibm_db';\n// Or for the full module:\nimport * as ibmdb from 'ibm_db';"}],"quickstart":{"code":"import * as ibmdb from 'ibm_db';\n\n// Configuration for a local DB2 database\n// Replace with your actual connection string\nconst connStr = process.env.DB2_CONN_STR ?? 'DATABASE=sample;HOSTNAME=localhost;PORT=50000;PROTOCOL=TCPIP;UID=db2inst1;PWD=password;';\n\nasync function runQuery() {\n  let conn;\n  try {\n    console.log('Attempting to connect to DB2...');\n    conn = await ibmdb.open(connStr);\n    console.log('Connection successful!');\n\n    // Create a table if it doesn't exist\n    try {\n      await conn.query(\"CREATE TABLE my_table (id INT, name VARCHAR(50))\");\n      console.log('Table my_table created successfully (or already exists).');\n    } catch (createErr) {\n      if (createErr.message.includes('SQLCODE=-601')) { // -601 is object already exists\n        console.log('Table my_table already exists, skipping creation.');\n      } else {\n        throw createErr; // Re-throw other errors\n      }\n    }\n\n    // Insert data\n    const insertResult = await conn.query(\"INSERT INTO my_table (id, name) VALUES (1, 'Alice')\");\n    console.log('Inserted 1 row:', insertResult.rowCount);\n\n    // Select data\n    const data = await conn.query(\"SELECT * FROM my_table WHERE id = 1\");\n    console.log('Selected data:', data);\n\n    // Update data\n    const updateResult = await conn.query(\"UPDATE my_table SET name = 'Bob' WHERE id = 1\");\n    console.log('Updated 1 row:', updateResult.rowCount);\n\n  } catch (err) {\n    console.error('Error during database operation:', err.message);\n  } finally {\n    if (conn) {\n      try {\n        await conn.close();\n        console.log('Connection closed.');\n      } catch (closeErr) {\n        console.error('Error closing connection:', closeErr.message);\n      }\n    }\n  }\n}\n\nrunQuery();\n","lang":"typescript","description":"This quickstart demonstrates how to establish a connection to a DB2 database, create a table (handling existing tables), insert data, query data, and update data using the asynchronous API, ensuring the connection is properly closed."},"warnings":[{"fix":"No direct code changes are typically required for standard usage, as N-API ensures ABI stability across Node.js versions. However, if you have custom native modules that interact with `ibm_db`'s internals, they might need to be re-evaluated or updated to use N-API.","message":"The `ibm_db` driver migrated from `NAN` to `Node-API (N-API)` in version 4.0.0, which can affect custom native add-ons or deep integrations relying on specific Node.js internal APIs. While this improves Node.js version independence, it's a significant internal architectural change.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If you have an older `db2connect` license, install `ibm_db` by explicitly specifying the older `clidriver` version: `npm install ibm_db --clidriver=\"v11.5.9\"`. Otherwise, acquire a compatible v12.1 db2connect license.","message":"Starting from `ibm_db@3.3.0`, the package by default downloads `v12.1.x clidriver`, which requires a `v12.1 db2connect license`. Older `db2connect` licenses (e.g., for v11.x clidriver) will lead to `SQL1598N` errors if the default driver is used without a compatible license.","severity":"breaking","affected_versions":">=3.3.0"},{"fix":"Refer to the `ibm_db` APIDocumentation on GitHub specifically for 'SSLConnection' instructions. Ensure proper `DB2CLNTOPT` environment variables or connection string parameters are set, and certificates are correctly configured and accessible.","message":"Connecting to a secure database using SSL/TSL may fail with GSKit errors if the necessary configurations or certificates are missing or incorrect. This is a common issue for secure connections.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `gcc` (version >= 8.4), `g++` (gcc-c++), `python3` (>=3.8.0), and `make` are installed. On RHEL, update your compiler. On Docker, include `RUN apt-get update && apt-get install gcc g++ libcrypt libxcrypt-compat python3 make -y` in your Dockerfile. For WSL, install `build-essentials`.","message":"Installation of `ibm_db` requires a C++ compiler (supporting C++11), Python 3 (for `node-gyp`), and `make` on most non-Windows/Mac platforms, especially if precompiled binaries are not available or fail to download. Default compilers on older Linux distributions might be insufficient.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install `ibm_db` using the `--unsafe-perm` flag: `npm install --unsafe-perm ibm_db`. This allows `node-gyp` to run scripts with root privileges if necessary.","message":"When installing `ibm_db` as the `root` user within a Docker container, permission issues can prevent successful native module compilation or `clidriver` download.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that your `db2connect` license is valid and compatible with the `clidriver` version downloaded by `ibm_db`. If using `ibm_db@3.3.0` or newer, ensure you have a v12.1 db2connect license or explicitly install with an older clidriver (`npm install ibm_db --clidriver=\"v11.5.9\"`).","cause":"This error typically indicates an issue with the `db2connect` license required for connecting to certain DB2 servers, especially when the `clidriver` version does not match the license.","error":"SQL1598N A DRDA AS token was detected. The DB2 server is configured to allow connection to the DRDA AS."},{"fix":"Consult the `ibm_db` API Documentation for 'SSLConnection' to correctly configure SSL. Ensure all necessary certificates are in place, accessible, and specified correctly in your connection string or environment variables (e.g., `DB2CLNTOPT`).","cause":"This error points to issues with SSL/TLS configuration, such as missing certificates, incorrect key stores, or misconfigured connection parameters when trying to establish a secure database connection.","error":"GSKit Error: A security error occurred."},{"fix":"Ensure `make`, a C++ compiler (like `gcc`/`g++` version >= 8.4), and `python3` (>=3.8.0) are installed and accessible in your system's PATH. On Windows, ensure Visual Studio (2015.3 v14.00 or >= 2022) is installed if precompiled binaries are not used.","cause":"This typically occurs during the native module compilation phase, indicating that the `make` utility or its dependencies (like a C++ compiler) are either missing or not correctly configured in the system's PATH.","error":"Error: `make` failed with exit status: 2"},{"fix":"Check prerequisites: ensure C++ compiler (C++11 support), Python3 (>=3.8.0), and `make` are installed. For Docker, use `npm install --unsafe-perm ibm_db` for root users and ensure build dependencies are installed (`RUN apt-get update && apt-get install gcc g++ python3 make -y`). Since v4.0.0 uses N-API, Node.js version compatibility should be less of an issue, but build tools are still required if precompiled binaries are not applicable.","cause":"This is a generic `node-gyp` rebuild failure, often due to missing build tools (compiler, python, make) or environmental issues (e.g., permissions in Docker, incompatible Node.js versions with native add-ons pre-N-API).","error":"npm ERR! code 1\nnpm ERR! ibm_db@X.Y.Z install: `node-gyp rebuild`"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}