better-sqlite3

Postconditions — what we check

• Statement.run · run-constraint-error

  error
  WhenStatement.run() is called without a try/catch block and the SQL operation may violate a unique constraint, foreign key, or other database constraint.
  ThrowsSqliteError
  Required handlingWrap Statement.run() in a try/catch block. Check err.code for SQLITE_CONSTRAINT to handle constraint violations gracefully.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• Statement.get · get-execution-error

  warning
  WhenStatement.get() is called without a try/catch block in a context where database errors (locked, constraint) could occur.
  ThrowsSqliteError
  Required handlingWrap Statement.get() in a try/catch block. Handle SqliteError to prevent unhandled crashes on database errors.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Statement.all · all-execution-error

  warning
  WhenStatement.all() is called without a try/catch block in a context where database errors could occur.
  ThrowsSqliteError
  Required handlingWrap Statement.all() in a try/catch block. Handle SqliteError to prevent unhandled crashes on database errors.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Database.exec · exec-no-rollback-error

  error
  WhenDatabase.exec() is called without a try/catch block. If an error occurs mid-execution, prior statements are NOT rolled back.
  ThrowsSqliteError
  Required handlingWrap Database.exec() in a try/catch block. Be aware that partial execution cannot be rolled back — use transactions for atomicity.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• Database.backup · backup-unhandled-rejection

  error
  WhenDatabase.backup() is called without .catch() or await inside try/catch. If the backup fails (directory missing, disk full, database error), the returned Promise is rejected with an Error.
  ThrowsError
  Required handlingAwait db.backup() inside a try/catch block or chain .catch() on the returned Promise. Log or handle the error to prevent silent backup failures in production.
  costhighin proddelayed failureusers seelost datavisibilitysilent
  Sources[1]
• Database.backup · backup-directory-missing

  warning
  WhenDatabase.backup() is called with a destination path whose parent directory does not exist. The backup() method checks directory existence before starting; throws TypeError synchronously then the promise rejects.
  ThrowsTypeError
  Required handlingEnsure the destination directory exists before calling backup(), or wrap in try/catch to handle the TypeError from missing directory. Use fs.mkdirSync(path.dirname(dest), { recursive: true }) before backup.
  costmediumin proddelayed failureusers seelost datavisibilitysilent
  Sources[1]
• Database · database-file-must-exist-error

  error
  Whennew Database(path, { fileMustExist: true }) is called but the database file at the given path does not exist. The constructor throws a SqliteError immediately — no database is created, no fallback occurs.
  ThrowsSqliteError
  Required handlingWrap new Database() in a try/catch when using fileMustExist: true. Catch SqliteError and handle the missing-file case (e.g., log, alert, or gracefully degrade rather than crashing the application).
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Database · database-directory-missing-error

  error
  Whennew Database(path) is called where the parent directory of the path does not exist. The constructor throws a TypeError synchronously: "Cannot open database because the directory does not exist."
  ThrowsTypeError
  Required handlingEnsure the parent directory exists before calling new Database(path). Use fs.mkdirSync(path.dirname(dbPath), { recursive: true }) first, or wrap in try/catch to handle the TypeError.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Database.transaction · transaction-async-function-error

  error
  WhenAn async function is passed to db.transaction(). The transaction wrapper detects a returned Promise and throws TypeError('Transaction function cannot return a promise'). The transaction is rolled back. This is a common mistake when migrating code from async/await patterns to better-sqlite3.
  ThrowsTypeError
  Required handlingOnly pass synchronous functions to db.transaction(). All database operations inside the transaction function must be synchronous better-sqlite3 calls. Do not use async/await, Promises, or any async I/O inside the transaction callback.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• Database.transaction · transaction-inner-exception-rollback

  error
  WhenA function wrapped by db.transaction() throws an exception during execution (e.g., a SqliteError from a constraint violation or a JavaScript error). The transaction is automatically rolled back. If the calling code does not catch the exception, it propagates up and may crash the application.
  ThrowsSqliteError
  Required handlingWrap the invocation of a transaction function in a try/catch block. Even though better-sqlite3 auto-rolls back the transaction, the exception still propagates and must be caught to prevent application crashes. Handle constraint violations (SQLITE_CONSTRAINT) to implement retry or conflict resolution logic.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• Statement.iterate · iterate-deferred-execution-error

  warning
  WhenStatement.iterate() is called and the result is consumed in a for...of loop without a try/catch wrapping the iteration. If the database is locked or the statement fails mid-iteration, an Error is thrown inside the loop and the iterator is closed. The error does NOT appear at the iterate() call site.
  ThrowsSqliteError
  Required handlingWrap the for...of loop consuming the iterator in a try/catch block, NOT just the iterate() call site. The error surface is deferred to iteration time, so catching at the call site is insufficient. Example: try { for (const row of stmt.iterate()) { ... } } catch (err) { ... }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]

Sources

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

1. [1]raw.githubusercontent.com/WiseLibs/better-sqlite3https://raw.githubusercontent.com/WiseLibs/better-sqlite3/master/docs/api.md