Request

A Request instance represents a request that can be executed on a connection.

new Request(sql, callback)
Event: 'columnMetadata'
Event: 'prepared'
Event: 'error'
Event: 'requestCompleted'
Event: 'row'
Event: 'done'
Event: 'doneInProc'
Event: 'doneProc'
Event: 'returnValue'
Event: 'order'
request.addParameter(name, type, value, [options])
request.addOutputParameter(name, type, [value], [options])
request.pause()
request.resume()
request.setTimeout(timeout)

new Request(sql, callback)

var Request = require('tedious').Request;

request = new Request("select 42, 'hello world'", function(err, rowCount) {
  ...
});
connection.execSql(request);

sql

The SQL statement to be executed (or a procedure name, if the request is to be used with connection.callProcedure).

callback

function (err, rowCount, rows) { }

The callback is called when the request has completed, either successfully or with an error. If an error occurs during execution of the statement(s), then err will describe the error.

As only one request at a time may be executed on a connection, another request should not be initiated until this callback is called.

This callback is called before requestCompleted event is emitted.

err

If an error occurs, an aggregate error object will be returned, and it needs to be logged as an array of messages. Be careful to check the size of the error message array before logging it as an array

err.errors.map (error=>console.log('Error: ', err))

rowCount

The number of rows emitted as result of executing the SQL statement.

rows

Rows as a result of executing the SQL statement.

Will only be avaiable if Connection's config.options.rowCollectionOnRequestCompletion is true.

Event: columnMetadata

request.on('columnMetadata', function (columns) { });

This event, describing result set columns, will be emitted before row events are emitted. This event may be emited multiple times when more than one recordset is produced by the statement.

columns

An array or object (depends on config.options.useColumnNames), where the columns can be accessed by index/name.

Each column has these properties.

colName: The column's name.
type.name: The column's type, such as VarChar, Int or Binary.
precision: The precision. Only applicable to numeric and decimal.
scale: The scale. Only applicable to numeric, decimal, time, datetime2 and datetimeoffset.
dataLength: The length, for char, varchar, nvarchar and varbinary.

Event: prepared

request.on('prepared', function () { });

The request has been prepared and can be used in subsequent calls to execute and unprepare.

Event: error

request.on('error', function (err) { });

The request encountered an error and has not been prepared.

Event: requestCompleted

request.on('requestCompleted', function () { });

This is the final event emitted by a request. This is emitted after the callback passed in a request is called.

Event: row

request.on('row', function (columns) { });

A row resulting from execution of the SQL statement.

columns

An array or object (depends on config.options.useColumnNames), where the columns can be accessed by index/name. Each column has two properties, metadata and value.

metadata

The same data that is exposed in the columnMetadata event.

value

The column's value. It will be null for a NULL.

If there are multiple columns with the same name, then this will be an array of the values.

Event: done

request.on('done', function (rowCount, more, rows) { });

All rows from a result set have been provided (through row events). This token is used to indicate the completion of a SQL statement. As multiple SQL statements can be sent to the server in a single SQL batch, multiple done events can be generated. An done event is emited for each SQL statement in the SQL batch except variable declarations. For execution of SQL statements within stored procedures, doneProc and doneInProc events are used in place of done events.

If you are using execSql then SQL server may treat the multiple calls with the same query as a stored procedure. When this occurs, the doneProc or doneInProc events may be emitted instead. You must handle both events to ensure complete coverage.

rowCount

The number of result rows. May be undefined if not available.

If there are more results to come (probably because multiple statements are being executed), then true.

rows

Rows as a result of executing the SQL statement.

Will only be avaiable if Connection's config.options.rowCollectionOnDone is true.

Event: doneInProc

request.on('doneInProc', function (rowCount, more, rows) { });

Indicates the completion status of a SQL statement within a stored procedure. All rows from a statement in a stored procedure have been provided (through row events).

This event may also occur when executing multiple calls with the same query using execSql.

rowCount

The number of result rows. May be undefined if not available.

If there are more result sets to come, then true.

rows

Rows as a result of executing the SQL.

Will only be avaiable if Connection's config.options.rowCollectionOnDone is true.

Event: doneProc

request.on('doneProc', function (rowCount, more, returnStatus, rows) { });

Indicates the completion status of a stored procedure. This is also generated for stored procedures executed through SQL statements.

This event may also occur when executing multiple calls with the same query using execSql.

rowCount

The number of result rows. May be undefined if not available.

If there are more result sets to come, then true.

returnStatus

The value returned from a stored procedure.

rows

Rows as a result of executing the SQL.

Will only be avaiable if Connection's config.options.rowCollectionOnDone is true.

Event: returnValue

request.on('returnValue', function (parameterName, value, metadata) { });

A value for an output parameter (that was added to the request with addOutputParameter(...)).

Event: order

request.on('order', function (orderColumns) { });

This event gives the columns by which data is ordered, if ORDER BY clause is executed in SQL Server.

orderColumns

An array of column numbers in the result set by which data is ordered.

request.addParameter(name, type, value, [options])

Add an input parameter to the request.

request.addParameter('city', TYPES.VarChar, 'London');

request.addOutputParameter(name, type, [value], [options])

Add an output parameter to the request.

request.addOutputParameter('id', TYPES.Int);

The parameter's value will be provide by an emitted returnValue event.

request.pause()

Temporarily suspends the flow of data from the database. No more 'row' events will be emitted until request.resume() is called.

request.pause();

If this request is already in a paused state, calling pause() has no effect.

request.resume()

Resumes the flow of data from the database.

request.resume();

If this request is not in a paused state, calling resume() has no effect.

request.setTimeout(timeout)

Sets a timeout for this request.

request.setTimeout(timeout);

timeout

The number of milliseconds before the request is considered failed, or 0 for no timeout.

When no timeout is set for the request, the options.requestTimeout of the Connection is used.