---
title: "Query Timeout"
description: "Set per-database query timeouts to prevent long-running queries from holding connections and exhausting resources."
canonical: "https://pgbeam.com/docs/query-timeout"
last-updated: "2026-10-08T10:00:49.000Z"
---

# Query Timeout

> Set per-database query timeouts to prevent long-running queries from holding connections and exhausting resources.

URL: https://pgbeam.com/docs/query-timeout

Query timeout lets you set a maximum execution time for queries on a per-database basis. When enabled, PgBeam sends `SET statement_timeout = <ms>` to the upstream database after acquiring a connection, ensuring no single query runs longer than the configured limit.

## How it works

The timeout is applied at the database level, not the project level. Each database registered in a project can have its own timeout value.

Setting

Behavior

`0` (default)

Disabled: no timeout override, upstream default applies

`1` to `300000` (ms)

PgBeam sets `statement_timeout` on each upstream connection

When a query exceeds the timeout, PostgreSQL cancels it and returns:

This is a standard PostgreSQL error. Your application handles it the same way regardless of whether PgBeam or a direct connection set the timeout.

## Configure the timeout

Navigate to your project, select a database, and go to **Settings**. Set the
**Query timeout** value in milliseconds.

## Choosing a timeout value

Workload

Suggested timeout

Why

Web app (API responses)

5,000-15,000 ms

Users won't wait longer than a few seconds

Background jobs

60,000-300,000 ms

Longer queries are expected but should still bound

Analytics / reporting

300,000 ms (max)

Complex aggregations need more time

Mixed (OLTP + occasional report)

30,000 ms

Balanced default for most applications

If your application already sets `statement_timeout` in its connection
initialization, PgBeam's setting will override it for the duration of the
pooled connection. The application-level timeout is restored when the
connection is returned to the pool and reset with `DISCARD ALL`.

## Interaction with connection pooling

In **transaction mode**, `statement_timeout` is set each time PgBeam acquires an upstream connection for a client. When the transaction ends and the connection is returned to the pool, `DISCARD ALL` resets it.

In **session mode**, the timeout is set once when the upstream connection is first established for the client session.

## Further reading

Connection Pooling: Pool modes and connection lifecycle

Error Codes: SQLSTATE reference

Troubleshooting: Debug slow queries