Fork me on GitHub

Request

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

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 occured, an error object.

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 like object, where the columns can be accessed either by index or name. Columns with a name that is an integer are not accessible by name, as it would be interpreted as an array index.

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.

more

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.

more

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.

more

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

See also Using Parameters.

parameterName

The parameter name. (Does not start with '@'.)

value

The parameter's output value.

metadata

The same data that is exposed in the columnMetadata event.

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');

See also Using Parameters.

name

The parameter name. This should correspond to a parameter in the SQL, or a parameter that a called procedure expects.

The name should not start '@'.

type

One of the supported data types.

value

The value that the parameter is to be given. The Javascript type of the argument should match that documented for data types.

options

Additional type options. Optional.

  • length for VarChar, NVarChar, VarBinary. Use length as Infinity for VarChar(max), NVarChar(max) and VarBinary(max).
  • precision for Numeric, Decimal
  • scale for Numeric, Decimal, Time, DateTime2, DateTimeOffset

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.

See also Using Parameters.

name

The parameter name. This should correspond to a parameter in the SQL, or a parameter that a called procedure expects.

type

One of the supported data types.

value

The value that the parameter is to be given. The Javascript type of the argument should match that documented for data types. Optional.

options

Additional type options. Optional.

  • length for VarChar, NVarChar, VarBinary. Use length as Infinity for VarChar(max), NVarChar(max) and VarBinary(max).
  • precision for Numeric, Decimal
  • scale for Numeric, Decimal, Time, DateTime2, DateTimeOffset

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.