scram_iterations

Definition PG 18 manual

The number of computational iterations to be performed when encrypting a password using SCRAM-SHA-256. The default is 4096. A higher number of iterations provides additional protection against brute-force attacks on stored passwords, but makes authentication slower. Changing the value has no effect on existing passwords encrypted with SCRAM-SHA-256 as the iteration count is fixed at the time of encryption. In order to make use of a changed value, a new password must be set.

How it works

scram_iterations is embedded in every newly generated SCRAM-SHA-256 verifier. Raising it increases offline-guessing cost but also increases legitimate password-setting and authentication work; existing verifiers keep the iteration count with which they were created until their passwords are reset.

It is a USER-context setting, so the session that executes CREATE ROLE or ALTER ROLE determines the count written into the new verifier. Role, database, or application-specific overrides can therefore create a mixture of counts even when postgresql.conf has one value.

PostgreSQL warns that when a role's stored count differs from the configured server value, an unauthenticated observer can distinguish response behavior and infer that the role exists. A count change therefore requires uniform session policy and rotation of all SCRAM verifiers, not only a GUC edit.

Operational considerations

Changing the GUC without resetting existing passwords; their verifiers retain the old count.

Allowing role or database session defaults to generate verifiers with counts different from postgresql.conf, creating a role-existence side channel.

Raising the count without load-testing authentication storms, failover, pooler reconnects, and password rotation jobs.

Assuming a higher count repairs weak passwords or compensates for leaked verifier material.

Workload guidance

OLAP: Use the same count for analytical roles; workload class is not a reason to expose a distinct verifier count. Schedule credential rotation so long-lived service accounts do not retain the old count.

OLTP: Choose one count through a security and authentication-latency benchmark, enforce it in every password-management session, and rotate all role passwords so stored verifiers converge. Load-test reconnect storms and failover before raising it.

SMALL: Keep the upstream count unless testing justifies a change. A smaller server should reduce connection churn with pooling, but must still keep all generated verifiers at one consistent count.