Create a read replica for a Postgres service

POST/v1/organizations/{organizationId}/postgres/{postgresId}/readReplica

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.

Initiate the process to create a new read replica for a Postgres service.

Authorizations

Authorizationstringheaderrequired
Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi

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

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

maxLength: 50, minLength: 1
pgConfigoptionalobject
Postgres runtime configuration configuration.

Example: {"max_connections":100}
31 properties
- max_connectionsoptionalstring | integer
  Sets the maximum number of concurrent connections to the database server.
  
  minimum: 1
  Example: 500
- default_transaction_isolationoptionalread committedorrepeatable readorserializable
  Sets the default transaction isolation level for new transactions.
  
  Example: "read committed"
- ssl_min_protocol_versionoptionalTLSv1orTLSv1.1orTLSv1.2orTLSv1.3
  Sets the minimum SSL/TLS protocol version allowed for client connections.
  
  Example: "TLSv1.3"
- maintenance_work_memoptionalstring | integer
  Sets the maximum memory to be used for maintenance operations.
  
  minimum: 64
  Example: "64MB"
- work_memoptionalstring | integer
  Sets the amount of memory Postgres will use for internal operations like sorting and hashing as part of executing a query.
  
  minimum: 64
  Example: "4MB"
- effective_cache_sizeoptionalstring | integer
  Sets the planner's assumption about the total size of data caches.
  
  minimum: 8
  Example: "4GB"
- random_page_costoptionalstring | number
  Sets the planner's estimate of the cost of a non-sequentially-fetched disk page. Lower values (1.1-1.5) are better for SSDs.
  
  minimum: 0
  Example: 1.1
- effective_io_concurrencyoptionalstring | integer
  Number of concurrent disk I/O operations the planner expects. Higher values (100-200) benefit SSDs.
  
  minimum: 0
  Example: 200
- max_worker_processesoptionalstring | integer
  Maximum number of background processes the system can support. Includes parallel query workers, logical replication, and more.
  
  minimum: 0
  Example: 8
- max_parallel_workersoptionalstring | integer
  Maximum number of workers that can be used for parallel operations. Cannot exceed max_worker_processes.
  
  minimum: 0
  Example: 4
- max_parallel_workers_per_gatheroptionalstring | integer
  Maximum number of parallel workers per executor node for parallel queries. Use 0 to disable parallel queries.
  
  minimum: 0
  Example: 2
- max_parallel_maintenance_workersoptionalstring | integer
  Maximum number of parallel workers for maintenance operations like CREATE INDEX and VACUUM.
  
  minimum: 0
  Example: 2
- statement_timeoutoptionalstring | integer
  Abort any statement that runs longer than the specified time. Use 0 to disable.
  
  minimum: 0
  Example: "60s"
- lock_timeoutoptionalstring | integer
  Abort any statement that waits longer than the specified time while attempting to acquire a lock. Use 0 to disable.
  
  minimum: 0
  Example: "10s"
- idle_session_timeoutoptionalstring | integer
  Terminate any session that has been idle for longer than the specified time. Use 0 to disable.
  
  minimum: 0
  Example: "2m"
- idle_in_transaction_session_timeoutoptionalstring | integer
  Terminate any session that has been idle within an open transaction for longer than the specified time. Use 0 to disable.
  
  minimum: 0
  Example: "2h"
- transaction_timeoutoptionalstring | integer
  Terminate any statement that takes more than the specified time, even while active. Use 0 to disable.
  
  minimum: 0
  Example: "120s"
- wal_sender_timeoutoptionalstring | integer
  Terminate replication connections that are inactive for longer than this time. Use 0 to disable.
  
  minimum: 0
  Example: "120m"
- wal_keep_sizeoptionalstring | integer
  Minimum size of past WAL files kept in pg_wal for standby servers. Use 0 to disable.
  
  minimum: 0
  Example: "1GB"
- min_wal_sizeoptionalstring | integer
  Minimum size to shrink the WAL to. WAL files are recycled rather than removed when below this size.
  
  minimum: 32768
  Example: "80MB"
- max_wal_sizeoptionalstring | integer
  Maximum size WAL can grow between checkpoints. Larger values improve write performance but increase crash recovery time.
  
  minimum: 32768
  Example: "5GB"
- max_slot_wal_keep_sizeoptionalstring | integer
  Specifies the maximum size of WAL files that replication slots are allowed to retain. Use -1 for unlimited.
  
  minimum: 0
  Example: "-1"
- wal_compressionoptionalofforonorlz4orzstd
  Compress full-page writes in WAL. Reduces I/O at the cost of CPU. Options vary by PostgreSQL version.
  
  Example: "off"
- autovacuum_max_workersoptionalstring | integer
  Maximum number of autovacuum worker processes that can run at the same time. Workers share a single cost-limit budget, so raising this alone may not speed up vacuuming.
  
  minimum: 1
  Example: 8
- autovacuum_naptimeoptionalstring | integer
  Minimum delay between autovacuum runs. Lower values make autovacuum check for work more frequently.
  
  minimum: 1
  Example: "5s"
- autovacuum_work_memoptionalstring | integer
  Maximum memory each autovacuum worker uses to track dead tuples. Higher values reduce repeated index-vacuum passes on large tables. Use -1 to fall back to maintenance_work_mem.
  
  minimum: 1024
  Example: "64000kB"
- autovacuum_vacuum_scale_factoroptionalstring | number
  Fraction of a table's rows that must change before autovacuum runs. Lower values vacuum large tables more frequently.
  
  minimum: 0
  Example: 0.2
- autovacuum_analyze_scale_factoroptionalstring | number
  Fraction of a table's rows that must change before autovacuum runs ANALYZE to refresh planner statistics.
  
  minimum: 0
  Example: 0.1
- autovacuum_vacuum_insert_scale_factoroptionalstring | number
  Fraction of a table's rows that must be inserted before autovacuum runs. Helps vacuum insert-heavy, rarely-updated tables.
  
  minimum: 0
  Example: 0.2
- autovacuum_vacuum_cost_limitoptionalstring | integer
  Cost-accounting limit shared across all autovacuum workers before they pause. Use -1 to inherit vacuum_cost_limit.
  
  minimum: 1
  Example: "-1"
- autovacuum_vacuum_cost_delayoptionalstring | integer
  Time autovacuum sleeps when the cost limit is reached. Lower values speed up vacuuming at the cost of more I/O.
  
  minimum: 0
  Example: "2ms"
pgBouncerConfigoptionalmap ofstring
PgBouncer runtime configuration configuration.

Example: {"default_pool_size":"16"}
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._-]+$

Response

JSON

200

Successful response

JSON

statusoptionalnumber
HTTP status code.

Example: 200
requestIdoptionalstring
Unique id assigned to every request. UUIDv4

format: uuid
resultoptionalobject
16 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.
- postgresVersionoptional18or17
- sizeoptionalc6gd.largeorc6gd.xlargeorc6gd.2xlargeorc6gd.4xlargeorc6gd.8xlargeorc6gd.16xlarge+137 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 two standbys.
- 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._-]+$
- 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

Create a read replica for a Postgres service

curl --request POST \
  --url https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/postgres/497f6eca-6276-4993-bfeb-53cbbbba6f08/readReplica \
  --header 'Authorization: Basic <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "string",
  "pgConfig": {
    "max_connections": 100
  },
  "pgBouncerConfig": {
    "default_pool_size": "16"
  },
  "tags": [
    {
      "key": "Environment",
      "value": "staging"
    }
  ]
}
'

const url = 'https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/postgres/497f6eca-6276-4993-bfeb-53cbbbba6f08/readReplica';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Basic <token>'},
  body: JSON.stringify({
    name: 'string',
    pgConfig: {max_connections: 100},
    pgBouncerConfig: {default_pool_size: '16'},
    tags: [{key: 'Environment', value: 'staging'}]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/postgres/497f6eca-6276-4993-bfeb-53cbbbba6f08/readReplica"

payload = {
    "name": "string",
    "pgConfig": { "max_connections": 100 },
    "pgBouncerConfig": { "default_pool_size": "16" },
    "tags": [
        {
            "key": "Environment",
            "value": "staging"
        }
    ]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "status": 200,
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "result": {
    "name": "string",
    "provider": "aws",
    "region": "string",
    "postgresVersion": "18",
    "size": "c6gd.large",
    "haType": "none",
    "tags": [
      {
        "key": "Environment",
        "value": "staging"
      }
    ],
    "id": "f71df78e-ddad-82d0-8dfa-abbec741b82e",
    "storageSize": 0,
    "state": "creating",
    "createdAt": "2026-03-26T20:51:16.384Z",
    "isPrimary": false,
    "connectionString": "string",
    "username": "string",
    "password": "string",
    "hostname": "string"
  }
}

{
  "status": 400,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

{
  "status": 500,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}