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

# JDBC

> Connect Java applications to PgBeam using JDBC, HikariCP, and Spring Boot for connection pooling, caching, and global routing.

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

Connect your Java application to PgBeam by updating the JDBC connection URL. This guide covers plain JDBC, HikariCP connection pooling, and Spring Boot configuration.

## Setup

## Connection pool sizing

PgBeam manages upstream connection pooling, so keep HikariCP's pool small:

Deployment type

Recommended `maximumPoolSize`

Single instance

5-10

Multiple instances behind LB

3-5 per instance

Batch processing

2-5

The default HikariCP pool size is 10, which is already reasonable with PgBeam.
For deployments with many instances, reduce to 3-5 per instance to avoid
hitting PgBeam's connection limit.

## HikariCP recommended settings

## SSL / TLS

The PostgreSQL JDBC driver connects to PgBeam over TLS. PgBeam's certificate is publicly trusted and works with all standard Java TLS configurations.

To explicitly enable SSL:

For Spring Boot:

## Caching

## Automatic caching via cache rules

For JPA/Hibernate queries and Spring Data repositories, PgBeam automatically tracks the generated SQL shapes. Enable caching for specific shapes through Cache Rules in the dashboard, with no code changes needed.

## SQL annotations for fine-grained control

With Spring's `JdbcTemplate`:

## Read replicas

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

See Read Replicas for replica setup and routing details.

## Error handling

JDBC exposes PostgreSQL SQLSTATE codes through `SQLException.getSQLState()`:

See Error Codes for the full reference.

## Migrations

Run migrations directly against your origin database:

Do not run Flyway or Liquibase migrations through PgBeam. Migration tools use
advisory locks and session-level features that should bypass the proxy.

## Debugging

Enable debug mode to see cache and routing details:

To capture NOTICE messages in JDBC, register a `NoticeListener` (pgJDBC) or check your logging framework's PostgreSQL driver output.

## Common issues

Issue

Cause

Fix

"too many connections"

HikariCP pool too large

Reduce `maximumPoolSize` to 3-5

SSL handshake errors

Missing `ssl=true` in URL

Add `?ssl=true&sslmode=require`

Stale data after writes

Cache returning old results

Use `noCache` annotation or adjust TTL

Migrations fail through PgBeam

Advisory locks not supported

Run migrations against origin directly

## Further reading

Connection Pooling: Pool modes, sizing, and lifecycle

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

Error Codes: SQLSTATE reference for PgBeam errors