Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve msnodesqlv8 documentation in README #1652

Merged
merged 1 commit into from
Jun 18, 2024
Merged

Improve msnodesqlv8 documentation in README #1652

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 67 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,27 @@
# node-mssql

Microsoft SQL Server client for Node.js
**Microsoft SQL Server client for Node.js**

[![NPM Version][npm-image]][npm-url] [![NPM Downloads][downloads-image]][downloads-url] [![Appveyor CI][appveyor-image]][appveyor-url] [![Join the chat at https://gitter.im/patriksimek/node-mssql](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/patriksimek/node-mssql?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Supported TDS drivers:

- [Tedious][tedious-url] (pure JavaScript - Windows/macOS/Linux, default)
- [Microsoft / Contributors Node V8 Driver for Node.js for SQL Server][msnodesqlv8-url] (v2 native - Windows or Linux/macOS 64 bits only)
- [MSNodeSQLv8][msnodesqlv8-url] (Microsoft / Contributors Node V8 Driver for Node.js for SQL Server, v2 native - Windows or Linux/macOS 64 bits only)

## Installation

npm install mssql
### Tedious driver (default)

```
npm install mssql
```

### MSNodeSQLv8 driver (optional)

```
npm install mssql msnodesqlv8
```

## Short Example: Use Connect String

Expand Down Expand Up @@ -68,6 +79,32 @@ const sqlConfig = {
})()
```

## Windows Authentication Example Using MSNodeSQLv8

```javascript
const sql = require('mssql/msnodesqlv8');

const config = {
server: "MyServer",
database: "MyDatabase",
options: {
trustedConnection: true, // Set to true if using Windows Authentication
trustServerCertificate: true, // Set to true if using self-signed certificates
},
driver: "msnodesqlv8", // Required if using Windows Authentication
};

(async () => {
try {
await sql.connect(config);
const result = await sql.query`select TOP 10 * from MyTable`;
console.dir(result);
} catch (err) {
console.error(err);
}
})();
```

## Documentation

### Examples
Expand All @@ -87,7 +124,7 @@ const sqlConfig = {
### Drivers

* [Tedious](#tedious)
* [Microsoft / Contributors Node V8 Driver for Node.js for SQL Server](#microsoft--contributors-node-v8-driver-for-nodejs-for-sql-server)
* [MSNodeSQLv8](#msnodesqlv8)

### Connections

Expand Down Expand Up @@ -174,16 +211,16 @@ const sql = require('mssql')
let result1 = await pool.request()
.input('input_parameter', sql.Int, value)
.query('select * from mytable where id = @input_parameter')

console.dir(result1)

// Stored procedure

let result2 = await pool.request()
.input('input_parameter', sql.Int, value)
.output('output_parameter', sql.VarChar(50))
.execute('procedure_name')

console.dir(result2)
} catch (err) {
// ... error checks
Expand All @@ -208,7 +245,7 @@ sql.on('error', err => {

sql.connect(config).then(pool => {
// Query

return pool.request()
.input('input_parameter', sql.Int, value)
.query('select * from mytable where id = @input_parameter')
Expand All @@ -229,9 +266,9 @@ sql.on('error', err => {
})

sql.connect(config).then(pool => {

// Stored procedure

return pool.request()
.input('input_parameter', sql.Int, value)
.output('output_parameter', sql.VarChar(50))
Expand Down Expand Up @@ -263,7 +300,7 @@ sql.on('error', err => {
})
```

All values are automatically sanitized against sql injection.
All values are automatically sanitized against sql injection.
This is because it is rendered as prepared statement, and thus all limitations imposed in MS SQL on parameters apply.
e.g. Column names cannot be passed/set in statements using variables.

Expand Down Expand Up @@ -580,7 +617,7 @@ In addition to configuration object there is an option to pass config as a conne
```
Server=localhost,1433;Database=database;User Id=username;Password=password;Encrypt=true
```
###### Standard configuration using msnodesqlv8 driver
###### Standard configuration using MSNodeSQLv8 driver
```
Driver=msnodesqlv8;Server=(local)\INSTANCE;Database=database;UID=DOMAIN\username;PWD=password;Encrypt=true
```
Expand Down Expand Up @@ -648,12 +685,21 @@ On top of the extra options, an `authentication` property can be added to the po
- **authentication** - An object with authentication settings, according to the [Tedious Documentation](https://tediousjs.github.io/tedious/api-connection.html). Passing this object will override `user`, `password`, `domain` settings.
- **authentication.type** - Type of the authentication method, valid types are `default`, `ntlm`, `azure-active-directory-password`, `azure-active-directory-access-token`, `azure-active-directory-msi-vm`, or `azure-active-directory-msi-app-service`
- **authentication.options** - Options of the authentication required by the `tedious` driver, depends on `authentication.type`. For more details, check [Tedious Authentication Interfaces](https://github.com/tediousjs/tedious/blob/v11.1.1/src/connection.ts#L200-L318)
- `tedious` does not support Windows Authentication/Trusted Connection, however the `msnodesqlv8` driver does.

More information about Tedious specific options: http://tediousjs.github.io/tedious/api-connection.html

### Microsoft / Contributors Node V8 Driver for Node.js for SQL Server
___

**Requires Node.js v10+ or newer. Windows 32-64 bits or Linux/macOS 64 bits only.** This driver is not part of the default package and must be installed separately by `npm install msnodesqlv8@^2`. To use this driver, use this require syntax: `const sql = require('mssql/msnodesqlv8')`.
### MSNodeSQLv8

Alternative driver, requires Node.js v10+ or newer; Windows (32 or 64-bit) or Linux/macOS (64-bit only). It's not part of the default package so it must be [installed](#msnodesqlv8-driver) in addition. Supports [Windows/Trusted Connection authentication](#windows-authentication-example-using-msnodesqlv8).

**To use this driver you must use this `require` statement:**

```javascript
const sql = require('mssql/msnodesqlv8')
```

Note: If you use import into your lib to prepare your request (`const { VarChar } = require('mssql')`) you also need to upgrade all your types import into your code (`const { VarChar } = require('mssql/msnodesqlv8')`) or a `connection.on is not a function` error will be thrown.

Expand All @@ -678,6 +724,8 @@ Driver={SQL Server Native Client 11.0};Server={#{server}\\#{instance}};Database=

Please note that the connection string with this driver is not the same than tedious and use yes/no instead of true/false. You can see more on the [ODBC](https://docs.microsoft.com/fr-fr/dotnet/api/system.data.odbc.odbcconnection.connectionstring?view=dotnet-plat-ext-5.0) documentation.

___

## Connections

Internally, each `ConnectionPool` instance is a separate pool of TDS connections. Once you create a new `Request`/`Transaction`/`Prepared Statement`, a new TDS connection is acquired from the pool and reserved for desired action. Once the action is complete, connection is released back to the pool. Connection health check is built-in so once the dead connection is discovered, it is immediately replaced with a new one.
Expand Down Expand Up @@ -1341,7 +1389,7 @@ ps.prepare('select @param as value', err => {

console.log(result.recordset[0].value) // return 12345
console.log(result.rowsAffected) // Returns number of affected rows in case of INSERT, UPDATE or DELETE statement.

ps.unprepare(err => {
// ... error checks
})
Expand Down Expand Up @@ -1374,9 +1422,9 @@ ps.prepare('select @param as value', err => {

request.on('done', result => {
// Always emitted as the last one

console.log(result.rowsAffected) // Returns number of affected rows in case of INSERT, UPDATE or DELETE statement.

ps.unprepare(err => {
// ... error checks
})
Expand Down Expand Up @@ -1682,7 +1730,7 @@ More information about JSON support can be found in [official documentation](htt

## Handling Duplicate Column Names

If your queries contain output columns with identical names, the default behaviour of `mssql` will only return column metadata for the last column with that name. You will also not always be able to re-assemble the order of output columns requested.
If your queries contain output columns with identical names, the default behaviour of `mssql` will only return column metadata for the last column with that name. You will also not always be able to re-assemble the order of output columns requested.

Default behaviour:
```javascript
Expand Down
Loading