Library / SDK
tediousjs/node-mssql avatar
tediousjs/node-mssql

node-mssql: one SQL Server API over two drivers, and what each driver costs you

Microsoft SQL Server client for Node.js

2,277 stars471 forksJavaScriptMIT

At a glance

What is it?
tediousjs/node-mssql is an MIT-licensed SQL Server client for Node.js that wraps Tedious by default and msnodesqlv8 as an option. Choosing between them decides whether you get pure JavaScript portability or Windows Authentication.
Who is it for?
Use node-mssql if you run Node.js 18.19.0 or later and need a SQL Server client with pooling, transactions, prepared statements and bulk operations behind one API. Reach for the msnodesqlv8 driver only when you need Windows Authentication, and accept the native-install cost.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 5 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 9, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • tediousjs/node-mssql2,277 ★ · +3
Star history
Repository2026-10-082026-11-09
tediousjs/node-mssql2.3k2.3k

3 Stars in the last 32 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Tedious is the default driver, and msnodesqlv8 is a separate native install

node-mssql does not speak the SQL Server wire protocol itself. It sits on top of two TDS drivers and gives them one API. Tedious is the default, written in pure JavaScript, and it runs on Windows, macOS and Linux. MSNodeSQLv8 is Microsoft's and its contributors' V8 driver for SQL Server, and it is native, with support for Windows or Linux and macOS on 64 bits only.

The install commands show the split:

code
npm install mssql
code
npm install mssql msnodesqlv8

The first pulls in Tedious through the package dependencies, where package.json allows tedious ^19.2.2 || ^20.0.0. The second adds the native module beside it.

The cost of the native option is real. If you pick msnodesqlv8, your install now compiles or fetches platform-specific code, and the 32-bit machines are out. If you pick Tedious, you keep a plain npm install that behaves the same on every operating system the project lists. Most readers should start with the default and move only when a missing feature forces them.

msnodesqlv8 6 needs Node.js 22, and older Node.js is pinned to version 5

The native driver has its own runtime floor, separate from the package itself. msnodesqlv8 6 needs Node.js 22 or later. On an older Node.js, you install msnodesqlv8 5 with this command:

code
npm install mssql msnodesqlv8@5

The mssql package states its own floor in package.json: engines node >=18.19.0. That gap matters. A server on Node.js 18 or 20 can run mssql with the default Tedious driver, but it cannot take the current msnodesqlv8 without a pin to the older major.

The pin has a consequence for upgrades. Moving a server from Node.js 20 to 22 is not enough to move msnodesqlv8, because the version in your lock file stays at 5 until you change the install line. Check which major of msnodesqlv8 you are on before you assume the runtime upgrade carried the driver with it.

Windows Authentication works only through the msnodesqlv8 entry point

The package ships two entry files, tedious.js and msnodesqlv8.js, and the choice of driver is a choice of require path. Plain require('mssql') gives Tedious. Windows Authentication goes through a different import:

code
const sql = require('mssql/msnodesqlv8');

The config for it sets options.trustedConnection to true, with a comment that says to set it when using Windows Authentication. A second option, trustServerCertificate, is marked to be set to true when using self-signed certificates. A commented-out driver key, "ODBC Driver 18 for SQL Server", shows where to name a specific ODBC driver.

If you wrote code against the default driver and later need Windows Authentication, the change is not a config flag. It is a different module path, a native install, and the platform limits from the previous sections. The example in the repository is the one worked answer for Windows Authentication.

The connection string needs URL encoding, and the config object sets the pool

There are two ways to connect, and each has a trap. The short form passes a connection string:

code
await sql.connect('Server=localhost,1433;Database=database;User Id=username;Password=password;Encrypt=true')

The repository warns twice that parts of the connection URI must be correctly URL encoded so that the URI can be parsed. A password with a reserved character is the usual way to hit this. On Windows Azure, add ?encrypt=true to the connection string.

The longer form builds a config object from environment variables: user from process.env.DB_USER, password from process.env.DB_PWD, database from process.env.DB_NAME, and server set to 'localhost'. The pool block sets max to 10, min to 0 and idleTimeoutMillis to 30000. The options block sets encrypt to true, marked for Azure, and trustServerCertificate to false, with a note to change it to true for local dev or self-signed certs.

Named instances use the server field: 'localhost\\instance' is the form given. One prerequisite sits outside the code. The package requires TCP/IP to connect to SQL Server, and you may need to enable it in your installation.

Four ways to call the same query, and a tagged template that parameterizes for you

The documentation lists async/await, promises, ES6 tagged template literals, callbacks and streaming as styles. They reach the same requests, so the choice is about your codebase, not about capability.

The tagged template form is the shortest:

code
const result = await sql.query`select * from mytable where id = ${value}

An interpolated ${value} in that form is sent as a parameter, which is why the documentation has a separate SQL injection section. The explicit form makes parameters visible. A pool.request() chain calls .input('input_parameter', sql.Int, value) and then .query('select * from mytable where id = @input_parameter'). For a stored procedure, the chain adds .output('output_parameter', sql.VarChar(50)) and ends with .execute('procedure_name').

The Request object also lists batch, bulk, cancel, pipe, toReadableStream, replaceInput and replaceOutput. Bulk inserts, parameterized queries and timeouts each map to one of those methods or to the config. The truncated example text does not show them in full, so read the linked sections before relying on a signature.

Transactions, prepared statements and table-valued parameters are separate objects

Beyond Request, the API exposes Transaction and PreparedStatement as their own classes. A Transaction has begin with an isolation level, commit and rollback. A PreparedStatement has input and output declarations, prepare, execute with values, and unprepare. The ordering is explicit, so a statement you prepare is a statement you must release.

Other documented areas include Geography and Geometry types, Table-Valued Parameters, JSON support, affected rows, handling duplicate column names, informational messages, metadata, a diagnostics channel and a CLI. The CLI is backed by commander in the dependencies, and the pool uses tarn, which is also in the dependency list. Connection Validation and Pool Management have their own sections under Connections.

The cost is surface area. Each of these is a separate chapter in the documentation, and the front page of the README is an index, not a tutorial. Someone who needs transactions plus a pool should read Pool Management and the Transaction sections together, since the pool decides how many of those run at once, with the default pool max of 10 in the sample config as the only number the examples give.

Major versions break behavior, and releases come in rapid patch bursts

The documentation keeps a separate change list for every major jump: 3.x to 4.x, 4.x to 5.x, and so on up to 11.x to 12.x. That is nine migration notes. Anyone upgrading across several majors reads them in order.

The repository is not archived, and the last push was on 2026-10-25. The recent releases are v12.7.11 on 2026-10-22, then v12.7.12 and v12.7.13 on 2026-10-26, three hours apart in the order given. Tooling in package.json explains the rhythm: semantic-release with commit-analyzer, release-notes-generator and the GitHub and npm plugins, plus commitlint with the conventional config. Releases are produced from commit messages, so a patch version appears whenever a fix commit lands.

For your lock file, that means patch versions move quickly and can be pinned safely, while a major bump is where you read the migration list. The repository also carries SECURITY.md and CONTRIBUTING.md for reporting and contributing. The test scripts in package.json, test-tedious and test-msnodesqlv8, run separate suites for each driver, which shows both drivers are exercised on their own.

Editorial conclusion

Use node-mssql if you run Node.js 18.19.0 or later and need a SQL Server client with pooling, transactions, prepared statements and bulk operations behind one API. Reach for the msnodesqlv8 driver only when you need Windows Authentication, and accept the native-install cost. Before upgrading, read the section for your version in the 11.x to 12.x changes, because the major releases have each carried their own migration notes.

Frequently asked questions

What is node mssql?

node-mssql is a Microsoft SQL Server client for Node.js, published to npm as mssql under the MIT license. It supports two TDS drivers, Tedious by default and MSNodeSQLv8 as an option.

How does node-mssql compare with Tedious?

Tedious is a pure JavaScript driver that node-mssql uses by default, and the package depends on tedious ^19.2.2 || ^20.0.0. node-mssql adds one API on top for pooling, requests, transactions and prepared statements.

What is an alternative driver for node-mssql?

MSNodeSQLv8 is the alternative driver supported inside node-mssql. Install it with npm install mssql msnodesqlv8, and require mssql/msnodesqlv8 to use Windows Authentication.

Can I use Node with SQL through node-mssql?

Yes, for Microsoft SQL Server. Install it with npm install mssql, which needs Node.js 18.19.0 or later, and connect over TCP/IP with sql.connect.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. tediousjs/node-mssql on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tediousjs-node-mssql.svg)](https://hysenlabs.com/projects/tediousjs-node-mssql)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tediousjs-node-mssql.svg)](https://hysenlabs.com/projects/tediousjs-node-mssql)

Was this useful?