db-timeout

Statement timeout

shipped

The sections below are generated from the CLI (methodology 0.3-draft, CLI 0.3.0); the same text is printed by sealmark explain db-timeout.

pack: db
weight: scored
scope: server
decided by: response
since: 0.2-draft (methodology 0.3-draft)
replaces: cap-timeout (retired id)
config keys: checks.db-timeout.enabledchecks.db-timeout.expected_secchecks.db-timeout.severitychecks.db-timeout.slow_sqltimeout_probe_sec

Probes

pg-sleep SELECT pg_sleep(<expected_sec + 20>)
cross-join SELECT count(*) FROM big_table a CROSS JOIN big_table b WHERE a.id + b.id = -1

Settings and thresholds

Every check also takes checks.db-timeout.enabled and checks.db-timeout.severity; they are described once in the configuration reference.

Threshold	Default	Set with	Standard
`expected_sec`	`10`	`checks.db-timeout.expected_sec`	locked

Key	Default	Standard	Meaning
`checks.db-timeout.expected_sec`	none	locked	Seconds a runaway query may run before db-timeout fails. null uses timeout_probe_sec.
`checks.db-timeout.slow_sql`	none	locked	A SELECT that runs for a long time, used instead of pg_sleep when a server refuses pg_sleep. Must be a SELECT. null keeps the built-in probe.
`timeout_probe_sec`	`10`	locked	Seconds the cap and timeout probes wait before a call counts as running too long (flag --timeout-probe).

How the verdict is established

Scoring. scored: pass = 1 point, part = 0.5, fail = 0. A fail lowers the pack's percentage but never caps the letter.

What to fix

Set a statement timeout on the connection or role (statement_timeout in Postgres) shorter than the harness waits, so runaway queries are cancelled rather than left running.

False positives

A statement that ends in under one second was refused or never ran, not cancelled: it is reported as refused before execution and the CPU-bound fallback is tried. If both are refused the check is not measured, never failed.

False negatives

The harness waits expected_sec + 8 seconds, so a timeout longer than that is reported as no timeout.