{"id":17564,"library":"database-js-mssql","title":"SQL Server Driver for Database-js","description":"database-js-mssql is a JavaScript driver for SQL Server designed to integrate with the `database-js` abstraction layer. It acts as a wrapper around the popular `node-mssql` library, enabling `database-js` applications to connect and query SQL Server databases (versions 2000-2017). The package is currently at version 0.3.0. As a specialized driver, its release cadence is tied to updates in `database-js` or critical fixes in its underlying `node-mssql` dependency, suggesting a maintenance-oriented development. Its key differentiator is providing a consistent `database-js` interface for SQL Server, allowing for database-agnostic code when using the `database-js` ecosystem, rather than directly interacting with `node-mssql`. This facilitates easier database switching and a unified API for data access across different SQL platforms.","status":"maintenance","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/thiagodp/database-js-mssql","tags":["javascript","database-js-mssql","database-js","mssql","ms-sql","sqlserver","sql-server","database"],"install":[{"cmd":"npm install database-js-mssql","lang":"bash","label":"npm"},{"cmd":"yarn add database-js-mssql","lang":"bash","label":"yarn"},{"cmd":"pnpm add database-js-mssql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core abstraction layer that this package provides a driver for.","package":"database-js","optional":false},{"reason":"Underlying SQL Server client library that this package wraps.","package":"mssql","optional":false}],"imports":[{"note":"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.","wrong":"import { Connection } from 'database-js-mssql';","symbol":"Connection","correct":"import { Connection } from 'database-js';"},{"note":"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.","wrong":"import 'database-js-mssql';","symbol":"database-js-mssql","correct":"require('database-js-mssql');"},{"note":"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.","wrong":"const MssqlDriver = require('database-js-mssql').MssqlDriver;","symbol":"MssqlDriver","correct":"import { MssqlDriver } from 'database-js-mssql';"}],"quickstart":{"code":"import { Connection } from 'database-js';\n\n(async () => {\n    // Ensure the driver is loaded, even if not directly referenced\n    require('database-js-mssql'); \n\n    let conn, statement, results;\n    try {\n        // Use environment variables for sensitive connection details\n        const user = process.env.DB_USER ?? 'username';\n        const password = process.env.DB_PASSWORD ?? 'password';\n        const server = process.env.DB_SERVER ?? 'localhost';\n        const database = process.env.DB_DATABASE ?? 'master';\n\n        // Connection string format: mssql:///user:password@server/database\n        conn = new Connection(`mssql:///${user}:${password}@${server}/${database}`);\n        console.log('Successfully connected to SQL Server.');\n\n        // Prepare a statement with a placeholder\n        statement = conn.prepareStatement(\"SELECT * FROM states WHERE state = ?\");\n\n        // Execute the query with a parameter\n        results = await statement.query(\"South Dakota\");\n        console.log('Query results:', results);\n\n    } catch (reason) {\n        console.error('An error occurred:', reason);\n    } finally {\n        if (conn) {\n            await conn.close();\n            console.log('Connection closed.');\n        }\n    }\n})();","lang":"javascript","description":"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."},"warnings":[{"fix":"Review 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.","message":"The `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()`.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"For 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.","message":"This 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade `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.","message":"The `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.","severity":"gotcha","affected_versions":"<0.2.2"},{"message":"The `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.","severity":"gotcha"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `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.","cause":"The `database-js-mssql` package has not been installed or correctly loaded/registered with `database-js`.","error":"Error: No driver found for \"mssql\""},{"fix":"Double-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.","cause":"Incorrect username, password, or insufficient permissions for the specified database user. This is a common SQL Server authentication error.","error":"Login failed for user 'username'."},{"fix":"Verify 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.","cause":"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.","error":"ConnectionError: Failed to connect to servername\\instancename in 15000ms"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}