0% found this document useful (0 votes)

6K views

MSSQL - NPM

Uploaded by

bkk.prog2

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

6K views

MSSQL - NPM

Uploaded by

bkk.prog2

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 63

9/19/23, 11:28 AM mssql - npm

Pro Teams Pricing Documentation

Search packages Search

mssql
10.0.1 • Public • Published 6 days ago

Readme

Code Beta

6 Dependencies

1,363 Dependents

165 Versions

node-mssql
Microsoft SQL Server client for Node.js

npm v10.0.1 downloads 1.7M/month build passing gitter join chat

Supported TDS drivers:

Tedious (pure JavaScript - Windows/macOS/Linux, default)

Microsoft / Contributors Node V8 Driver for Node.js for SQL Server (v2 native - Windows
or Linux/macOS 64 bits only)

Installation

npm install mssql

Short Example: Use Connect String

https://www.npmjs.com/package/mssql#output-name-type-value 1/63
9/19/23, 11:28 AM mssql - npm

const sql = require('mssql')

async () => {
try {
// make sure that any items are correctly URL encoded in the
await sql.connect('Server=localhost,1433;Database=database;U
const result = await sql.query`select * from mytable where i
console.dir(result)
} catch (err) {
// ... error checks
}
}

If you're on Windows Azure, add ?encrypt=true to your connection string. See docs to
learn more.

Parts of the connection URI should be correctly URL encoded so that the URI can be
parsed correctly.

Longer Example: Connect via Config Object

Assuming you have set the appropriate environment variables, you can construct a config
object as follows:

const sql = require('mssql')

const sqlConfig = {
user: process.env.DB_USER,
password: process.env.DB_PWD,
database: process.env.DB_NAME,
server: 'localhost',
pool: {
max: 10,
min: 0,
idleTimeoutMillis: 30000
},

https://www.npmjs.com/package/mssql#output-name-type-value 2/63
9/19/23, 11:28 AM mssql - npm

options: {
encrypt: true, // for azure
trustServerCertificate: false // change to true for local dev /
}
}

async () => {
try {
// make sure that any items are correctly URL encoded in the conne
await sql.connect(sqlConfig)
const result = await sql.query`select * from mytable where id = ${
console.dir(result)
} catch (err) {
// ... error checks
}
}

Documentation
Examples

Async/Await
Promises
ES6 Tagged template literals
Callbacks
Streaming
Connection Pools

Configuration

General
Formats

Drivers

Tedious
Microsoft / Contributors Node V8 Driver for Node.js for SQL Server

https://www.npmjs.com/package/mssql#output-name-type-value 3/63
9/19/23, 11:28 AM mssql - npm

Connections

Pool Management
ConnectionPool
connect
close

Requests

Request
execute
input
output
toReadableStream
pipe
query
batch
bulk
cancel

Transactions

Transaction
begin
commit
rollback

Prepared Statements

PreparedStatement
input
output
prepare
execute
unprepare

Other

CLI
https://www.npmjs.com/package/mssql#output-name-type-value 4/63
9/19/23, 11:28 AM mssql - npm

Geography and Geometry

Table-Valued Parameter
Response Schema
Affected Rows
JSON support
Handling Duplicate Column Names
Errors
Informational messages
Metadata
Data Types
SQL injection
Known Issues
Contributing
8.x to 9.x changes
7.x to 8.x changes
6.x to 7.x changes
5.x to 6.x changes
4.x to 5.x changes
3.x to 4.x changes
3.x Documentation

Examples
Config

const config = {
user: '...',
password: '...',
server: 'localhost', // You can use 'localhost\\instance' to con
database: '...',
}

Async/Await

https://www.npmjs.com/package/mssql#output-name-type-value 5/63
9/19/23, 11:28 AM mssql - npm

const sql = require('mssql')

(async function () {
try {
let pool = await sql.connect(config)
let result1 = await pool.request()
.input('input_parameter', sql.Int, value)
.query('select * from mytable where id = @input_paramete

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
}
})()

sql.on('error', err => {

// ... error handler
})

Promises
Queries

const sql = require('mssql')

sql.on('error', err => {

// ... error handler
https://www.npmjs.com/package/mssql#output-name-type-value 6/63
9/19/23, 11:28 AM mssql - npm

})

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

return pool.request()
.input('input_parameter', sql.Int, value)
.query('select * from mytable where id = @input_parameter')
}).then(result => {
console.dir(result)
}).catch(err => {
// ... error checks
});

Stored procedures

const sql = require('mssql')

sql.on('error', err => {

// ... error handler
})

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

// Stored procedure

return pool.request()
.input('input_parameter', sql.Int, value)
.output('output_parameter', sql.VarChar(50))
.execute('procedure_name')
}).then(result => {
console.dir(result)
}).catch(err => {
// ... error checks
})

https://www.npmjs.com/package/mssql#output-name-type-value 7/63
9/19/23, 11:28 AM mssql - npm

Native Promise is used by default. You can easily change this with sql.Promise =
require('myownpromisepackage') .

ES6 Tagged template literals

const sql = require('mssql')

sql.connect(config).then(() => {
return sql.query`select * from mytable where id = ${value}`
}).then(result => {
console.dir(result)
}).catch(err => {
// ... error checks
})

sql.on('error', err => {

// ... error handler
})

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.

Callbacks

const sql = require('mssql')

sql.connect(config, err => {

// ... error checks

// Query

new sql.Request().query('select 1 as number', (err, result) => {

// ... error checks

console.dir(result)
})

https://www.npmjs.com/package/mssql#output-name-type-value 8/63
9/19/23, 11:28 AM mssql - npm

// Stored Procedure

new sql.Request()
.input('input_parameter', sql.Int, value)
.output('output_parameter', sql.VarChar(50))
.execute('procedure_name', (err, result) => {
// ... error checks

console.dir(result)
})

// Using template literal

const request = new sql.Request()

request.query(request.template`select * from mytable where id =
// ... error checks
console.dir(result)
})
})

sql.on('error', err => {

// ... error handler
})

Streaming
If you plan to work with large amount of rows, you should always use streaming. Once
you enable this, you must listen for events to receive data.

const sql = require('mssql')

sql.connect(config, err => {

// ... error checks

const request = new sql.Request()

request.stream = true // You can set streaming differently for e

https://www.npmjs.com/package/mssql#output-name-type-value 9/63
9/19/23, 11:28 AM mssql - npm

request.query('select * from verylargetable') // or request.exec

request.on('recordset', columns => {

// Emitted once for each recordset in a query
})

request.on('row', row => {

// Emitted for each row in a recordset
})

request.on('rowsaffected', rowCount => {

// Emitted for each `INSERT`, `UPDATE` or `DELETE` statement
// Requires NOCOUNT to be OFF (default)
})

request.on('error', err => {

// May be emitted multiple times
})

request.on('done', result => {

// Always emitted as the last one
})
})

sql.on('error', err => {

// ... error handler
})

When streaming large sets of data you want to back-off or chunk the amount of data
you're processing to prevent memory exhaustion issues; you can use the
Request.pause() function to do this. Here is an example of managing rows in batches
of 15:

let rowsToProcess = [];

request.on('row', row => {

https://www.npmjs.com/package/mssql#output-name-type-value 10/63
9/19/23, 11:28 AM mssql - npm

rowsToProcess.push(row);
if (rowsToProcess.length >= 15) {
request.pause();
processRows();
}
});
request.on('done', () => {
processRows();
});

function processRows() {
// process rows
rowsToProcess = [];
request.resume();
}

Connection Pools
An important concept to understand when using this library is Connection Pooling as this
library uses connection pooling extensively. As one Node JS process is able to handle
multiple requests at once, we can take advantage of this long running process to create a
pool of database connections for reuse; this saves overhead of connecting to the
database for each request (as would be the case in something like PHP, where one
process handles one request).

With the advantages of pooling comes some added complexities, but these are mostly
just conceptual and once you understand how the pooling is working, it is simple to make
use of it efficiently and effectively.

The Global Connection Pool

To assist with pool management in your application there is the sql.connect()
function that is used to connect to the global connection pool. You can make repeated
calls to this function, and if the global pool is already connected, it will resolve to the
connected pool. The following example obtains the global connection pool by running
sql.connect() , and then runs the query against the pool.

https://www.npmjs.com/package/mssql#output-name-type-value 11/63
9/19/23, 11:28 AM mssql - npm

NB: It's important to note that there can only be one global connection pool connected at
a time. Providing a different connection config to the connect() function will not create
a new connection if it is already connected.

const sql = require('mssql')

const config = { ... }

// run a query against the global connection pool

function runQuery(query) {
// sql.connect() will return the existing global pool if it exists
return sql.connect(config).then((pool) => {
return pool.query(query)
})
}

Awaiting or .then -ing the pool creation is a safe way to ensure that the pool is always
ready, without knowing where it is needed first. In practice, once the pool is created then
there will be no delay for the next connect() call.

Also notice that we do not close the global pool by calling sql.close() after the query
is executed, because other queries may need to be run against this pool and closing it will
add additional overhead to running subsequent queries. You should only ever close the
global pool if you're certain the application is finished. Or for example, if you are running
some kind of CLI tool or a CRON job you can close the pool at the end of the script.

Global Pool Single Instance

The ability to call connect() and close() repeatedly on the global pool is intended
to make pool management easier, however it is better to maintain your own reference to
the pool, where connect() is called once, and the resulting global pool's connection
promise is re-used throughout the entire application.

For example, in Express applications, the following approach uses a single global pool
instance added to the app.locals so the application has access to it when needed. The
server start is then chained inside the connect() promise.

https://www.npmjs.com/package/mssql#output-name-type-value 12/63
9/19/23, 11:28 AM mssql - npm

const express = require('express')

const sql = require('mssql')
const config = {/*...*/}
//instantiate a connection pool
const appPool = new sql.ConnectionPool(config)
//require route handlers and use the same connection pool everywhere
const route1 = require('./routes/route1')
const app = express()
app.get('/path', route1)

//connect the pool and start the web server when done
appPool.connect().then(function(pool) {
app.locals.db = pool;
const server = app.listen(3000, function () {
const host = server.address().address
const port = server.address().port
console.log('Example app listening at http://%s:%s', host, port)
})
}).catch(function(err) {
console.error('Error creating connection pool', err)
});

Then the route uses the connection pool in the app.locals object:

// ./routes/route1.js
const sql = require('mssql');

module.exports = function(req, res) {

req.app.locals.db.query('SELECT TOP 10 * FROM table_name', functio
if (err) {
console.error(err)
res.status(500).send('SERVER ERROR')
return
}
res.status(200).json({ message: 'success' })
https://www.npmjs.com/package/mssql#output-name-type-value 13/63
9/19/23, 11:28 AM mssql - npm

})
}

Advanced Pool Management

For some use-cases you may want to implement your own connection pool management,
rather than using the global connection pool. Reasons for doing this include:

Supporting connections to multiple databases

Creation of separate pools for read vs read/write operations

The following code is an example of a custom connection pool implementation.

// pool-manager.js
const mssql = require('mssql')
const pools = new Map();

module.exports = {
/**
* Get or create a pool. If a pool doesn't exist the config must be
* If the pool does exist the config is ignored (even if it was dif
* when creating the pool)
*
* @param {string} name
* @param {{}} [config]
* @return {Promise.<mssql.ConnectionPool>}
*/
get: (name, config) => {
if (!pools.has(name)) {
if (!config) {
throw new Error('Pool does not exist');
}
const pool = new mssql.ConnectionPool(config);
// automatically remove the pool from the cache if `pool.close()`
const close = pool.close.bind(pool);
pool.close = (...args) => {
pools.delete(name);

https://www.npmjs.com/package/mssql#output-name-type-value 14/63
9/19/23, 11:28 AM mssql - npm

return close(...args);
}
pools.set(name, pool.connect());
}
return pools.get(name);
},
/**
* Closes all the pools and removes them from the store
*
* @return {Promise<mssql.ConnectionPool[]>}
*/
closeAll: () => Promise.all(Array.from(pools.values()).map((connect
return connect.then((pool) => pool.close());
})),
};

This file can then be used in your application to create, fetch, and close pools.

const { get } = require('./pool-manager')

async function example() {

const pool = await get('default')
return pool.request().query('SELECT 1')
}

Similar to the global connection pool, you should aim to only close a pool when you know
it will never be needed by the application again. Typically this will only be when your
application is shutting down.

Result value manipulation

In some instances it is desirable to manipulate the record data as it is returned from the
database, this may be to cast it as a particular object (eg: moment object instead of
Date ) or similar.

In v8.0.0+ it is possible to register per-datatype handlers:

https://www.npmjs.com/package/mssql#output-name-type-value 15/63
9/19/23, 11:28 AM mssql - npm

const sql = require('mssql')

// in this example all integer values will return 1 more than their
sql.valueHandler.set(sql.TYPES.Int, (value) => value + 1)

sql.query('SELECT * FROM [example]').then((result) => {

// all `int` columns will return a manipulated value as per the ca
})

Configuration
The following is an example configuration object:

const config = {
user: '...',
password: '...',
server: 'localhost',
database: '...',
pool: {
max: 10,
min: 0,
idleTimeoutMillis: 30000
}
}

General (same for all drivers)

user - User name to use for authentication.

password - Password to use for authentication.
server - Server to connect to. You can use 'localhost\instance' to connect to named
instance.
port - Port to connect to (default: 1433 ). Don't set when connecting to named
instance.
domain - Once you set domain, driver will connect to SQL Server using domain login.
database - Database to connect to (default: dependent on server configuration).

https://www.npmjs.com/package/mssql#output-name-type-value 16/63
9/19/23, 11:28 AM mssql - npm

connectionTimeout - Connection timeout in ms (default: 15000 ).

requestTimeout - Request timeout in ms (default: 15000 ). NOTE: msnodesqlv8 driver
doesn't support timeouts < 1 second. When passed via connection string, the key must
be request timeout
stream - Stream recordsets/rows instead of returning them all at once as an argument of
callback (default: false ). You can also enable streaming for each request
independently ( request.stream = true ). Always set to true if you plan to
work with large amount of rows.
parseJSON - Parse JSON recordsets to JS objects (default: false ). For more
information please see section JSON support.
pool.max - The maximum number of connections there can be in the pool (default:
10 ).
pool.min - The minimum of connections there can be in the pool (default: 0 ).
pool.idleTimeoutMillis - The Number of milliseconds before closing an unused
connection (default: 30000 ).
arrayRowMode - Return row results as a an array instead of a keyed object. Also adds
columns array. (default: false ) See Handling Duplicate Column Names

Complete list of pool options can be found here.

Formats
In addition to configuration object there is an option to pass config as a connection string.
Connection strings are supported.

Classic Connection String

Standard configuration using tedious driver

Server=localhost,1433;Database=database;User Id=username;Password=pass

Standard configuration using msnodesqlv8 driver

Driver=msnodesqlv8;Server=(local)\INSTANCE;Database=database;UID=DOMAI