node-mssql

mssql is the standard way Node.js applications talk to Microsoft SQL Server. It wraps the pure-JavaScript Tedious driver by default (with an optional MSNodeSQLv8 native driver for ODBC/Windows-auth scenarios) behind a single, consistent API for connection pooling, parameterized queries, stored procedures, transactions, and prepared statements.

The library is built around a global or per-instance ConnectionPool, from which Request, Transaction, and PreparedStatement objects borrow connections and release them back automatically. It supports both callback and Promise-based usage, ES6 tagged-template queries for automatic SQL-injection-safe parameterization, and event-based streaming for processing very large result sets without loading everything into memory.

Maintained under the tediousjs GitHub organization, mssql has been the de facto SQL Server driver for Node.js since 2013, with a large contributor base, frequent releases, and semantic-release-based automated publishing. It ships a small CLI (bin/mssql) for running ad-hoc queries from config files or connection strings, and exposes a diagnostics channel for APM/tracing integrations.

What You Get

• A ConnectionPool class (plus a convenience global pool via sql.connect()) that manages TDS connections using the tarn pooling library, with configurable min/max pool size and idle timeout
• Parameterized Request objects supporting .input()/.output() bindings, stored procedure execution, and ES6 tagged-template queries (sql.query`select * from t where id = $\{id\}`) that are automatically sanitized against SQL injection
• Transaction and PreparedStatement classes for multi-statement atomic operations and repeated parameterized execution
• Streaming support via request.stream = true with recordset/row/rowsaffected/done events, plus request.pause()/resume() for backpressure on large result sets
• Bulk insert support (Request.bulk()) and a Table helper for building table-valued parameters
• A small CLI (bin/mssql) for running queries directly from a connection string or JSON config file, and a diagnostics channel (node:diagnostics_channel) for tracing integrations

Common Use Cases

• Connecting a Node.js/Express/NestJS backend to an existing SQL Server or Azure SQL database
• Running parameterized queries and stored procedures safely without hand-rolling SQL-injection defenses
• Wrapping multi-step writes (e.g. order + line items) in a Transaction for atomicity
• Streaming very large report/export queries row-by-row instead of buffering the full result set in memory
• Bulk-loading CSV/ETL data into SQL Server tables via Request.bulk()

Under The Hood

Architecture

mssql is organized as a thin, driver-agnostic base layer (lib/base/connection-pool.js, request.js, transaction.js, prepared-statement.js) that each concrete driver extends: lib/tedious/ (the default, pure-JS TDS implementation used by index.js) and lib/msnodesqlv8/ (the native ODBC-backed alternative, entered via a separate mssql/msnodesqlv8 subpath). The base ConnectionPool extends Node’s EventEmitter and delegates actual pooling to the external tarn library, while parsing config from either an object or an ADO-style connection string via @tediousjs/connection-string. A global-connection.js module offers a singleton pool so callers can use sql.connect()/sql.query without managing a pool instance themselves. Swapping the underlying driver (e.g. moving from Tedious to MSNodeSQLv8) means extending the same base classes, which keeps the public Request/Transaction/PreparedStatement API stable across both.

Tech Stack

The package is plain CommonJS JavaScript (with a small amount of TypeScript/TSQL in the test fixtures) targeting Node >=18.19, with runtime dependencies on tedious (the TDS protocol driver), tarn (connection pooling), @tediousjs/connection-string (ADO connection-string parsing), commander (the bundled CLI), and debug (namespaced debug logging under mssql:*). Releases are fully automated via semantic-release, commitlint, and GitHub Actions (nodejs.yml), publishing to npm on conventional-commit-driven version bumps.

Code Quality

Testing is split by driver into test/tedious, test/msnodesqlv8, and test/common (unit tests, CLI tests, template-string tests), run with Mocha and linted with standard (zero-config ESLint preset) as part of npm test. Error handling is centralized through a small hierarchy of typed errors (MSSQLError, ConnectionError, RequestError, TransactionError, PreparedStatementError) that wrap driver-level errors while preserving the original error and stack trace. Commit messages are enforced via commitlint/@commitlint/config-conventional, and the CI workflow runs lint plus the unit suite on every push.

What Makes It Unique

Unlike most single-driver database clients, mssql cleanly abstracts two structurally different SQL Server connection strategies (pure-JS TDS via Tedious, and native ODBC via MSNodeSQLv8) behind one identical request/transaction/pooling API, letting consumers switch drivers for platform or authentication reasons (e.g. Windows Integrated Auth) without rewriting query code. Its diagnostics-channel instrumentation and dedicated CLI are also less common additions for a database driver at this level of the stack.