---
title: "pgx"
description: "Connect Go applications using pgx to PgBeam for connection pooling, caching, and global routing."
canonical: "https://pgbeam.com/docs/pgx"
last-updated: "2026-09-14T19:37:21.000Z"
---

# pgx

> Connect Go applications using pgx to PgBeam for connection pooling, caching, and global routing.

URL: https://pgbeam.com/docs/pgx

Connect your Go application to PgBeam by updating the connection string. pgx is the most widely used PostgreSQL driver for Go and works with PgBeam without any code changes.

## Setup

## Set the connection string

## Connect with pgxpool

## Reduce pool size

PgBeam handles upstream pooling, so reduce `pgxpool`'s pool:

## Pool sizing

Since PgBeam manages upstream connections, keep your client-side pool small:

Deployment type

Recommended `MaxConns`

Single binary / single pod

5-10

Multiple pods behind LB

3-5 per pod

Short-lived CLI tools

1-2

With PgBeam in transaction pool mode, upstream connections are released after
each transaction. A `MaxConns` of 5 per pod handles high concurrency without
pressuring the upstream database.

## TLS

pgx uses TLS by default when connecting to PgBeam. No additional configuration is needed. PgBeam's `*.proxy.pgbeam.app` certificate is publicly trusted and works with all standard Go TLS configurations.

If you need to verify the TLS connection explicitly:

## Caching

## Automatic caching via cache rules

For standard queries, PgBeam tracks the SQL shapes flowing through your project. Enable caching for specific shapes through Cache Rules in the dashboard. No code changes needed.

## SQL annotations for fine-grained control

Use SQL comments for per-query cache control:

## Read replicas

Route read queries to replicas using the `/* @pgbeam:replica */` annotation:

See Read Replicas for replica setup and health check details.

## Error handling

PgBeam returns standard PostgreSQL SQLSTATE codes. Use `pgconn.PgError` to handle PgBeam-specific errors:

See Error Codes for the full reference.

## Migrations

Run migrations directly against the origin database:

This applies to all migration tools: golang-migrate, goose, atlas, or custom migration scripts.

## Debugging

Enable debug mode to see cache and routing details:

## Common issues

Issue

Cause

Fix

"too many connections"

`MaxConns` too high

Reduce to 3-5 per pod

Prepared statement errors

Using transaction pool mode

Use session pool mode, or avoid `Prepare()`

Connection refused on startup

Cold start after inactivity

Normal: first connection is slower

## Further reading

Connection Pooling: Pool modes, sizing, and lifecycle

Caching: TTL, SWR, cache layers, and cache rules

Error Codes: SQLSTATE reference for PgBeam errors