Skip to content

PostgreSQL Settings ​

PostgreSQL Settings tunes the performance and resource parameters of the local PostgreSQL server. Security, authentication, network, and TLS parameters are deliberately not editable here.

Until the PostgreSQL module is installed, the page says so and changes nothing.

Overview ​

URL: /admin/settings/postgresql-settings

The page appears under Settings > Databases.

The PostgreSQL settings with the profile picker and parameter list

Configuration state ​

The header states where the current values came from, which is what tells you whether the panel or something else is in charge:

FieldWhat it means
Stored profileThe profile this panel has on record. Custom means the values match neither a preset nor a saved profile.
Running profileWhat the server is actually running.
Last appliedWhen this panel last applied a profile. Never applied from this panel means the values on the server were not set here.
ServerThe PostgreSQL release.
RestartWhether a change is waiting for a restart.

Profiles ​

A profile is a starting point rather than a fixed setting:

  • Balanced - a general-purpose starting point.
  • Web transactions - for many small, short queries, which is what most hosted sites produce.
  • Reporting - for fewer, heavier queries.
  • Custom - what the page shows when the values match no preset.

A built-in preset is computed for this particular machine rather than being a fixed table of numbers, so the same preset lands on different values on a different server.

Reset to server defaults puts every parameter back to what PostgreSQL itself would use.

Parameters ​

Every field, its unit, and its accepted range come from the running server, so the form cannot offer a value the server would reject. Values are in the unit named in the field label.

Each parameter states what is in effect, what it falls back to, and its source: a value from the configuration file was set explicitly, a value from the default was never set.

A parameter you do not change keeps its value. Leaving a field alone does not reset it.

Parameters marked Restart required are read by PostgreSQL only at startup. Changing one is stored, but does not take effect until the server restarts, and the header says a restart is pending until it does. Plan those changes for a quiet moment: a restart interrupts every open connection, including the sites using them.

Values the page refuses ​

Since panel 1.9.4, a value with a line break or another control character is refused with "Field must not contain line breaks or other control characters.", and a value that is too long with "Field is too long.", followed by the maximum. The message stands under the field it names, and nothing is sent or stored. Before, a line break at the end of a value was dropped and the rest was sent.

The administrator API ​

Since panel 1.9.5, the administrator REST API reads and applies the settings of this page with the same checks. The calls need an administrator API key; none of them needs an explicit grant.

Method and pathWhat it does
GET /api/postgresql/settingsWhat this page shows: the configuration state, each parameter with the value in effect, the value stored for it, its unit, its bounds, and whether changing it needs a restart, and the built-in profiles of this server.
PUT /api/postgresql/settingsApply either a built-in profile, by its id, or settings, parameter names with their values. Only the parameters named change.
POST /api/postgresql/settings/resetReset to server defaults: either names, the parameters to reset, or "all": true for every parameter this panel set. A request with neither is refused, never read as a reset of everything.

A value is checked as on the page: a value for every parameter, numbers within their bounds and in their unit. A parameter that is not listed or cannot be edited is refused by name with 422, and so is an unknown profile. The answer's activation says how the change was applied: reload picks it up without dropping a connection, and restart restarted PostgreSQL, which closes every open connection for a few seconds. pending_restart says whether a stored value waits for a restart. While the PostgreSQL module is not installed, the calls answer 409.