msnodesqlv8

Native ODBC driver for SQL Server (and Sybase ASE) for Node.js and Electron. Ships prebuilt binaries for Linux, macOS and Windows. Supports BCP, TVP, streaming, Always Encrypted, stored procedures, prepared statements, connection pooling and Windows integrated auth.

---

Performance

Measured end-to-end over a network (RTT ~3 ms) against SQL Server 2022 on Linux x64, Node v24, ODBC Driver 18. Schema is a 14-column trade record (bigint PK, datetime2, varchar, nvarchar, int, decimal, bit, nullable nvarchar) — a realistic OLTP row, not a narrow best-case table.

Operation	Rows	Median	Throughput
bulk insert	100,000	762 ms	131k rows/s
bcp insert	100,000	764 ms	131k rows/s
bcp insert	10,000	77 ms	129k rows/s
select (array)	100,000	891 ms	112k rows/s
select (stream)	100,000	815 ms	122k rows/s

Reproduce: node samples/javascript/benchmark.js --rows 1000,10000,100000 --modes bulk,bcp,select. Numbers depend on RTT, schema width and server hardware — use the script to get your own.

---

Install

npm install msnodesqlv8 --save

Prebuilt binaries are downloaded automatically for Linux (x64, glibc ≥ 2.28 and musl), macOS (x64, arm64) and Windows (x64, ia32). Electron binaries are published alongside Node binaries for current major versions.

You also need a Microsoft ODBC driver on the host:

• Linux / macOS: ODBC Driver 17 or 18 (18 recommended, required for BCP).
• Windows: ODBC Driver 17 or 18 via the MSI installer. Older drivers (SQL Server Native Client) still work for non-BCP paths.

Building from source is documented in docs/building-from-source.md.

---

Quick start

Connect and query

const sql = require('msnodesqlv8')

const cs = 'Driver={ODBC Driver 18 for SQL Server};Server=localhost;' +
           'Database=master;UID=sa;PWD=yourStrong(!)Password;Encrypt=no'

const conn = await sql.promises.open(cs)
const res  = await conn.promises.query('SELECT @@VERSION AS v')
console.log(res.first[0].v)
await conn.promises.close()

Parameterised insert

await conn.promises.query(
  'INSERT INTO trades (id, symbol, qty) VALUES (?, ?, ?)',
  [1, 'AAPL', 100]
)

Bulk insert (the fast path)

const table = await conn.promises.getTable('trades')
await table.promises.insert(rows)          // array-bind, ~130k rows/s
// table.setUseBcp(true)                    // opt-in to native BCP protocol

See samples/javascript/ for runnable versions of every snippet below.

---

Features

Feature	Sample	Notes
Connect + query	simple-demo.js	callback and promise APIs
Streaming results	streaming.js	on('row'), on('column'), pause/resume
Stored procedures	procedure.js	named params, output params, return code
Table-valued parameters	tvp.js	build TVP from object array
Bulk insert / update	table-builder.js	BulkTableOpMgr array bind
BCP fast insert	benchmark.js	table.setUseBcp(true) — ODBC 17/18 only
Connection pool	simple-pool.js	built-in, no external dep
Pool scaling strategies	pool-scaling.js	see docs/pool-efficient-strategy.md
Prepared statements	test/prepared.test.js	reuse parsed plan across calls
Transactions	txn.js	explicit begin/commit/rollback
Pause / resume long query	paged-procedure-pause-resume.js	backpressure for large result sets
Thread workers	thread-workers.js	offload queries to worker_threads
Benchmark harness	benchmark.js	reproduces the numbers above

Full API reference lives in the wiki.

---

Standalone example apps

Full runnable projects in their own repos, showing msnodesqlv8 wired into real frameworks. The driver is a native addon — do not call it from a UI thread (renderer process, Next.js client components). Use a server route, API handler or worker.

Stack	Repo
Next.js (pages router)	todo-with-nextjs_msnodesqlv8
Next.js (app router)	todo-with-nextjs-app-router_msnodesqlv8
Vite + Express	msnodesqlv8-vite
TypeScript	msnodesqlv8_ts_sample
JavaScript with IDE typings	msnodesqlv8_yarn_sample
Sequelize	msnodesqlv8-sequelize
mssql package over this driver	msnodesqlv8_mssql_sample
Electron	msnodesqlv8-electron
React	msnodesqlv8-react

---

Platform support

Platform	Arch	Node	Electron
Linux (glibc ≥ 2.28)	x64	20, 22, 24	32+
Linux (musl / Alpine)	x64	20, 22, 24	32+
macOS	x64, arm64	20, 22, 24	32+
Windows	x64, ia32	20, 22, 24	32+
Windows Integrated Auth	x64	supported via Trusted_Connection=yes	—

Tested against SQL Server 2017, 2019, 2022. Sybase ASE support is smaller in scope — see samples/javascript/sybase-query.js and the wiki.

---

Troubleshooting

IM002: Data source name not found — no matching ODBC driver installed. On Linux/macOS check odbcinst -q -d. On Windows check ODBC Data Sources (64-bit).

SSL Provider: certificate verify failed on newer SQL Server — add Encrypt=yes;TrustServerCertificate=yes to the connection string, or install the server certificate.

Segfault on Ubuntu/Debian with Node 18/20 — requires OpenSSL 3.2. See tool/openssl.sh in this repo and the wiki install notes.

BCP crashes or silently falls back — BCP requires ODBC Driver 17 or 18 exactly. Any older driver (SQL Server Native Client, FreeTDS) will either crash the process or silently no-op. Check with odbcinst -q -d.

Prebuilt binary fails to load — your glibc, Node ABI or Electron version may not match a published binary. Try building from source: docs/building-from-source.md.

More issues and workarounds: GitHub Issues.

---

Links

• Wiki (API reference, deep dives)
• Samples
• Test suite — authoritative usage examples for every feature
• Changelog / releases
• Issues
• Legacy README (pre-rewrite, for reference): docs/README-legacy.md

License

Apache 2.0. See LICENSE.txt.