node-odbc

odbc is a native Node.js addon that provides an asynchronous bridge to unixODBC, letting JavaScript applications connect to any database with an ODBC driver — including IBM Db2, IBM i, and dozens of other DBMS platforms that ship ODBC support but lack a native Node.js driver. Built with node-addon-api on top of N-API, it compiles once and runs unmodified across Node.js LTS versions without a rebuild step for every runtime upgrade.

The library exposes both callback and Promise-based APIs for connections, prepared statements, and cursors, plus a built-in connection pool that queues and throttles concurrent connection attempts to avoid overwhelming ODBC driver managers. Result sets are bound directly via SQLBindCol rather than the slower SQLGetData, making it a practical choice for teams that need to query legacy or enterprise database systems from a modern JavaScript stack.

What You Get

• Dual callback/Promise API across every async operation — connect, query, prepare, fetch, and transaction control all work either way.
• A connection Pool with configurable initial/increment/max size, connection reuse, and a queue that throttles simultaneous connection attempts.
• Cursor support for fetching large result sets in configurable batches instead of loading everything into memory at once.
• Prepared Statement objects that separate bind and execute phases for repeated parameterized queries.
• Shipped TypeScript type definitions (odbc.d.ts) alongside the JS implementation.

Common Use Cases

• Connecting a Node.js service to an IBM i or Db2 backend that only exposes an ODBC driver.
• Bridging a modern web app to a legacy on-prem database with no native Node.js client library.
• Running parameterized queries against any ODBC-compliant DBMS through a single consistent API.
• Streaming large result sets from a data warehouse using cursor-based fetches to control memory usage.

Under The Hood

Architecture odbc layers a thin N-API native addon (src/odbc.cpp, odbc_connection.cpp, odbc_statement.cpp, odbc_cursor.cpp) under an idiomatic JavaScript wrapper (lib/odbc.js, Connection.js, Statement.js, Cursor.js, Pool.js). The native layer owns the ODBC handle lifecycle (environment, connection, and statement handles) and performs the actual SQLConnect/SQLExecute/SQLFetch calls on async workers so the event loop is never blocked; the JS layer wraps each native object in a class that normalizes callback-vs-Promise call signatures and adds higher-level behavior — most notably Pool, which layers a static ConnectionQueue and an EventEmitter on top of raw Connection objects to throttle how many ODBC connections attempt to establish simultaneously, manage reuse-vs-reconnect semantics, and hand freed connections back to waiting callers. Because every other object (Statement, Cursor, pooled Connection) is built directly on the native connection handle, a change to the core handle lifecycle would ripple through pooling, cursoring, and prepared statements alike.

Tech Stack The native layer is written in C++ against node-addon-api (N-API) rather than the older nan/V8 API, which keeps the compiled binary ABI-stable across Node.js versions — no rebuild needed after upgrading the runtime. Compilation is driven by binding.gyp/node-gyp, with prebuilt binaries fetched at install time via @mapbox/node-pre-gyp and a fallback to source builds. The library talks to databases exclusively through unixODBC (or the platform’s native ODBC driver manager on Windows), so any DBMS with a conformant ODBC driver — Db2, IBM i, Snowflake, SQL Server, and more — works without a database-specific dependency. The JS layer’s only runtime dependency for pooling logic is the async package; tests run under Mocha with dotenv-provided connection strings, and C++ formatting is enforced in CI via clang-format.

Code Quality Tests are organized by feature area (test/connection, test/pool, test/statement, test/cursor, test/queries, test/DBMS) with dozens of spec files, but they require a live ODBC DSN against a real database (documented in test/testenv.md) rather than a mock driver, so the GitHub Actions workflow only runs a cross-platform build and a C++ formatting check — it does not execute the test suite in CI. Error handling in the native layer surfaces ODBC diagnostic records as structured JS Error objects with driver-supplied codes and messages. The JS wrapper classes use explicit typeof-based argument-shape detection to support multiple call signatures, which keeps the public API flexible but adds branching complexity; a shipped odbc.d.ts gives TypeScript consumers type coverage without a full TypeScript rewrite. An Airbnb-derived ESLint config and clang-format govern JS and C++ style respectively.

API Design The API mirrors familiar Node.js database-driver conventions — odbc.connect()/odbc.pool() return either a Promise or invoke a callback depending on whether one was passed — so it drops into existing callback- or async/await-based codebases with minimal adaptation. Getting started requires only a connection string (typically a DSN reference) and a single await odbc.connect(…); there’s no ORM-style setup or schema declaration. The design does ask callers to understand ODBC-specific concepts (cursors, isolation levels, DSNs in odbc.ini) that don’t map directly to database-specific client libraries, which is the tradeoff for supporting arbitrary ODBC drivers through one API.