Routing & Regions

How PgBeam routes connections across global regions and caches reads close to the client, and what happens when things fail.

PgBeam is a globally distributed proxy. When a client connects, it is routed to the nearest PgBeam region automatically. From there, PgBeam handles everything: TLS termination, project lookup, connection pooling, caching, and the upstream query.

You do not choose a region when creating a project. Every project is accessible from every region. PgBeam picks the best path to the upstream database for you.

Regions

PgBeam operates in regions worldwide:

Region	Location	Identifier
US East	N. Virginia	`us-east-1`
US West	Oregon	`us-west-2`
EU West	Ireland	`eu-west-1`
Asia South	Mumbai	`ap-south-1`
Southeast Asia	Singapore	`ap-southeast-1`
Northeast Asia	Tokyo	`ap-northeast-1`

All regions are interconnected over a private network. Inter-region traffic never crosses the public internet.

How a connection is routed

Every client connection follows the same lifecycle:

DNS resolution

The client resolves abc.proxy.pgbeam.app. The connection is directed to the nearest PgBeam region automatically, based on the client's location. No application-level routing is involved.

TLS handshake

The client connects over TLS. PgBeam uses SNI (Server Name Indication) to extract the project identifier from the hostname during the TLS handshake, before any PostgreSQL protocol traffic is exchanged.

Project lookup

PgBeam resolves the full project configuration: upstream host, pool mode, cache settings, connection limits, and rate limits. Project configs are cached locally, so this lookup is fast after the first connection.

Cache check (for queries)

When caching is enabled, each incoming query is checked against the local cache before any upstream communication. Cache hits are returned directly, with zero upstream latency.

Pool acquire and upstream auth

PgBeam acquires an upstream connection from the per-project pool (or dials a new one). Your credentials are forwarded to the upstream database for authentication. PgBeam does not store user passwords.

Query execution

The query runs against the upstream database and results flow back to the client. When caching is enabled, eligible read results are stored in the local cache for future requests.

Pool release

When the client disconnects (or the transaction ends, in transaction mode), the upstream connection is reset with DISCARD ALL and returned to the pool.

Routing across regions

When your database is in a different region from the connecting client, PgBeam keeps connection pools close to the database while still serving clients from the nearest region. Clients connect to the region nearest them; PgBeam routes the query to the region nearest your database, where the pool lives.

Keeping pools close to the database has two advantages:

Connection stability. Long-lived upstream connections stay on the shortest, most stable network path to the database.
Pool efficiency. Connections from every region share the same pool, maximizing connection reuse.

Cache and routing interaction

The cache check always happens in the region nearest the client, before any cross-region hop. This is the key performance benefit:

Cache hit: Served from the nearest region. No cross-region hop. No upstream query. The client gets the result with local latency only.
Cache miss: The query is routed to the region nearest the database, executed against the upstream, and the result is cached near the client for future requests.

This means a client in Singapore querying a database in Virginia can get sub-millisecond response times for cached queries, despite the database being halfway around the world.

Failover

If the path to the database's region is unavailable (network partition, region outage), PgBeam falls back to connecting to the upstream database directly from the client's region. This is less efficient (no pool sharing across regions) but maintains connectivity.

Failover is automatic. Your application does not need to handle it: the connection works transparently either way.

Read replica routing

PgBeam supports two modes for routing queries to read replicas:

Per-query annotations (default)

Annotate queries with /* @pgbeam:replica */ to send them to a replica:

/* @pgbeam:replica */ SELECT * FROM products WHERE active = true;

Auto read routing

When enabled on a database with replicas configured, PgBeam automatically routes all SELECT queries to replicas without requiring annotations. Enable it per database in the dashboard, API, or CLI.

Query type	Annotation mode	Auto read routing mode
Read with `@pgbeam:replica`	Round-robin across replicas	Round-robin across replicas
Read without annotation	Primary database	Round-robin across replicas
Write (`INSERT`/`UPDATE`/`DELETE`)	Primary database	Primary database
Inside transaction	Primary database	Primary database

PgBeam strips annotations before forwarding. See Read Replicas for setup instructions, ORM examples, and health check details.

Latency characteristics

Understanding where latency comes from helps you optimize your setup:

Scenario	Typical latency	What determines it
Cache hit near client	< 1ms	L1/L2 cache lookup
Cache miss, database in same region	1-5ms	Upstream query time
Cache miss, database in another region	30-150ms	Inter-region RTT + query
Cold start (project was parked)	Varies	Pool re-init + first dial

The biggest latency win comes from caching. A cache hit eliminates both the upstream query and any cross-region hop.

Failure scenarios

Failure	PgBeam behavior
A PgBeam region goes down	Clients are automatically routed to the next nearest region
Path to the database's region fails	Fallback to a direct connection from the client's region
Upstream database unreachable	Circuit breaker opens after 3 failures
Shared cache goes down	Queries fall through to upstream (fail-open)
All replicas unhealthy	Replica-annotated queries fall back to primary

See Resilience for detailed circuit breaker behavior and recovery.