Postconditions: what we check

• select · select-query-error

  error
  Whenquery fails (syntax error, connection lost, timeout, invalid table/column)
  ThrowsError with query details and database-specific error code
  Required handlingCaller MUST wrap select() in try-catch to handle SQL errors, connection failures, and timeouts. Query errors crash application if unhandled.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• insert · insert-constraint-violation

  error
  Wheninsert violates constraint (unique, foreign key, not null, type mismatch)
  ThrowsError with constraint violation details and database error code
  Required handlingCaller MUST wrap insert() in try-catch to handle constraint violations. Unique violations, foreign key errors, and type mismatches crash application if unhandled.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• update · update-no-try-catch

  error
  Whenupdate() called in async context without try-catch or .catch() handler
  ThrowsError with database-specific error code and query details
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• update · update-zero-rows-not-checked

  warning
  Whenupdate() result (number of affected rows) is not checked after execution — caller assumes update succeeded when WHERE matched nothing
  Throwsdoes not throw — returns 0 silently
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• delete · delete-no-try-catch

  error
  Whendel()/delete() called in async context without try-catch or .catch() handler
  ThrowsError with database-specific error code; KnexTimeoutError on connection timeout
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• delete · delete-foreign-key-violation

  error
  Whendelete() called on a parent row that has child rows in another table with a foreign key constraint, without CASCADE
  ThrowsError with foreign key constraint violation from database driver
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• first · first-no-try-catch

  error
  Whenfirst() called in async context without try-catch
  ThrowsError with database-specific error code on query failure
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• first · first-undefined-not-checked

  error
  Whenfirst() result used directly without null/undefined check before accessing properties (e.g. result.id, result.name)
  ThrowsTypeError: Cannot read properties of undefined at runtime
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• raw · raw-no-try-catch

  error
  Whenknex.raw() called in async context without try-catch
  ThrowsError with SQL error details from database; or binding Error synchronously on undefined binding
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• raw · raw-sql-injection-risk

  error
  Whenknex.raw() called with user-provided input interpolated directly into the SQL string (template literal or string concatenation) instead of using binding parameters
  Throwsdoes not throw — silently executes malicious SQL
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• destroy · destroy-not-called-on-shutdown

  warning
  Whenknex instance is created but destroy() is never called — process exits (or tries to exit) without closing the connection pool
  Throwsdoes not throw — process hangs indefinitely, never exits
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• destroy · destroy-no-try-catch

  warning
  Whenawait knex.destroy() called without try-catch
  ThrowsError on pool teardown failure (rare but possible on network error)
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• batchInsert · batch-insert-no-try-catch

  error
  WhenbatchInsert() called without try-catch around the await
  ThrowsError on constraint violation or connection failure (same as insert()); TypeError for invalid chunkSize or non-array batch input
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• migrate.latest · migrate-latest-no-try-catch

  error
  Whenawait knex.migrate.latest() called without try-catch in server startup or deployment scripts
  ThrowsLockError if migration table is already locked by another process; Error from migration scripts that throw; KnexTimeoutError on database connection failure
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• migrate.latest · migrate-latest-lock-not-released-on-crash

  error
  WhenProcess crashes during migrate.latest() execution (SIGKILL, OOM, power failure) leaving migration lock in locked state
  ThrowsLockError('Migration table is already locked') on all subsequent migrate.latest() calls
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• migrate.rollback · migrate-rollback-no-try-catch

  error
  Whenawait knex.migrate.rollback() called without try-catch
  ThrowsLockError if migration table is already locked; Error from down() migration scripts that throw; Error if named migration not found
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• transaction · transaction-error

  error
  Whenquery within transaction fails (constraint violation, deadlock, connection lost)
  ThrowsError causing automatic rollback if unhandled
  Required handlingCaller MUST wrap transaction callback in try-catch to handle errors and ensure proper rollback. Unhandled errors may leave database in inconsistent state if transaction partially commits.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11]
• increment · increment-no-try-catch

  error
  Whenincrement() called in async context without try-catch or .catch() handler
  ThrowsError with database-specific error code on connection failure, invalid column name, or type mismatch (e.g. incrementing a non-numeric column); KnexTimeoutError after acquireConnectionTimeout on pool exhaustion
  Required handlingCaller MUST wrap await knex(table).where({...}).increment() in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][12]
• increment · increment-zero-rows-not-checked

  warning
  Whenincrement() result (number of affected rows) is not checked after execution — caller assumes counter was incremented when WHERE matched nothing (row does not exist)
  Throwsdoes not throw — returns 0 silently
  Required handlingCaller SHOULD check the return value of increment(). If the returned count is 0, either the WHERE condition matched nothing or the row was deleted. For counter semantics that require the row to exist, verify count > 0 or use an upsert pattern.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][13]
• decrement · decrement-no-try-catch

  error
  Whendecrement() called in async context without try-catch or .catch() handler
  ThrowsError with database-specific error code on connection failure, invalid column name, or type mismatch; KnexTimeoutError on pool exhaustion
  Required handlingCaller MUST wrap await knex(table).where({...}).decrement() in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][14]
• decrement · decrement-zero-rows-not-checked

  warning
  Whendecrement() result (number of affected rows) is not checked after execution — caller assumes counter was decremented when WHERE matched nothing
  Throwsdoes not throw — returns 0 silently
  Required handlingCaller SHOULD check the returned row count. If 0, the target row was not found. For inventory/seat management, treat 0-row decrement as a precondition failure.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• transactionProvider · transaction-provider-factory-no-try-catch

  error
  Whenawait trxProvider() called without try-catch around the factory invocation
  ThrowsKnexTimeoutError if connection pool is exhausted when the factory is first called; Error on any database-level failure during transaction initialization
  Required handlingCaller MUST wrap await trxProvider() in try-catch, especially in high-concurrency contexts where connection pool exhaustion is possible.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11][15]
• transactionProvider · transaction-provider-connection-not-released

  error
  WhenFactory invocation succeeds but neither trx.commit() nor trx.rollback() is ever called — transaction is left open indefinitely
  Throwsdoes not throw — connection silently hangs
  Required handlingMUST ensure trx.commit() or trx.rollback() is called in all code paths. Use try/finally: const trx = await trxProvider(); try { ...; await trx.commit(); } catch (err) { await trx.rollback(err); throw err; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11][15]
• schema.createTable · schema-create-table-no-try-catch

  error
  Whenawait knex.schema.createTable(...) called without try-catch
  ThrowsError if table already exists (database-native: "relation already exists" in PostgreSQL, "Table already exists" in MySQL/SQLite); Error if the connected user lacks CREATE TABLE privileges; KnexTimeoutError on connection pool exhaustion during DDL
  Required handlingCaller MUST wrap await knex.schema.createTable() in try-catch in migration scripts. In deployment automation, check for "already exists" errors to handle idempotent re-deployments. Use knex migration system (migrate.latest) rather than manually calling createTable() for idempotent DDL management.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16][17]
• schema.dropTable · schema-drop-table-no-try-catch

  error
  Whenawait knex.schema.dropTable(...) called without try-catch
  ThrowsError if table does not exist ("relation does not exist" in PostgreSQL, "Unknown table" in MySQL); Error if FK constraints reference the table from another table without CASCADE ("cannot drop table X because other objects depend on it" in PostgreSQL); Error if user lacks DROP privilege; KnexTimeoutError on pool exhaustion
  Required handlingCaller MUST wrap await knex.schema.dropTable() in try-catch. Prefer dropTableIfExists() for idempotent down() migrations to avoid the "does-not-exist" error on re-runs.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• schema.alterTable · schema-alter-table-no-try-catch

  error
  Whenawait knex.schema.alterTable(...) called without try-catch
  ThrowsError on type-incompatible conversions ("cannot cast type X to type Y" in PostgreSQL, "Incorrect integer value" in MySQL); Error when ADD COLUMN NOT NULL without default is applied to a non-empty table ("column contains null values"); Error on lock timeout when another transaction holds a conflicting lock on the target table (PostgreSQL lock_timeout setting, MySQL lock_wait_timeout); Error on duplicate column name when ADD COLUMN targets an existing column; KnexTimeoutError on pool exhaustion
  Required handlingCaller MUST wrap await knex.schema.alterTable() in try-catch. For production deploys against a live table, set a lock_timeout (PostgreSQL) or innodb_lock_wait_timeout (MySQL) and handle the timeout error explicitly rather than blocking writes indefinitely.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• schema.hasTable · schema-has-table-no-try-catch

  warning
  Whenawait knex.schema.hasTable(...) called without try-catch
  ThrowsKnexTimeoutError on connection pool exhaustion (60s default); Error on connection failure to the database; Error on permission denied if the connected user lacks SELECT on the system catalog
  Required handlingCaller MUST wrap await knex.schema.hasTable() in try-catch in bootstrap and migration code. Treat connection failures as a startup error and surface them before the app starts accepting traffic.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• schema.hasColumn · schema-has-column-no-try-catch

  warning
  Whenawait knex.schema.hasColumn(...) called without try-catch
  ThrowsKnexTimeoutError on pool exhaustion; Error on connection failure; Error on permission denied against the system catalog
  Required handlingCaller MUST wrap await knex.schema.hasColumn() in try-catch in migration guard-code.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• migrate.up · migrate-up-no-try-catch

  error
  Whenawait knex.migrate.up(...) called without try-catch
  ThrowsLockError("Migration table is already locked") if another process holds the lock; Error from the migration script's up() function; Error("Migration X was not found") if config.name references a missing migration; KnexTimeoutError on connection pool exhaustion
  Required handlingCaller MUST wrap await knex.migrate.up() in try-catch in deploy scripts. Distinguish LockError (concurrent deploy — retry/wait) from script errors (genuine migration failure — alert and rollback).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• migrate.down · migrate-down-no-try-catch

  error
  Whenawait knex.migrate.down(...) called without try-catch
  ThrowsLockError("Migration table is already locked"); Error from the migration script's down() function; Error("Migration X was not run") if the specified name refers to a migration that was never applied; KnexTimeoutError on pool exhaustion
  Required handlingCaller MUST wrap await knex.migrate.down() in try-catch. In rollback automation, surface the underlying script error rather than retrying — a failing down() step usually indicates the migration's down() logic is broken or the data has drifted.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• migrate.forceFreeMigrationsLock · migrate-force-free-lock-no-try-catch

  warning
  Whenawait knex.migrate.forceFreeMigrationsLock(...) called without try-catch
  ThrowsError on UPDATE failure against the lock table; KnexTimeoutError on pool exhaustion; Error on permission denied against the migration lock table
  Required handlingCaller MUST wrap await knex.migrate.forceFreeMigrationsLock() in try-catch. Surface failures loudly — a failed unlock means the service cannot recover its ability to migrate.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• migrate.forceFreeMigrationsLock · migrate-force-free-lock-races-active-migration

  error
  WhenforceFreeMigrationsLock() called while another process is actively running a migration (rather than the documented recovery case of a crashed migration)
  Throwsdoes not throw — silently clears the lock and allows a concurrent migration
  Required handlingOperator MUST verify no other migration process is running before calling forceFreeMigrationsLock(). Treat this function as a manual operator tool, never wire it into automated deploy scripts that run unconditionally.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• seed.run · seed-run-no-try-catch

  error
  Whenawait knex.seed.run(...) called without try-catch
  ThrowsError("Invalid seed file: <path> must have a seed function") if a file is missing the seed export; Error("Error while executing \"<path>\" seed: <original-message>") wrapping any error thrown from inside the seed function (including all knex query errors: insert constraint violations, connection failures, KnexTimeoutError); Error if the seed directory does not exist
  Required handlingCaller MUST wrap await knex.seed.run() in try-catch in test setup hooks and bootstrap scripts. Inspect err.original to recover the underlying knex error when reporting failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18]
• seed.run · seed-run-partial-state-on-failure

  warning
  Whenseed.run() throws partway through a multi-file seed sequence without the caller rolling back already-inserted rows or truncating the affected tables
  Throwsdoes not throw — leaves database in partially-seeded state
  Required handlingCaller SHOULD wrap seed.run() in an explicit transaction (or truncate-and-retry on failure) when partial-state recovery matters. At minimum, treat a failed seed.run() as a signal that the database needs cleanup before the next attempt.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[18]
• stream · stream-error-event-not-registered

  error
  Whenknex(...).stream() (or chained .stream()) consumed without registering an 'error' listener on the returned stream (or without try/catch around a for-await-of loop consuming it)
  Throwsdoes not throw from the .stream() call — errors are emitted asynchronously on the stream's 'error' event; an unhandled 'error' event terminates the Node.js process with an uncaught exception
  Required handlingCaller MUST either (1) consume the stream with for-await-of inside try/catch, OR (2) register stream.on('error', handler) before piping, OR (3) use the callback form which returns a Promise that rejects on stream errors. Never .pipe() a knex stream without an 'error' listener.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[19]
• stream · stream-not-destroyed-on-request-abort

  warning
  Whenknex stream piped into an HTTP response is not explicitly destroyed when the HTTP request is aborted by the client
  Throwsdoes not throw — the database connection is held open and remains in the pool as in-use until either query completion or KnexTimeoutError
  Required handlingCaller MUST listen for the HTTP request's 'aborted' / 'close' event and call stream.destroy() to release the pooled connection. The for-await-of consumption form handles this automatically (the docs state: "if the loop terminates with a break, return, or a throw, the stream will be destroyed"). The raw-pipe form does not.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[19]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.