feat(settings): time out opening a database connection

[bryangingechen]

Motivation

Opening a database connection had no time limit of its own, so psycopg used its built-in default of 130 s. Against a Postgres that accepts the TCP connection and then never answers, a request waited past gunicorn's 120 s worker timeout and ended with the worker killed rather than an error. The health endpoint's notes recorded this gap. Celery tasks waited the same way.

What changes

• DJANGO_DB_CONNECT_TIMEOUT, wired through base.py and .env.example, sets libpq's connect_timeout in DATABASES["default"]["OPTIONS"]. It applies to each address the host name resolves to.
  • Default 10 s.
  • Accepts 2 to 600. psycopg turns anything below 2 into 2, and 0 or less into its own 130 s, so those values refuse to start instead of quietly meaning something else.
  • Blank or unset means the default, as an env file copied from .env.example may have it.
  • It is always passed, so libpq's PGCONNECT_TIMEOUT no longer has any effect. Nothing in the repo used it.
• Docs: docs/production_image.md (Configuration, and the /api/health bullet: against a database that doesn't answer, the 503 comes after about the timeout, so a probe with a shorter timeout times out instead, and fails either way). The health endpoint's notes in qb_site/api/AGENTS.md and health.py now name the setting instead of describing the gap.

User-visible effects

None while the database answers. When it hangs, requests and tasks fail after about 10 s instead of 130 s. No migrations.

Testing

• core.tests.test_db_connect_timeout (5 tests):
  • default 10 for unset, empty and blank;
  • set values are used;
  • 0, 1, -5, 601, ten and 2.5 refuse to start, with the setting's name in the error;
  • the active settings carry the value in OPTIONS, and Django's own connection parameters, built from them, pass it to psycopg;
  • against a listening socket that never answers, Django's own connection code, with the configured OPTIONS and a 2 s timeout, raises OperationalError after about 2 s, where it would otherwise wait for psycopg's 130 s.
• uv run ruff check ., uv run ruff format --check .
• Review (a separate agent) checked that Django 5.2.6 and 6.1.2 both pass OPTIONS through, and that psycopg 3.2.10 and 3.3.6 both apply the timeout per attempt, with the same 2 s floor and 130 s fallback. The review fixes are in 8eede328. Left for a follow-up: a server that freezes after connecting still holds a request until gunicorn's timeout. TCP keepalives or tcp_user_timeout would cover that.
• bash scripts/repo_check_compose.sh: all 13 steps passed locally (core 119, syncer 543, analyzer 606, api 28, zulip_bot 350, console 96, site_analytics 81 tests). Compose's .env from .env.example sets the new value, and every service connects with it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QoXLf4KSfqzMFrdZGQG9Up