How to Set connection timeout in PostgreSQL

How do I set and tune connect_timeout in PostgreSQL?

connect_timeout defines how long ParadeDB/PostgreSQL will wait when opening a new client connection before aborting.

Welcome to the Galaxy, Guardian!

Oops! Something went wrong while submitting the form.

Description

What does the connection timeout parameter do?

connect_timeout (seconds) tells ParadeDB/PostgreSQL how long to attempt a TCP handshake and authentication before giving up. A low value fails fast; a high value tolerates slow networks.

How do I set connect_timeout in a libpq connection string?

Add connect_timeout=<seconds> to any libpq-style URI or keyword/value string. Example:

psql "host=db.prod port=5432 dbname=shop user=app connect_timeout=5"

Can I set connect_timeout in psql flags?

Yes.Use -d or -h/-p flags together with the parameter:

psql -h db.prod -p 5432 -U app -d shop "connect_timeout=5"

When should I change the timeout?

Increase the value for cross-region traffic, overloaded servers, or VPN links. Decrease it inside low-latency data centers to fail over quickly.

What is the default value?

If omitted, libpq waits 15 seconds (psql) or the driver default. ParadeDB inherits this from PostgreSQL.

Does connect_timeout affect running queries?

No. It influences only the initial handshake.Query execution timeouts use statement_timeout.

Best practices for ParadeDB in production

• Document the chosen timeout in infrastructure code.
• Keep it under your load-balancer health-check interval.
• Monitor failed logins for spikes indicating an overly low value.

Complete example: Node.js pg client

const { Pool } = require('pg'); const pool = new Pool({ connectionString: 'postgres://app:@db.prod:5432/shop', connectionTimeoutMillis: 5000, // 5 seconds });

How do I test my setting?

Block the port with a firewall rule and run your client; it should error in ≈timeout seconds.

Why How to Set connection timeout in PostgreSQL is important

How to Set connection timeout in PostgreSQL Example Usage


-- Connect with a 3-second timeout and fetch today’s orders
psql "host=10.0.1.5 port=5432 dbname=ecommerce user=reporter connect_timeout=3" -c \
  "SELECT o.id, c.name, o.total_amount
   FROM Orders o
   JOIN Customers c ON c.id = o.customer_id
   WHERE o.order_date = CURRENT_DATE;"

How to Set connection timeout in PostgreSQL Syntax


psql "host=<hostname> port=<port> dbname=<database> user=<user> connect_timeout=<seconds>"

psql postgresql://<user>@<host>:<port>/<database>?connect_timeout=<seconds>

libpq keyword/value string:
  host=<hostname> port=<port> dbname=<database> user=<user> connect_timeout=<seconds>

Example with ecommerce schema:
psql "host=10.0.1.5 port=5432 dbname=ecommerce user=reporter connect_timeout=3"

Common Mistakes

Mistake: Raising connect_timeout to several minutes. Why wrong: masks network failures and slows failover. Fix: keep it below 10–15 s and rely on retries.
Mistake: Assuming connect_timeout controls query runtime. Why wrong: it only covers initial handshake. Fix: use statement_timeout for query limits.