[vincentsarago]

Stacked on #307.

Why

A single expensive DuckDB query (e.g. a low zoom tile over a large, unsorted remote GeoParquet file) can keep a worker busy for minutes: a z5 tile over a 2.3M-polygon remote file read the whole ~870 MB file and took ~55s.

What

• New query_timeout setting (TIPG_DUCKDB_QUERY_TIMEOUT, seconds) in DuckDBCatalogSettings. Disabled by default.
• Items queries (including the numberMatched COUNT(*)) and tiles queries still running after the timeout are interrupted with cursor.interrupt().
• Interrupted queries raise a new QueryTimeout error, mapped to 504 Gateway Timeout in DEFAULT_STATUS_CODES.
• Documented in docs/src/advanced/duckdb.md (settings table and the low zoom levels section).

On DuckDB 2.0, an interrupt stops the query within ~0.3s. The cursor and the connection are still usable after it, and interrupting a cursor whose query already finished doesn't affect its next queries.

Not covered

• Catalog building (GeoParquet footer reads) has no timeout.
• PostgreSQL backend is unchanged.

Tests

tests/duck/test_timeout.py uses a view over 10¹¹ rows with a 0.5s timeout:

• Items and tiles queries are interrupted, and the connection stays usable.
• Queries finishing before the timeout are not affected, including after a stale timer fires.
• No timeout by default.
• Both endpoints return a 504 over HTTP.

Full test suite passes locally (145 tests).

🤖 Generated with Claude Code