Dynamically Change YSQL HBA Rules Without Restarting YB-TServers

YSQL uses PostgreSQL-style host-based authentication (HBA) rules to determine which clients can connect, which database users they can use, and which authentication method is required.

In YugabyteDB, these rules are configured using the YB-TServer flag:

ysql_hba_conf_csv

The value of this flag is used to generate the local ysql_hba.conf file used by YSQL. YugabyteDB documentation confirms that ysql_hba.conf is autogenerated from ysql_hba_conf_csv, so the file itself should not be edited directly.

Historically, changing ysql_hba_conf_csv required restarting the YB-TServers. That can be inconvenient when administrators need to make security-related changes such as:

● Changing authentication methods.
● Adding or removing allowed networks.
● Restricting a particular database user.
● Updating LDAP authentication rules.
● Responding quickly to a security requirement.

Starting with YugabyteDB 2025.1.1.1, ysql_hba_conf_csv can be changed dynamically without restarting the YB-TServer. The 2025.1.1.1 release notes explicitly list the enhancement, and it is also present in the 2025.2 release line.

Version Behavior

YugabyteDB Version	`ysql_hba_conf_csv` Behavior	Restart Required?
2024.2.7.1	Not recognized as safe for runtime changes	Yes, using the normal supported workflow
2025.1.1.1	Dynamic updates introduced	No
2025.2	Dynamic update support included	No

💡 Version check: There is currently a documentation inconsistency worth knowing about. The YugabyteDB release notes explicitly document dynamic ysql_hba_conf_csv updates beginning in 2025.1.1.1, while the current stable YB-TServer flag reference still labels the flag as Restart Needed. Verify the behavior of the exact YugabyteDB and YBA version you are running before making a production change.

The current YugabyteDB source also defines ysql_hba_conf_csv using DEFINE_RUNTIME_string, confirming its runtime designation in current code.

Why This Is Useful

Consider a cluster that currently allows clients to connect using trust:

				
					host all all all trust

You may want to require SCRAM authentication for a specific application user without restarting the database.

A runtime HBA change makes that possible.

Better yet, we can demonstrate it without changing authentication for every user and accidentally locking ourselves out.

Demo: Change One User from trust to SCRAM

For this example, we’ll create a test user named hba_demo and require scram-sha-256 authentication for that user while leaving the existing catch-all trust rule in place.

This gives us a safe way to demonstrate that the HBA rules changed dynamically.

Step 1: Check the Current HBA Rules

Connect using ysqlsh and query pg_hba_file_rules:

				
					SELECT
    line_number,
    type,
    database,
    user_name,
    address,
    auth_method
FROM pg_hba_file_rules
ORDER BY line_number;

You might see something similar to:

				
					.line_number | type  | database | user_name  | address | auth_method
-------------+-------+----------+------------+---------+------------
           4 | host  | {all}    | {all}      | all     | trust
           5 | local | {all}    | {yugabyte} |         | trust

The pg_hba_file_rules view is useful for examining and troubleshooting the HBA configuration YugabyteDB generated.

Step 2: Record the PostgreSQL Start Time

Before changing anything, record when the local PostgreSQL process started:

				
					SELECT pg_postmaster_start_time();

Example:

				
					.  pg_postmaster_start_time
-------------------------------
 2026-08-10 13:12:41.123456+00

We’ll run this again after changing the HBA configuration.

If the value remains unchanged, we have another easy way to demonstrate that PostgreSQL was not restarted.

Step 3: Create a SCRAM Test User

First ensure that the password is stored using SCRAM:

				
					SET password_encryption = 'scram-sha-256';

Then create the test user:

				
					CREATE ROLE hba_demo
LOGIN
PASSWORD 'ChangeMeForYourDemo!';

🔐 Avoid locking yourself out: Do not change a broad rule such as host all all all trust directly to scram-sha-256 until you have verified that the required login roles have valid passwords and that you have a recovery path. HBA rules are evaluated for new connections, so an incorrect rule can prevent administrators and applications from reconnecting.

Step 4: Dynamically Change `ysql_hba_conf_csv`

For a self-managed YugabyteDB installation, yb-ts-cli can change a runtime YB-TServer flag.

Run the following against the YB-TServer RPC port, which is 9100 by default:

				
					./bin/yb-ts-cli \
  --server_address=127.0.0.1:9100 \
  set_flag ysql_hba_conf_csv \
  "host all hba_demo 127.0.0.1/32 scram-sha-256,host all all all trust"

The important part of the new configuration is the ordering:

				
					host all hba_demo 127.0.0.1/32 scram-sha-256
host all all all trust

PostgreSQL HBA processing uses the first matching rule, so connections from hba_demo on 127.0.0.1 encounter the SCRAM rule before reaching the more permissive catch-all rule. YugabyteDB likewise evaluates the generated HBA records in order.

🌐 Multi-node cluster: yb-ts-cli set_flag changes the targeted YB-TServer. If you are administering a multi-node cluster directly, apply the desired HBA configuration consistently to every YB-TServer. In YugabyteDB Anywhere, use the universe’s Actions > Edit Flags workflow so YBA can coordinate the flag configuration across the universe.

YugabyteDB Anywhere provides an Edit Flags workflow and supports immediately applying flags that do not require a restart.

Step 5: Verify the New HBA Rules

Run the same query again:

				
					SELECT
    line_number,
    type,
    database,
    user_name,
    address,
    auth_method
FROM pg_hba_file_rules
ORDER BY line_number;

The relevant rules should now resemble:

				
					/line_number | type  | database | user_name  |   address    |  auth_method
-------------+-------+----------+------------+--------------+---------------
           4 | host  | {all}    | {hba_demo} | 127.0.0.1    | scram-sha-256
           5 | host  | {all}    | {all}      | all          | trust
           6 | local | {all}    | {yugabyte} |              | trust

Step 6: Prove That Authentication Changed

First try an incorrect password:

				
					PGPASSWORD='WrongPassword' ./bin/ysqlsh \
  -h 127.0.0.1 \
  -U hba_demo \
  -d yugabyte \
  -c "SELECT current_user;"

The connection should fail because the first matching rule now requires SCRAM authentication.

Now use the correct password:

				
					PGPASSWORD='ChangeMeForYourDemo!' ./bin/ysqlsh \
  -h 127.0.0.1 \
  -U hba_demo \
  -d yugabyte \
  -c "SELECT current_user;"

The connection should succeed:

				
					.current_user
--------------
 hba_demo

Step 7: Verify That PostgreSQL Was Not Restarted

Run:

				
					SELECT pg_postmaster_start_time();

Compare the result with the value recorded before changing ysql_hba_conf_csv.

It should be unchanged.

That gives us the important result:

				
					HBA configuration changed
        +
New authentication rule enforced
        +
PostgreSQL start time unchanged
        =
No YB-TServer / PostgreSQL restart required

Do You Need `pg_reload_conf()`?

This is an important difference from the original workflow.

In PostgreSQL, pg_reload_conf() tells the postmaster to re-read configuration files by causing a SIGHUP-style reload.

With YugabyteDB’s runtime implementation, however, changing the runtime configuration causes YugabyteDB to regenerate the PostgreSQL configuration files and reload the PostgreSQL process. Current YugabyteDB source shows the update path rewriting ysql_hba.conf and then issuing SIGHUP to PostgreSQL.

Therefore, on a YugabyteDB version supporting dynamic ysql_hba_conf_csv updates, this should not be necessary as a separate step:

				
					SELECT pg_reload_conf();

You can still use PostgreSQL configuration inspection functions and views for troubleshooting, but the runtime flag mechanism handles the reload needed to activate the new HBA configuration.

💡 Existing sessions are different: HBA rules are evaluated when a client establishes a connection. Changing an HBA rule does not retroactively disconnect sessions that are already connected. Test the new rule by opening a new connection.

What Happens on Older Versions?

On YugabyteDB 2024.2.7.1, attempting the same command produced:

				
					Unable to set flag: Remote error:
Flag is not safe to change at runtime
(use --force flag to allow anyway)

That behavior was captured directly in the test that led to this tip.

Although yb-ts-cli exposes a --force option, I would not use --force as the recommended production workaround for an older release.

The important point is not simply whether the tool can be forced to modify a flag. The later YugabyteDB enhancement explicitly added supported dynamic behavior for ysql_hba_conf_csv.

For releases where the flag is not runtime-supported, use the normal rolling-restart process or upgrade to a release that supports the dynamic configuration behavior.

YugabyteDB Anywhere

For a universe managed by YugabyteDB Anywhere:

1. Open the universe.
2. Select Actions > Edit Flags.
3. Edit ysql_hba_conf_csv under the YB-TServer configuration.
4. Use the available non-restart application method when supported by the YugabyteDB/YBA version.
5. Apply the change.
6. Verify the resulting rules using pg_hba_file_rules.
7. Open a new client connection and confirm the new authentication behavior.

YBA’s Edit Flags interface can immediately apply configuration changes that do not require a restart, while restart-required changes can be handled using rolling or concurrent restart workflows.

Final Takeaway

The ability to update ysql_hba_conf_csv dynamically removes an operational obstacle from YSQL security administration.

Instead of requiring a rolling YB-TServer restart just to change an authentication rule, supported YugabyteDB releases can:

● Update the runtime ysql_hba_conf_csv value.
● Regenerate ysql_hba.conf.
● Reload PostgreSQL.
● Apply the new rule to subsequent client connections.
● Keep existing database processes and sessions running.

For environments where authentication rules change frequently., or where security teams need IP, user, LDAP, or authentication-policy changes made quickly, that is a small feature with a very useful operational payoff.

And perhaps the most important lesson: check the YugabyteDB version before assuming ysql_hba_conf_csv is runtime configurable. The feature was explicitly documented in the 2025.1.1.1 release line and is also included in 2025.2.

Have Fun!

Hard to believe it’s been over seven years since we built this house!

That’s my old Ford Edge sitting in the driveway… and yes, the license plate really does say VERTICA. 😄 I worked there before coming to Yugabyte, so of course I had to represent.

I actually wanted to get YUGABYTEDB on my next vanity plate, but apparently that’s just a few too many characters for PA. 😂

A lot has happened since this picture was taken, and now that we’re getting ready to move on to our next chapter, it’s starting to hit me how much I’m going to miss this place. We made a lot of great memories here! ❤️🏡