knex

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]

Sources

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

1. [1]knexjs.org/guide/query-builder.htmlhttps://knexjs.org/guide/query-builder.html
2. [2]knexjs.org/guide/query-builder.htmlhttps://knexjs.org/guide/query-builder.html#insert
3. [3]knexjs.org/guide/query-builder.htmlhttps://knexjs.org/guide/query-builder.html#update
4. [4]knexjs.org/guide/query-builder.htmlhttps://knexjs.org/guide/query-builder.html#del-delete
5. [5]knexjs.org/guide/query-builder.htmlhttps://knexjs.org/guide/query-builder.html#first
6. [6]knexjs.org/guide/raw.htmlhttps://knexjs.org/guide/raw.html
7. [7]knexjs.org/guide/raw.htmlhttps://knexjs.org/guide/raw.html#sql-injection
8. [8]knexjs.org/guidehttps://knexjs.org/guide/#destroy
9. [9]knexjs.org/guide/utility.htmlhttps://knexjs.org/guide/utility.html#batch-insert
10. [10]knexjs.org/guide/migrations.htmlhttps://knexjs.org/guide/migrations.html
11. [11]knexjs.org/guide/transactions.htmlhttps://knexjs.org/guide/transactions.html
12. [12]github.com/knex/knexhttps://github.com/knex/knex/blob/master/lib/query/querybuilder.js#L1111-L1121
13. [13]github.com/knex/knexhttps://github.com/knex/knex/blob/master/lib/query/querybuilder.js#L1640
14. [14]github.com/knex/knexhttps://github.com/knex/knex/blob/master/lib/query/querybuilder.js#L1124-L1134
15. [15]github.com/knex/knexhttps://github.com/knex/knex/blob/master/lib/knex-builder/make-knex.js#L156-L164
16. [16]knexjs.org/guide/schema-builder.htmlhttps://knexjs.org/guide/schema-builder.html
17. [17]github.com/knex/knexhttps://github.com/knex/knex/blob/master/lib/schema/builder.js#L46-L88