tedious

Postconditions — what we check

• connect · connection-failure

  error
  WhenCannot connect (wrong credentials, server unreachable, etc.)
  ThrowsConnectionError event with details
  Required handlingCaller MUST handle 'error' event on Connection. Common error codes: - ESOCKET: Network/socket error - ELOGIN: Authentication failed - ETIMEOUT: Connection timeout Implement retry with exponential backoff for transient issues.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• execSql · syntax-error

  error
  WhenSQL syntax error
  ThrowsError event on Request with error.number indicating syntax error
  Required handlingCaller MUST handle 'error' event on Request. SQL Server error numbers: - 102, 156: Syntax errors - 207: Invalid column name - 208: Invalid object name (table not found) DO NOT retry - fix SQL syntax.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• execSql · constraint-violation

  error
  WhenUnique constraint, foreign key, or NOT NULL violation
  ThrowsError event with error.number for constraint violations
  Required handlingCaller MUST handle constraint violations: - 2627: Unique constraint violation - 547: Foreign key constraint violation - 515: NOT NULL constraint violation Extract details from error.message. DO NOT retry without fixing data.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• execSql · connection-error

  error
  WhenConnection lost during query execution
  ThrowsError event with connection-related error codes
  Required handlingCaller MUST handle connection errors. Connection may be lost due to timeout or server restart. Implement retry with exponential backoff.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• execSql · deadlock

  error
  WhenTransaction deadlock detected
  ThrowsError event with error.number = 1205
  Required handlingCaller MUST handle deadlock errors. Deadlocks are transient - implement retry logic. SQL Server automatically rolls back deadlocked transaction. Consider transaction isolation level and lock hints to reduce deadlocks.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• execSql · timeout

  error
  WhenQuery execution timeout exceeded
  ThrowsError event with ETIMEOUT code
  Required handlingCaller MUST handle timeout errors. Query took longer than request timeout setting. Consider optimizing query or increasing timeout.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• callProcedure · procedure-error

  error
  WhenStored procedure raises error or does not exist
  ThrowsError event on Request with SQL Server error number
  Required handlingCaller MUST handle 'error' event on Request. Error numbers: - 2812: Procedure not found - Application errors: RAISERROR in procedure Check error.number and error.message for details.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• callProcedure · connection-error

  error
  WhenConnection lost during procedure call
  ThrowsError event with connection-related error codes
  Required handlingCaller MUST handle connection errors. Implement retry with exponential backoff for transient issues.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• beginTransaction · transaction-start-error

  error
  WhenCannot start transaction due to connection issues
  ThrowsError event on Connection with transaction error details
  Required handlingCaller MUST handle 'error' event on Connection. Connection must be in LoggedIn state to begin transaction. Ensure no other transaction is active on connection.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• beginTransaction · nested-transaction-error

  error
  WhenAttempting to begin transaction when one is already active
  ThrowsError event indicating transaction already in progress
  Required handlingCaller MUST track transaction state. SQL Server supports nested transactions via SAVE TRANSACTION. Consider using savepoints for nested logic.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• commitTransaction · commit-error

  error
  WhenCannot commit transaction (constraint violation, business rule failure)
  ThrowsError event on Connection with commit failure details
  Required handlingCaller MUST handle 'error' event on Connection. Commit can fail if deferred constraints are violated. Transaction will be rolled back automatically on commit failure.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• commitTransaction · no-active-transaction

  error
  WhenAttempting to commit when no transaction is active
  ThrowsError event indicating no transaction to commit
  Required handlingCaller MUST track transaction state. Ensure beginTransaction was called and no prior rollback occurred.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• rollbackTransaction · rollback-error

  error
  WhenCannot rollback transaction (connection lost)
  ThrowsError event on Connection with rollback failure details
  Required handlingCaller MUST handle 'error' event on Connection. Rollback rarely fails; if it does, connection may be unusable. Consider closing and reopening connection after rollback failure.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• rollbackTransaction · no-active-transaction

  error
  WhenAttempting to rollback when no transaction is active
  ThrowsError event indicating no transaction to rollback
  Required handlingCaller MUST track transaction state. Ensure beginTransaction was called.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• prepare · prepare-error

  error
  WhenSQL syntax error or invalid statement
  ThrowsError event on Request with SQL Server error details
  Required handlingCaller MUST handle 'error' event on Request. Prepare validates SQL syntax before execution. Error numbers same as execSql (102, 156, 207, 208).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• unprepare · unprepare-error

  error
  WhenCannot unprepare statement (connection lost, invalid handle)
  ThrowsError event on Request with error details
  Required handlingCaller MUST handle 'error' event on Request. Unprepare should always be called to free server resources.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• execute · execute-parameter-validation-error

  error
  WhenParameter value type does not match the declared parameter type (e.g., passing a string where an Int parameter is expected). Validation runs synchronously in execute() via DataType.validate() before any network call.
  ThrowsRequestError delivered to Request callback (code: undefined)
  Required handlingCaller MUST handle 'error' event on the Request object. Parameter type mismatches are caught before the request is sent to SQL Server. Validate parameter types before calling execute(). The same error handler used for prepare()/unprepare() MUST also cover execute().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• execute · execute-invalid-state-error

  error
  Whenexecute() is called while the connection is not in LOGGED_IN state — e.g., a prior request is still in-flight, or the connection is closing. SQL Server allows only one request at a time per connection.
  ThrowsRequestError with code 'EINVALIDSTATE' delivered to Request callback
  Required handlingCaller MUST wait for the previous request's callback before calling execute(). Only one request at a time per Connection is allowed. Use connection pooling (e.g., mssql) to run concurrent queries. Always handle the 'error' event.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][6]
• execBulkLoad · bulk-load-constraint-violation

  error
  WhenBulk insert violates a table constraint — e.g., unique key violation (error 2627), foreign key constraint (error 547), NOT NULL constraint (error 515) — when checkConstraints is enabled in BulkLoad options. Without checkConstraints, SQL Server may bypass constraint checks, causing silent data corruption.
  ThrowsError delivered to BulkLoad callback (err.number = 2627 | 547 | 515)
  Required handlingCaller MUST handle error in the BulkLoad callback: newBulkLoad(table, options, (err, rowCount) => { if (err) { /* handle constraint violation */ } }). Consider enabling checkConstraints: true option to catch violations during insert. Log rowCount on success to confirm all rows were inserted.
  costhighin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[7][3]
• execBulkLoad · bulk-load-column-definition-mismatch

  error
  WhenColumn definitions added via bulkLoad.addColumn() do not match the actual table schema (wrong data type, wrong nullable flag, or column doesn't exist). This causes the bulk insert to fail. Attempting to call addColumn() after rows have already been written throws synchronously: "Columns cannot be added to bulk insert after the first row has been written."
  ThrowsError thrown synchronously from addColumn() OR Error delivered to BulkLoad callback
  Required handlingCall addColumn() for ALL columns before writing any rows. Verify column definitions against the live table schema before performing bulk load operations. Always handle the BulkLoad callback for schema errors that surface at insert time.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• execBulkLoad · bulk-load-timeout

  error
  WhenBulk load exceeds the timeout configured via bulkLoad.setTimeout() or the connection's requestTimeout. Large datasets or slow networks can exceed the timeout, resulting in the bulk load being considered failed.
  ThrowsRequestError with code 'ETIMEOUT' delivered to BulkLoad callback
  Required handlingSet an appropriate timeout with bulkLoad.setTimeout(ms) for large bulk operations. Default is the Connection's requestTimeout (default: 15000ms). For large datasets, use setTimeout(0) for no timeout or increase it explicitly. Handle ETIMEOUT in the callback and implement retry logic for transient failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][1]
• saveTransaction · save-transaction-state-error

  error
  WhensaveTransaction() is called when no active transaction exists, or the connection is not in LOGGED_IN state (e.g., a prior request is still pending, connection is closing). SQL Server requires an active transaction for savepoints.
  ThrowsRequestError with code 'EINVALIDSTATE' delivered to saveTransaction callback
  Required handlingCaller MUST check that beginTransaction() has been called before saveTransaction(). Wait for each request's callback to complete before issuing the next request. Always handle the err argument in the saveTransaction callback.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• saveTransaction · save-transaction-connection-error

  error
  WhenConnection is lost while setting the savepoint. Network failure or server restart during the TRANSACTION_MANAGER request causes an error in the callback.
  ThrowsConnectionError delivered to saveTransaction callback
  Required handlingCaller MUST handle error in the saveTransaction callback. On connection error, the parent transaction state is undefined — roll back and reconnect.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• transaction · transaction-begin-error

  error
  WhenTransaction cannot be started — connection is not in LOGGED_IN state (EINVALIDSTATE), or the connection was lost before beginTransaction completed. The error is delivered to the cb callback: cb(err) with no done argument.
  ThrowsRequestError or ConnectionError delivered to cb(err)
  Required handlingCaller MUST check the err argument in the transaction callback before using done(). If err is set, do NOT call done() — the transaction was never started. Example: connection.transaction((err, done) => { if (err) return handleError(err); ... })
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• transaction · transaction-commit-error

  error
  WhenTransaction commit fails due to deferred constraint violation, connection loss, or server error during COMMIT. The error is delivered through the done() callback: done(err). If the commit fails and the connection is still LOGGED_IN, tedious automatically attempts to rollback before passing the error to done().
  ThrowsRequestError or ConnectionError delivered through done(err)
  Required handlingCaller MUST handle the err argument in the done() callback. On commit error, do NOT retry the transaction without re-starting it from beginTransaction. The automatic rollback in tedious's transaction() helper means the transaction is already rolled back when done(err) is called. Example: done(err) => { if (err) { /* transaction was rolled back */ } }
  costhighin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[1]
• execSqlBatch · exec-sql-batch-invalid-state

  error
  WhenexecSqlBatch() is called while the connection is not in LOGGED_IN state — another request is in-flight, the connection is closing, or was never established. Error message: "Requests can only be made in the LoggedIn state, not the X state."
  ThrowsRequestError with code 'EINVALIDSTATE' delivered to Request callback
  Required handlingCaller MUST wait for the previous request's callback before calling execSqlBatch(). Only one request per connection is allowed at a time. Handle the 'error' event on the Request object.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][6]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]tediousjs.github.io/tedious/api-connection.htmlhttps://tediousjs.github.io/tedious/api-connection.html
2. [2]tediousjs.github.io/tedious/api-request.htmlhttps://tediousjs.github.io/tedious/api-request.html
3. [3]docs.microsoft.com/en-us/sqlhttps://docs.microsoft.com/en-us/sql/relational-databases/errors-events/database-engine-events-and-errors
4. [4]docs.microsoft.com/en-us/sqlhttps://docs.microsoft.com/en-us/sql/relational-databases/sql-server-transaction-locking-and-row-versioning-guide
5. [5]docs.microsoft.com/en-us/sqlhttps://docs.microsoft.com/en-us/sql/t-sql/language-elements/begin-transaction-transact-sql
6. [6]tediousjs.github.io/tedious/frequently-encountered-problems.htmlhttps://tediousjs.github.io/tedious/frequently-encountered-problems.html
7. [7]tediousjs.github.io/tedious/bulk-load.htmlhttps://tediousjs.github.io/tedious/bulk-load.html