Reduce Master Reads During YSQL Connection Churn with Authentication Caching

Applications that frequently open and close YSQL connections can generate more database work than the SQL being executed might suggest.

Every fresh YSQL backend needs to authenticate the user and initialize its session. Part of that startup path requires access to shared PostgreSQL catalogs such as pg_authid. With enough connection churn, those authentication and startup lookups can create a steady stream of catalog reads against the YB-Master.

YugabyteDB 2026.1 introduces improvements that reduce this overhead by preloading authentication catalog entries earlier and allowing the YB-TServer response cache to serve authentication catalog prefetches for regular YSQL backends… not just Connection Manager authentication backends.

✅ Supported Version

The combined connection-authentication caching improvements described in this Tip are documented in YugabyteDB 2026.1.1.0. The examples below were tested using 2026.1.1.0-b91. Issue #31999 was also backported to the 2025.2 release train, but the broader regular-backend caching enhancement in #32063 is documented in the 2026.1.1.0 release.

The official v2026.1.1.0 changelog lists both improvements: reducing pg_authid catalog cache misses and reducing master reads from frequent connection setup by applying the authentication response cache to all backends.

What Happens During a New YSQL Connection?

A brand-new PostgreSQL backend has to perform several operations before your first SQL statement even runs.

During authentication and backend initialization, YugabyteDB accesses shared catalogs that include information about roles, databases, and catalog versions.

One particularly important catalog is:

				
					pg_authid

pg_authid stores PostgreSQL role information, including authentication-related metadata.

Prior to the improvement tracked by #31999, a new YSQL backend could miss the pg_authid catalog cache multiple times during startup. The issue documents approximately two pg_authid cache misses per new connection: one lookup by role name during authentication and another by OID during backend initialization.

Under high connection churn, repeating that work for every new backend adds unnecessary overhead.

Two Improvements Work Together

There are actually two related optimizations involved.

Issue	Improvement	Benefit
`#31999`	Preload the `pg_authid` AUTHNAME and AUTHOID catalog-cache entries earlier during backend startup.	Reduces repeated `pg_authid` catalog cache misses on every fresh connection.
`#32063`	Allow regular YSQL backends to serve the authentication catalog prefetch from the YB-TServer `PgResponseCache`.	Converts repeated per-connection master reads for authentication catalogs into shared TServer cache hits.

The first optimization makes the PostgreSQL catalog cache more efficient during backend startup. The second reduces how often the backend needs to go back to the master for the authentication catalog prefetch itself.

This Is No Longer Just a Connection Manager Optimization

An important part of #32063 is that the TServer authentication cache is now available to regular YSQL backends.

Earlier work allowed a YSQL Connection Manager authentication backend to use the TServer response cache. The newer implementation extends that path so direct PostgreSQL/YSQL connections can benefit as well.

💡 Connection Manager is not required

The authentication response cache originally applied to Connection Manager authentication backends. With the #32063 enhancement, regular YSQL backends can use the same TServer-level authentication prefetch cache. This makes the optimization useful even for applications connecting directly to YSQL.

Enabling the Authentication Response Cache

The key TServer flag is:

				
					ysql_enable_read_request_cache_for_connection_auth

The current YugabyteDB flag documentation describes it as serving the connection-auth catalog prefetch, including pg_authid and pg_database, from the TServer response cache. The flag applies to both Connection Manager authentication backends and regular backends. Its default is false.

For the caching path to be used, the following conditions apply:

TServer Flag	Required Value	Current Default
`ysql_enable_read_request_caching`	`true`	`true`
`ysql_enable_read_request_cache_for_connection_auth`	`true`	`false`
`ysql_yb_enable_invalidation_messages`	`true`	`true`
`ysql_enable_profile`	`false`	`false`

The current flag reference lists read-request caching and invalidation messages as enabled by default, while login profiles are disabled by default. The authentication-specific response cache itself is disabled by default, so that is the key flag that normally needs to be enabled.

⚠️ Login Profiles and Authentication Caching

The connection-auth response cache is not used when YSQL login profiles are enabled. Updates to pg_yb_role_profile occur outside the normal DDL catalog-version path, which could otherwise allow a cached authentication response to become stale.

The YugabyteDB flag documentation explicitly notes this restriction.

Demo: Measuring the Effect of Connection-Auth Caching

The following test uses:

● Version: 2026.1.1.0-b91
● Build Time: 11 Aug 2026 11:21:50 UTC

The test repeatedly creates fresh ysqlsh connections and watches the master read counter:

				
					handler_latency_yb_tserver_TabletServerService_Read_count

The important thing is to compare the change in the counter, not the absolute value.

Part 1: Baseline – Authentication Response Cache Disabled

Start a fresh local cluster with the authentication response cache explicitly disabled:

				
					./bin/yugabyted destroy

./bin/yugabyted start \
  --tserver_flags="ysql_enable_read_request_cache_for_connection_auth=false"

sleep 5

Warm up YSQL once:

				
					./bin/ysqlsh -c "SELECT 1;" > /dev/null

Capture the master read counter:

				
					curl -s http://127.0.0.1:7000/prometheus-metrics \
  | grep 'handler_latency_yb_tserver_TabletServerService_Read_count'

Now create 100 fresh YSQL connections:

				
					for i in {1..100}; do
  ./bin/ysqlsh -c "SELECT 1;" > /dev/null
done

Check the metric again:

				
					curl -s http://127.0.0.1:7000/prometheus-metrics \
  | grep 'handler_latency_yb_tserver_TabletServerService_Read_count'

Record the difference between the two readings.

Part 2: Enable Authentication Response Caching

Destroy the test cluster and recreate it with the authentication cache enabled:

				
					./bin/yugabyted destroy

./bin/yugabyted start \
  --tserver_flags="ysql_enable_read_request_caching=true,ysql_enable_read_request_cache_for_connection_auth=true,ysql_yb_enable_invalidation_messages=true,ysql_enable_profile=false"

sleep 5

Warm the cluster in the same way:

				
					./bin/ysqlsh -c "SELECT 1;" > /dev/null

Capture the new baseline:

				
					curl -s http://127.0.0.1:7000/prometheus-metrics \
  | grep 'handler_latency_yb_tserver_TabletServerService_Read_count'

Run the exact same connection churn workload:

				
					for i in {1..100}; do
  ./bin/ysqlsh -c "SELECT 1;" > /dev/null
done

Then check the counter again:

				
					curl -s http://127.0.0.1:7000/prometheus-metrics \
  | grep 'handler_latency_yb_tserver_TabletServerService_Read_count'

What Should You See?

With the authentication response cache enabled, the increase in master reads should be smaller for the same number of fresh connections.

Instead of every backend independently fetching the authentication catalogs from the master, repeated authentication prefetch requests can now be satisfied by the TServer’s shared response cache. This is the behavior explicitly described in #32063.

💡 Compare the delta, not a magic number

The goal of the test is not to reproduce an exact master-read count. Compare the increase in handler_latency_yb_tserver_TabletServerService_Read_count across the same connection workload with authentication caching disabled and enabled. The cached run should require fewer master reads for the connection-authentication catalogs.

What Is Still Read from the Master?

This optimization does not eliminate all catalog work associated with creating a new PostgreSQL backend.

The authentication response cache applies specifically to the connection-auth catalog prefetch. YugabyteDB’s flag documentation notes that the backend still rebuilds its full catalog cache and shared relcache initialization data from fresh master data after authentication.

That means you should still expect some master read activity when repeatedly creating fresh connections.

⚠️ This does not cache every backend-startup catalog read

The optimization caches the authentication prefetch path. A newly created backend still performs other startup and catalog initialization work, so master reads will not drop to zero.

One Important Detail About the Demo

Because 2026.1.1.0-b91 already contains the #31999 pg_authid catalog-cache improvement, both sides of this test benefit from that optimization.

The before-and-after test primarily isolates the behavior controlled by:

				
					ysql_enable_read_request_cache_for_connection_auth

In other words:

Both tests:
- #31999 -> pg_authid cache preload improvement
Caching enabled test:
- #31999 + #32063 -> TServer authentication response caching

That distinction is useful when interpreting the results.

Where This Helps Most

Connection pooling is still one of the best ways to avoid unnecessary backend creation, but not every application maintains long-lived connections perfectly.

Short-lived functions, autoscaling application tiers, serverless workloads, microservices, health checks, and misconfigured client pools can all generate bursts of new connections.

The 2026.1 authentication caching improvements make those connection patterns less expensive by reducing unnecessary catalog cache misses and repeated master reads during the authentication path.

Final Takeaway

Fresh YSQL connections require more than opening a TCP socket—they must authenticate the user and initialize PostgreSQL backend state.

With YugabyteDB 2026.1.1.0:

New YSQL Connection

↓

Authentication Catalog Prefetch

↓

TServer PgResponseCache

↓

Cache Hit
Reuse cached catalog response

Cache Miss
Read from YB-Master

The result is fewer repeated reads against the master when applications create large numbers of new YSQL connections.

✅ Final Takeaway

If your workload creates large numbers of short-lived YSQL connections, YugabyteDB 2026.1.1.0 can reduce authentication-related master traffic by serving connection-auth catalog prefetches from the YB-TServer response cache. Enable ysql_enable_read_request_cache_for_connection_auth=true and compare the master-read delta under your actual connection workload.

Have Fun!