db_user_namespace

Definition PG 16 manual

This parameter enables per-database user names. It is off by default. This parameter can only be set in the postgresql.conf file or on the server command line.

If this is on, you should create users as username@dbname. When username is passed by a connecting client, @ and the database name are appended to the user name and that database-specific user name is looked up by the server. Note that when you create users with names containing @ within the SQL environment, you will need to quote the user name.

With this parameter enabled, you can still create ordinary global users. Simply append @ when specifying the user name in the client, e.g., joe@. The @ will be stripped off before the user name is looked up by the server.

db_user_namespace causes the client's and server's user name representation to differ. Authentication checks are always done with the server's user name so authentication methods must be configured for the server's user name, not the client's. Because md5 uses the user name as salt on both the client and server, md5 cannot be used with db_user_namespace.

How it works

db_user_namespace enables per-database user names. This legacy feature represented users internally as user@database and was removed in PostgreSQL 17; it is not a modern tenant-isolation mechanism.

db_user_namespace is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The final authentication path combines this setting with pg_hba.conf, role attributes, credential material, client capabilities, and sometimes operating-system identity services.

Operational considerations

Editing db_user_namespace without reloading configuration and verifying the effective value and subsequent behavior.

Changing one authentication setting without testing pg_hba.conf ordering, existing secrets, mappings, and every client library.

Weakening identity policy to solve connection churn or CPU cost that should be addressed with pooling and capacity planning.

Changing db_user_namespace globally without a rollback plan and a client or operational compatibility test.

Workload guidance

OLAP: Do not build analytical tenancy on db_user_namespace. Use roles, schemas, databases, and row-level security according to the required boundary.

OLTP: Do not adopt or tune db_user_namespace: it was a legacy compatibility feature and is absent from PostgreSQL 17+. Migrate to ordinary cluster-wide roles with explicit authorization.

SMALL: Leave db_user_namespace off on old releases and remove dependencies before upgrading; it provides no useful small-node optimization.