tedious 20.x

Complete instructions

Verified against tedious@20.0.0 on 2026-09-08. 3 of 3 examples executed.

tedious ^20.0.0

Runtime and package boundary

• Version 20 requires Node.js >=22. Node.js 18, 20, and 21 are not supported.
• Install with npm install tedious.
• This is a Node.js library implementing the TDS protocol for Microsoft SQL Server. It does not provide a CLI or test runner.
• The package exports Connection, Request, TYPES, ISOLATION_LEVEL, and connect.
• Tedious does not provide connection pooling. Use tedious-connection-pool when pooling is required.
• The package's normal runtime entry points are its generated lib/tedious.js and lib/tedious.d.ts files.

Imports

Use the package exports directly:

const { Connection, Request, TYPES, ISOLATION_LEVEL, connect } = require('tedious');

The older individual-property style is also valid:

const Connection = require('tedious').Connection;
const Request = require('tedious').Request;
const TYPES = require('tedious').TYPES;

Do not assume that a test runner supplies describe, it, or expect; Tedious is a library, not a runner.

Constructing and opening a connection

A connection is constructed with a configuration object containing the server, options, and authentication settings. Calling connect starts the connection attempt:

const { Connection } = require('tedious');

const config = {
  server: '192.168.1.210',
  options: {},
  authentication: {
    type: 'default',
    options: { userName: 'test', password: 'test' }
  }
};

const connection = new Connection(config);
connection.on('connect', (err) => {
  if (err) console.error('Error:', err);
});
connection.connect();

connect(callback) is also available. The connection-related examples in this skill only construct objects or exercise local request setup; actually calling connect or executing SQL requires a reachable SQL Server and credentials.

Requests

Create a request with SQL text and a completion callback. Add input parameters with addParameter; output parameters use addOutputParameter. A request can also be paused, resumed, timed out, or cancelled.

import assert from 'node:assert/strict';
import { Request, TYPES } from 'tedious';

const request = new Request('select @city', (err, rowCount) => {
  assert.equal(err, null);
  assert.equal(rowCount, 1);
});

request.addParameter('city', TYPES.VarChar, 'London');
assert.equal(typeof request.pause, 'function');
assert.equal(typeof request.resume, 'function');
assert.equal(typeof request.setTimeout, 'function');
assert.equal(typeof request.cancel, 'function');

Attach a row listener to receive result columns when the request is executed:

const request = new Request("select 42, 'hello world'", function (err, rowCount) {
  if (err) console.error(err);
});

request.on('row', function (columns) {
  columns.forEach(function (column) {
    console.log(column.value);
  });
});

connection.execSql(request);

The connection methods for request execution are execSql(request), execSqlBatch(request), callProcedure(request), and execute(request, parameters). prepare(request) and unprepare(request) are also available.

Important sequencing rule: only one request may be active on a connection at a time. Do not start another request until the previous request's completion callback has run.

Data types

Use members of TYPES when adding request or bulk-load columns. The documented type set includes:

TinyInt, Bit, SmallInt, Int, SmallDateTime, Real, Money, DateTime, Float, Decimal, Numeric, SmallMoney, BigInt, Image, Text, UniqueIdentifier, NText, VarBinary, VarChar, Binary, Char, NVarChar, NChar, Xml, Time, Date, DateTime2, DateTimeOffset, UDT, TVP, and Variant.

import assert from 'node:assert/strict';
import { TYPES } from 'tedious';

assert.equal(typeof TYPES.Int, 'object');
assert.equal(typeof TYPES.VarChar, 'object');
assert.equal(typeof TYPES.NVarChar, 'object');
assert.equal(typeof TYPES.DateTime2, 'object');
assert.equal(typeof TYPES.TVP, 'object');

Transactions

Connection provides beginTransaction(callback, [name], [isolationLevel]), commitTransaction(callback), rollbackTransaction(callback, [name]), and transaction(callback). ISOLATION_LEVEL is exported for transaction isolation settings.

Do not begin a transaction or execute SQL until the connection is established, and continue to obey the one-active-request rule.

Bulk loads

Create a bulk-load operation with newBulkLoad(tableName, options, callback), define columns with addColumn, and submit rows with execBulkLoad(bulkLoad, rows).

import assert from 'node:assert/strict';
import { Connection, TYPES } from 'tedious';

const connection = new Connection({
  server: 'localhost',
  options: {},
  authentication: {
    type: 'default',
    options: { userName: 'user', password: 'password' }
  }
});

const bulkLoad = connection.newBulkLoad('MyTable', { keepNulls: true }, (error, rowCount) => {});
bulkLoad.addColumn('myInt', TYPES.Int, { nullable: false });
bulkLoad.addColumn('myString', TYPES.NVarChar, { length: 50, nullable: true });

assert.equal(typeof bulkLoad.getTableCreationSql(), 'string');
assert.equal(typeof bulkLoad.setTimeout, 'function');
assert.equal(typeof bulkLoad.cancel, 'function');

When a live connection is available, submit rows like this:

connection.execBulkLoad(bulkLoad, [
  { myInt: 7, myString: 'hello' },
  { myInt: 23, myString: 'world' }
]);

The bulk-load completion callback receives an error and row count. Bulk loads can also be timed out or cancelled.

Common mistakes

• Running v20 on Node.js 18, 20, or 21. Upgrade to Node.js 22 or newer.
• Copying an older example that assumes Tedious supplies pooling. It does not.
• Starting a second request before the first request's completion callback runs.
• Treating Request as a promise or assuming SQL execution happens during construction. Construct it, then pass it to a connection method.
• Forgetting to add parameters with the appropriate TYPES member.
• Calling connection or bulk-load execution APIs in a standalone example without a reachable SQL Server. These operations require a real server and credentials.
• Treating repository commands such as build, docs, or tests as runtime requirements. They are development scripts, not a package-owned CLI.

Not covered

This skill does not specify SQL Server connection options beyond the documented example, authentication variants, the behavior of individual SQL data types, stored-procedure parameter details, error-event inventories, pooling APIs, or deployment/network configuration. It also does not provide a live database integration test; those behaviors require SQL Server, valid credentials, and a configured environment.