Registry / database / odbc
library2.5.0jsnpmunverified

The `odbc` package provides asynchronous Node.js bindings to the `unixODBC` driver manager, enabling Node.js applications to connect and interact with various databases via their respective ODBC drivers. The current stable version, 2.5.0, indicates active development with a consistent release cadence of minor and patch updates every few months. Key differentiators include comprehensive Promise support for modern asynchronous programming patterns, significant performance enhancements achieved by leveraging `SQLBindCol` for efficient result set binding, and a complete rewrite using `N-API` for improved stability and compatibility across supported Node.js LTS versions. This package is designed for robust, high-performance enterprise database connectivity in Node.js environments.

npm install odbc
INSTALL
IMPORT
SIG · ODBC
O
odbc
databasejavascriptv2.5.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

odbc
import odbc from 'odbc';
const odbc = require('odbc');
While CommonJS `require` still works, modern Node.js applications and TypeScript projects should prefer ESM `import`.
Connection
import { Connection } from 'odbc';
This type is primarily used for type annotations. Instances are usually obtained via `odbc.connect()` or `odbc.pool.connect()`.
Result
import { Result } from 'odbc';
This type is primarily used for type annotations, representing the structure of query results.
Cursor
import { Cursor } from 'odbc';
Used for advanced scenarios involving row-by-row data retrieval, particularly for large datasets, and often returned by specific query methods.

Demonstrates connecting to an ODBC data source, executing a simple SELECT query, an INSERT statement with parameters, and gracefully closing the connection using async/await and Promises.

import odbc from 'odbc'; async function runQuery() { let connection: odbc.Connection | null = null; try { // Ensure your DSN is configured in odbc.ini and odbcinst.ini // For example, if you have a DSN named 'my-db-dsn' configured to connect to your database. // Or you can pass a full connection string directly. const connectionString = process.env.ODBC_CONNECTION_STRING ?? 'DSN=my-db-dsn'; connection = await odbc.connect(connectionString); console.log('Successfully connected to the database.'); const result = await connection.query('SELECT 1 AS MyColumn, \'Hello, World!\' AS MyText'); console.log('Query result:', result.length ? result[0] : 'No rows returned.'); const insertResult = await connection.query(`INSERT INTO MyTable (id, name) VALUES (?, ?)`, [2, 'Test User']); console.log('Insert result:', insertResult.count + ' rows affected.'); // Example of calling a stored procedure (replace with actual procedure and parameters) // const procedureResult = await connection.callProcedure('MySchema', 'MyProcedure', [1, 'param2']); // console.log('Procedure result:', procedureResult); } catch (err: any) { console.error('Database operation failed:', err.message); } finally { if (connection) { try { await connection.close(); console.log('Connection closed.'); } catch (closeErr: any) { console.error('Failed to close connection:', closeErr.message); } } } } runQuery();
Debug
Known issues
breakingVersion 2.4.9 dropped support for N-API versions 7 and below, which means older Node.js LTS versions (prior to Node.js 20.x) are no longer supported. Ensure your Node.js environment meets the 'engines' requirement (>=20.0.0).
fix
Upgrade your Node.js environment to an active LTS version (e.g., 20, 22, 24) as specified in the package's engine requirements.
affects: >=2.4.9
gotchaThe package requires `unixODBC` binaries and development libraries to be installed on your system for successful compilation and runtime. Installation commands vary by operating system (e.g., `apt-get`, `yum`, `brew`).
fix
Refer to the `odbc` package README for specific installation instructions for `unixODBC` on your operating system (e.g., `sudo apt-get install unixodbc unixodbc-dev` on Debian/Ubuntu).
affects: >=1.0.0
gotchaDebugging methods changed significantly in v2.4.0. The internal `DEBUG` recompilation option was removed. Tracing of ODBC calls must now be enabled through your driver manager (`unixODBC` or Windows ODBC Data Source Administrator) rather than through `node-odbc` itself.
fix
Configure tracing in your `odbcinst.ini` file (for `unixODBC`) or through the ODBC Data Source Administrator (for Windows) instead of relying on package-specific debug flags.
affects: >=2.4.0
gotchaProper configuration of `odbc.ini` (for DSNs) and `odbcinst.ini` (for drivers) is critical for `node-odbc` to connect to your database. Incorrect or missing entries in these files are a common source of connection failures.
fix
Ensure that your `odbc.ini` and `odbcinst.ini` files are correctly set up and located in a path accessible by `unixODBC`. Consult `unixODBC` documentation for details on configuration.
affects: >=1.0.0
breakingWhile not strictly breaking if callbacks are used, version 2.0 introduced native JavaScript Promise support. If no callback is provided to an asynchronous function, it will now return a Promise. Code expecting immediate return values or older callback patterns without explicit Promise handling might need adjustment.
fix
Refactor asynchronous operations to use `async/await` syntax or `.then()`/`.catch()` Promise chains for modern, clearer error handling and flow control.
affects: >=2.0.0
Errors
Common errors & fixes
Error: Can't find module 'odbc'
The native C++ addon failed to compile or locate, often due to missing `unixODBC` development libraries or an unsupported Node.js version.
fix
Verify `unixODBC` development libraries are installed (e.g., `unixodbc-dev`). Ensure your Node.js version is supported (>=20.0.0). Try `npm rebuild odbc`.
Error: The specified DSN contains an architecture mismatch between the Driver and Application
This error occurs when the ODBC driver (e.g., 32-bit) and the Node.js application's architecture (e.g., 64-bit) do not match, or vice-versa.
fix
Ensure that your ODBC drivers and Node.js runtime (and its compiled addons) are all of the same architecture (either 32-bit or 64-bit). Reinstalling the correct driver or Node.js version may be necessary.
[unixODBC][Driver Manager]Data source name not found, and no default driver specified
The DSN specified in the connection string is not defined in `odbc.ini`, or the driver specified in `odbcinst.ini` is incorrect or missing.
fix
Check your `odbc.ini` and `odbcinst.ini` files. Confirm the DSN name is correct and the associated driver is properly configured and installed. Ensure the `ODBCINI` environment variable points to the correct `odbc.ini` file if it's not in a standard location.
Upgrade
Version history
2.5.0latest on npm
Audit
Dependencies
unixodbcrequiredRequired binaries and development libraries for module compilation and runtime operation.
ODBC driversrequiredSpecific database drivers are needed for connecting to the target database management system.
Agent activity
4 hits · last 30 days
node
4
Resources
odbc — npm install odbc · libregistry