mssql is a robust and actively maintained Node.js client for Microsoft SQL Server, currently stable at version 12.3.1. It features a rapid release cadence, with multiple minor and patch versions frequently released, often within weeks, and major versions roughly annually. The library supports multiple underlying TDS drivers: the pure JavaScript `Tedious` driver (default) and the native `MSNodeSQLv8` driver, offering flexibility based on deployment environment and performance needs. It provides a modern API with support for async/await, Promises, ES6 tagged template literals, and streaming, alongside traditional callbacks. Key differentiators include its comprehensive API for managing connections, connection pools, and requests, as well as explicit support for SQL Server features like input/output parameters, stored procedure execution, and bulk inserts.
npm install mssqlVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to establish a connection to SQL Server using a configuration object, perform parameterized inserts, retrieve data using a tagged template literal query, and properly close the connection pool. It uses environment variables for sensitive credentials and shows basic error handling.
Ensure all connection configuration objects are treated as immutable once passed to `sql.connect()`. Make copies if modifications are necessary elsewhere in the application lifecycle.
Enable TCP/IP in SQL Server Configuration Manager for your SQL Server instance and ensure the SQL Server Browser service is running or that you specify the port (e.g., 1433) directly in your connection string/config.
For Azure, always set `options: { encrypt: true }`. For local development with self-signed certificates, use `options: { trustServerCertificate: true }`. For production with proper SSL certificates, `trustServerCertificate` should be `false` (default) and a valid CA provided.Install `msnodesqlv8` with `npm install mssql msnodesqlv8` and use `import sql from 'mssql/msnodesqlv8'` (or `require('mssql/msnodesqlv8')`) to leverage this driver. Ensure your environment meets the native driver's OS requirements.When constructing connection strings manually, ensure that parts like `User Id`, `Password`, `Server`, and `Database` are correctly URL encoded (e.g., using `encodeURIComponent`). Using a config object for `sql.connect()` generally handles this for individual properties.
Update to the latest `mssql` version to benefit from BigInt handling improvements. When working with `msnodesqlv8`, be aware that BigInts will be transmitted as strings and ensure your SQL schema can accommodate this if implicit conversion isn't desired.
Update `mssql` to version 11.0.1 or higher. Alternatively, convert BigInt values to a compatible number or string type before passing them as parameters if an update is not possible.
Verify credentials, ensure the user exists and has correct permissions in the SQL Server database. Check if SQL Server Authentication is enabled if not using Windows Authentication. If using Windows Authentication, ensure `trustedConnection: true` is set and `msnodesqlv8` is correctly configured.
Ensure SQL Server is running, TCP/IP is enabled in SQL Server Configuration Manager, and no firewall rules are blocking the specified port (default 1433). Verify the `server` and `port` (if specified) in your connection configuration.
Run `npm install msnodesqlv8` in your project directory. Ensure you are importing correctly with `import sql from 'mssql/msnodesqlv8'` (or `require('mssql/msnodesqlv8')`) and not from the base `mssql` package if you intend to use this specific driver.Ensure `sql.close()` is called before attempting to establish a new global connection. For most applications, use connection pools (the default behavior when using `sql.connect(config)`) to manage multiple connections without needing to manually close and reopen the global connection for each operation.