allow_alter_system

Definition PG 18 manual

When allow_alter_system is set to off, an error is returned if the ALTER SYSTEM command is executed. This parameter can only be set in the postgresql.conf file or on the server command line. The default value is on.

Note that this setting must not be regarded as a security feature. It only disables the ALTER SYSTEM command. It does not prevent a superuser from changing the configuration using other SQL commands. A superuser has many ways of executing shell commands at the operating system level, and can therefore modify postgresql.auto.conf regardless of the value of this setting.

Turning this setting off is intended for environments where the configuration of PostgreSQL is managed by some external tool. In such environments, a well-intentioned superuser might mistakenly use ALTER SYSTEM to change the configuration instead of using the external tool. This might result in unintended behavior, such as the external tool overwriting the change at some later point in time when it updates the configuration. Setting this parameter to off can help avoid such mistakes.

This parameter only controls the use of ALTER SYSTEM. The settings stored in postgresql.auto.conf take effect even if allow_alter_system is set to off.

How it works

Allows running the ALTER SYSTEM command. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

When off, PostgreSQL rejects ALTER SYSTEM before it can rewrite postgresql.auto.conf. The switch neither erases existing auto.conf entries nor prevents an operating-system administrator from editing configuration files, so it is an SQL administration boundary rather than a filesystem security boundary.

Monitor and change allow_alter_system together with config_file, data_directory, hba_file. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Operational considerations

Keeping a compatibility switch permanently instead of fixing the client.

Testing in one session and deploying globally to unrelated applications.

Confusing parsing compatibility with data or security compatibility.

Forgetting to remove an override after the upgrade migration is complete.

Workload guidance

OLAP: Use the same policy as OLTP. If batch tooling calls ALTER SYSTEM, migrate it to the declarative configuration interface first so jobs do not begin failing silently after reload.

OLTP: A managed environment whose configuration controller owns postgresql.conf/auto.conf may disable it to narrow the SQL administration surface. Audit existing auto.conf and still restrict filesystem and superuser access.

SMALL: A single-admin instance may keep the default, but ALTER SYSTEM is not a change-audit system; retain versioned configuration, rollback, and restart/reload records.