Skip to content
You're viewing documentation for v2026.11.6-beta. It may be out of date.Go to latest
TimescaleDB Enterprise
Esc
↑↓navigate↵open⌘Jpreview

Review settings changes

Validates a change set (or a YAML document of all overrides) against pg_settings of the leader, SHOW CONFIG of PgBouncer and the locks of the owners, and gives one review row per setting: the old and the new value, the owner, a reload or a restart, and the servers that restart in order. A change of the PgBouncer pool size gives a derived row for work_mem, which follows the pool size. A decrease of max_connections, max_locks_per_transaction or max_prepared_transactions (a row, or a change that waits for a restart) restarts the leader first, when no such parameter goes up; with an increase too, the replicas restart first and the decrease waits for the next restart. The rows also hold the overrides that wait for their apply. hba (or the hba section of the YAML document) is the whole list of the HBA rules of the user; the review checks each rule and counts the rules that the change adds, removes and changes. A plan writes nothing, and it works while a workflow runs. It answers 409 when settings_version is not the version of the store.

POST/api/v1/database-services/{id}/settings/plan
Authorization
tse_sessionAPI key · cookierequired
Path parameters
idstringrequired
Request body
requiredapplication/json
changesSettingChangeInput[]

The changes. Omit changes and yaml to review the overrides that wait for their apply.

max items 500
Show properties
Array of SettingChangeInput
namestringrequired
min length 1 · max length 128
scopestringrequired

The scope of the setting: a PostgreSQL parameter, a setting of PgBouncer, or an HAProxy tunable of ADR D16.

Allowed:postgresqlpgbouncerhaproxy
valuestring | nullrequired

The new value, as a user writes it (for example 1min). null: a reset.

max length 4096
hbaHbaRule[]

All HBA rules of the user, in their order (ADR D17), in place of the hba section of yaml. Omit it to keep the rules.

max items 500
Show properties
Array of HbaRule
addressstringrequired

An IPv4 or IPv6 CIDR with no host bits, for example 10.20.0.0/16. Empty for local.

max length 64
commentstring

A note of the user. The files do not get it.

max length 256
databasestringrequired

all, sameuser, replication, or a comma list of database names.

max length 1024
methodstringrequired

scram-sha-256, md5, cert (hostssl only) or reject.

max length 32
typestringrequired

host, hostssl, hostnossl or local.

max length 16
userstringrequired

all, or a comma list of user names.

max length 1024
hba_versionstring

With hba: hba.version of the settings read that the user changed. Another version of the rules gives 409, and a change of other settings does not.

max length 64
settings_versioninteger<int64>required

The version that the user saw: settings_version of the settings or of the YAML read.

yamlstring

All overrides as one YAML document (ADR D14), in place of changes. A key that is not in the document is a reset.

max length 262144
Responses
200

OK

derivedSettingsDerivedRow[]required

The settings that the console changes because of a row, for example work_mem after a change of the pool size of PgBouncer (ADR D15).

Show properties
Array of SettingsDerivedRow
applystringrequired
Allowed:reload
namestringrequired
newstringrequired

The value after the apply, or an estimate of it.

notestring
oldstringrequired

The live value.

ownerstringrequired
Allowed:sized
scopestringrequired
Allowed:postgresql
errorsstring[]required

The errors that are not of one row, for example of the YAML document.

hbaSettingsPlanHBA

The review of the HBA rules, when the rules after the change differ from the applied rules (TSE-1149). A change of the rules needs only a reload.

Show properties
addedinteger<int64>required

The rules that the change adds, by position.

appliedHbaRule[]required

The user rules that the servers use now.

Show properties
Array of HbaRule
addressstringrequired

An IPv4 or IPv6 CIDR with no host bits, for example 10.20.0.0/16. Empty for local.

max length 64
commentstring

A note of the user. The files do not get it.

max length 256
databasestringrequired

all, sameuser, replication, or a comma list of database names.

max length 1024
methodstringrequired

scram-sha-256, md5, cert (hostssl only) or reject.

max length 32
typestringrequired

host, hostssl, hostnossl or local.

max length 16
userstringrequired

all, or a comma list of user names.

max length 1024
changedinteger<int64>required
errorsstring[]required
removedinteger<int64>required
rulesSettingsPlanHBARule[]required

The user rules after the change, in their order.

Show properties
Array of SettingsPlanHBARule
addressstringrequired
commentstring
databasestringrequired
errorsstring[]required
lineinteger<int64>

The line of the rule in the YAML document.

methodstringrequired
typestringrequired
userstringrequired
warningsstring[]required
warningsstring[]required
leader_firstbooleanrequired

A parameter that a replica needs at the value of the leader or higher goes down (a row, or a change that waits for a restart), and no such parameter goes up. The restart starts with the leader, and the writes stop for the time of its restart. With an increase too, the replicas restart first and the decrease waits for the next restart.

restartbooleanrequired

A row needs a restart of PostgreSQL.

restart_serversSettingsRestartServer[]required

The servers that restart, in order. Empty when no row needs a restart.

Show properties
Array of SettingsRestartServer
namestring
rolestring
server_idstringrequired
rowsSettingsPlanRow[]required

One row per setting that the apply changes: the changes, and the overrides that wait for their apply.

Show properties
Array of SettingsPlanRow
applystringrequired
Allowed:reloadrestartnone
errorsstring[]required
leader_firstbooleanrequired

The row lowers a parameter that a replica needs at the value of the leader or higher.

lineinteger<int64>

The line of the key in the YAML document.

namestringrequired
newstring | nullrequired

The new value. null: a reset.

new_ownerstringrequired
Allowed:overridedefault
notestring
oldstringrequired

The live value.

old_ownerstring

The owner of the live value. Empty when pg_settings has no such parameter.

reset_tostring

The value after a reset, when the console knows it: the shipped default or the PostgreSQL default.

scopestringrequired
warningsstring[]required
settings_versioninteger<int64>required
validbooleanrequired

No row and no part of the YAML document has an error. An apply needs a valid plan.

yaml_afterstringrequired

The overrides as YAML after the change.

yaml_beforestringrequired

The overrides as YAML before the change (ADR D14).

default

Error

codestring

Stable code of the refusal, when the route has codes

detailsstring[]

Additional detail, e.g. per-field validation failures

errorstringrequired

Human-readable error message

Request
curl -X POST 'https://console.example.com/api/v1/database-services/string/settings/plan' \
  -H 'Cookie: tse_session=YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "changes": [
    {
      "name": "string",
      "scope": "postgresql",
      "value": "string"
    }
  ],
  "hba": [
    {
      "address": "string",
      "comment": "string",
      "database": "string",
      "method": "string",
      "type": "string",
      "user": "string"
    }
  ],
  "hba_version": "string",
  "settings_version": 0,
  "yaml": "string"
}'
Response
{
  "derived": [
    {
      "apply": "reload",
      "name": "string",
      "new": "string",
      "note": "string",
      "old": "string",
      "owner": "sized",
      "scope": "postgresql"
    }
  ],
  "errors": [
    "string"
  ],
  "hba": {
    "added": 0,
    "applied": [
      {
        "address": "string",
        "comment": "string",
        "database": "string",
        "method": "string",
        "type": "string",
        "user": "string"
      }
    ],
    "changed": 0,
    "errors": [
      "string"
    ],
    "removed": 0,
    "rules": [
      {
        "address": "string",
        "comment": "string",
        "database": "string",
        "errors": [
          "string"
        ],
        "line": 0,
        "method": "string",
        "type": "string",
        "user": "string",
        "warnings": [
          "string"
        ]
      }
    ],
    "warnings": [
      "string"
    ]
  },
  "leader_first": true,
  "restart": true,
  "restart_servers": [
    {
      "name": "string",
      "role": "string",
      "server_id": "string"
    }
  ],
  "rows": [
    {
      "apply": "reload",
      "errors": [
        "string"
      ],
      "leader_first": true,
      "line": 0,
      "name": "string",
      "new": "string",
      "new_owner": "override",
      "note": "string",
      "old": "string",
      "old_owner": "string",
      "reset_to": "string",
      "scope": "string",
      "warnings": [
        "string"
      ]
    }
  ],
  "settings_version": 0,
  "valid": true,
  "yaml_after": "string",
  "yaml_before": "string"
}