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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connection
✓ import { Connection } from 'database-js';
✗ import { Connection } from 'database-js-mssql';
The `Connection` class is part of the `database-js` abstraction layer, which this package extends. Users typically interact with `database-js` directly, not `database-js-mssql` for the core connection object.
database-js-mssql
✓ require('database-js-mssql');
✗ import 'database-js-mssql';
This package is primarily a CommonJS module. Requiring it ensures the driver is registered with `database-js`. It's a side-effect import for driver discovery, as it doesn't typically export user-facing symbols directly in simple use cases.
MssqlDriver
✓ import { MssqlDriver } from 'database-js-mssql';
✗ const MssqlDriver = require('database-js-mssql').MssqlDriver;
While not explicitly shown in the README, driver packages for `database-js` typically export their specific driver class (e.g., `MssqlDriver`) for advanced usage, such as manual registration or type hinting in TypeScript projects. This package primarily uses CommonJS `require` syntax.
Demonstrates how to establish a connection to a SQL Server database, prepare and execute a parameterized query, and properly close the connection using the `database-js` API powered by this driver.
import { Connection } from 'database-js';
(async () => {
// Ensure the driver is loaded, even if not directly referenced
require('database-js-mssql');
let conn, statement, results;
try {
// Use environment variables for sensitive connection details
const user = process.env.DB_USER ?? 'username';
const password = process.env.DB_PASSWORD ?? 'password';
const server = process.env.DB_SERVER ?? 'localhost';
const database = process.env.DB_DATABASE ?? 'master';
// Connection string format: mssql:///user:password@server/database
conn = new Connection(`mssql:///${user}:${password}@${server}/${database}`);
console.log('Successfully connected to SQL Server.');
// Prepare a statement with a placeholder
statement = conn.prepareStatement("SELECT * FROM states WHERE state = ?");
// Execute the query with a parameter
results = await statement.query("South Dakota");
console.log('Query results:', results);
} catch (reason) {
console.error('An error occurred:', reason);
} finally {
if (conn) {
await conn.close();
console.log('Connection closed.');
}
}
})();
Debug
Known issues
breakingThe `close()` method now closes all connections managed by the connection pool, rather than just a single connection. This changes behavior for applications that relied on granular control over individual connections via `close()`.fixReview application logic that calls `conn.close()` to ensure the desired behavior aligns with closing all pooled connections. If individual connection management is required, investigate `database-js` or `node-mssql` documentation for alternative APIs.
affects: >=0.3.0
gotchaThis package is a driver for `database-js` and is primarily a CommonJS module, indicated by `require` examples and older `engines.node` specification (>=4). Using ES Modules (`import`) directly for `database-js-mssql` might require specific configuration or a CJS wrapper in a modern ESM-only environment.fixFor new projects, consider if the `database-js` abstraction is still the best fit for modern Node.js applications, which often prefer direct `node-mssql` or ORM usage with ESM. If using, stick to `require()` or ensure proper ESM-CJS interop.
affects: >=0.1.0
gotchaThe `database-js-mssql` driver relies on `node-mssql` as its underlying SQL Server client. An upgrade of `node-mssql` to version 4.2.2 (in `database-js-mssql` v0.2.2) was necessary to address a critical bug (Tedious issue #427). Ensure your `database-js-mssql` version is sufficiently recent to benefit from this and other upstream `node-mssql` fixes.fixUpgrade `database-js-mssql` to at least `0.2.2` to include the `node-mssql` bug fix. Regularly check for updates to `database-js-mssql` and its `node-mssql` dependency to incorporate security patches and performance improvements.
affects: <0.2.2
gotchaThe `database-js` abstraction layer, and by extension this driver, does not inherently support connection pooling beyond what `node-mssql` provides internally. For advanced connection management or multi-database scenarios, direct interaction with `node-mssql`'s pooling features or an external pool manager might be required.
Errors
Common errors & fixes
Error: No driver found for "mssql"
The `database-js-mssql` package has not been installed or correctly loaded/registered with `database-js`.
fixEnsure `npm install database-js-mssql` has been run, and add `require('database-js-mssql');` early in your application's entry point before creating any `database-js` connections. Login failed for user 'username'.
Incorrect username, password, or insufficient permissions for the specified database user. This is a common SQL Server authentication error.
fixDouble-check the username and password in your connection string or environment variables. Verify that the user has the necessary permissions on the SQL Server database. Consult SQL Server logs for more details on the login failure.
ConnectionError: Failed to connect to servername\instancename in 15000ms
The Node.js application could not establish a network connection to the SQL Server instance within the default timeout. This often indicates network issues, incorrect server address/port, or the SQL Server service not running/configured for remote connections.
fixVerify the SQL Server instance is running and accessible from the machine running the Node.js application. Check firewall rules, ensure TCP/IP is enabled for SQL Server, and confirm the server address, instance name, and port (default 1433) in your connection string are correct. For named instances, ensure the SQL Server Browser service is running.
Audit
Dependencies
database-jsrequiredCore abstraction layer that this package provides a driver for.
mssqlrequiredUnderlying SQL Server client library that this package wraps.