Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Update Postgres service state

Beta
PATCH/v1/organizations/{organizationId}/postgres/{postgresId}/state
API playground

Initiate a process for a Postgres service:

  • restart: Initiates a service restart
  • promote: Promotes a read replica to primary
  • switchover: Switch a primary over to a standby. If there is no standby, replace the primary with a newly provisioned server and switch over to it.

Permission

The API key must have the control-plane:postgres-service:manage permission.

Authorizations

Path parameters

  • organizationIdstringrequired

    ID of the organization that owns the Postgres service.

    format: uuid
  • postgresIdstringrequired

    ID of the requested Postgres service.

    format: uuid

Request bodyJSON

  • commandoptionalrestartorpromoteorswitchover

    Postgres status, which initiates a process.

Response

JSON

200

Successful response

JSON
  • statusoptionalnumber

    HTTP status code.

    Example: 200
  • requestIdoptionalstring

    Unique id assigned to every request. UUIDv4

    format: uuid
  • resultoptionalobject
    20 properties
    • nameoptionalstring

      Name of the Postgres service. Alphanumerical string with whitespaces up to 50 characters.

      maxLength: 50, minLength: 1
    • provideroptionalawsorgcp

      The cloud provider for a Postgres service.

    • regionoptionalstring

      The cloud region for a Postgres service.

    • postgresVersionoptional19or18or17
    • sizeoptionalc6gd.largeorc6gd.xlargeorc6gd.2xlargeorc6gd.4xlargeorc6gd.8xlargeorc6gd.16xlarge+186 more

      The VM size for a Postgres service.

    • haTypeoptionalnoneorasyncorsync

      Type of high availability: “none” for no replication, “async” for asynchronous replication to a single standby, and “sync” for synchronous replication to the number of standbys in standbyCount (two by default).

    • standbyCountoptional0or1or2

      Number of hot standby instances. Accepted values and defaults depend on haType:

      • “none”: 0 (default)
      • “async”: 1 (default)
      • “sync”: 1, or 2 (default)

      When haType is updated without standbyCount, the default for the new haType applies.

    • tagsoptionalarray ofobject

      Tags associated with the Postgres service. Tag keys starting with “chc_” are reserved for internal use.

      2 properties
      • keystringrequired

        Tag key. Must be alphanumeric with dashes, underscores and dots.

        maxLength: 128, minLength: 1, pattern: ^[a-zA-Z0-9._-]+$
      • valueoptionalstring

        Tag value. Must be alphanumeric with dashes, underscores and dots.

        maxLength: 256, pattern: ^[a-zA-Z0-9._-]+$
    • ipAccessListoptionalarray ofobject

      IPv4 access rules shown in the console. IPv6 rules are not included. Returned when reading or configuring access; omitted from other service updates.

      4 properties
      • sourcestringrequired

        IPv4 address or CIDR allowed to connect. Returned as a canonical CIDR.

        Example: "203.0.113.0/24"
      • portRangestringrequired

        Port or inclusive range, from 1 to 65535. Use "5432" for Postgres, "6432" for PgBouncer, or a range such as "5432..6432".

        Example: "5432"
      • idoptionalstring

        Rule ID returned by the service. Include it when editing an existing rule; omit it when creating a rule.

      • descriptionoptionalstring

        Optional description of the access list entry.

    • idoptionalstring
      format: uuid
      Example: "f71df78e-ddad-82d0-8dfa-abbec741b82e"
    • storageSizeoptionalinteger

      The storage size, in GiB, which must be supported by the specified size.

    • stateoptionalcreatingorrestartingorrunningorreplaying_walorrestoring_backuporfinalizing_restore+3 more

      Current state of the service

    • createdAtoptionalstring
      format: date-time
      Example: "2026-03-26T20:51:16.384Z"
    • isPrimaryoptionalboolean

      True if this service is the primary service in the data warehouse

      Default: false
    • connectionStringoptionalstring

      Connection string to the Postgres service. Embeds the service password, so it is only returned when the service is created or its password is reset. Omitted from every other response when Postgres credential redaction is enabled for the organization. Not guaranteed to be present — treat as optional.

    • usernameoptionalstring

      Username for the Postgres service

    • passwordoptionalstring

      Password for the Postgres service. Only returned when the service is created or its password is reset. Omitted from every other response when Postgres credential redaction is enabled for the organization. Not guaranteed to be present — treat as optional.

    • hostnameoptionalstring

      Hostname for the Postgres service

    • deletionProtectionoptionalboolean

      When true, the service cannot be deleted until deletion protection is turned off. Only available for organizations with deletion protection enabled.

    • earliestRestoreTimeoptionalstring

      Earliest point in time the service can be restored to with the restore endpoint. ISO-8601. Only present for a primary service once its first backup has completed.

      format: date-time