scram_iterations

scram_iterations is the PostgreSQL setting that defines the iteration count for SCRAM secret generation.

Note

Fact — official short description: “Sets the iteration count for SCRAM secret generation.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , Value—: Raw unit
Range , Value1 – 2147483647: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueConnections and Authentication / Authentication: Upstream classification
Latest boot value , Value4096: 4096

Lifecycle

Fact	Value
First observed	PG16
Present in	PG16–19 Beta 3
Removed in	No
Introduction commit	`b577743000cd` — Make SCRAM iteration count configurable
Commit date	2023-03-27
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG16–19 Beta 3	`4096`	—	4096

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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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.
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.
Small nodes	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.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

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.

password_encryption · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile