> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a read replica for a Postgres service
> **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.
Beta
**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.
## OpenAPI
````yaml _specs/cloud-openapi.json POST /v1/organizations/{organizationId}/postgres/{postgresId}/readReplica
openapi: 3.1.2
info:
title: OpenAPI spec for ClickHouse Cloud
version: '1.0'
contact:
name: ClickHouse Support
url: >-
https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-910487
email: support@clickhouse.com
servers:
- url: https://api.clickhouse.cloud
security:
- basicAuth: []
tags:
- name: Organization
- name: User management
- name: Billing
- name: Role Management
- name: Service
- name: Backup
- name: OpenAPI
- name: Prometheus
- name: ClickPipes
- name: ClickStack
- name: Postgres
paths:
/v1/organizations/{organizationId}/postgres/{postgresId}/readReplica:
post:
tags:
- Postgres
summary: Create a read replica for a Postgres service
description: >-
**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.
operationId: postgresInstanceCreateReadReplica
parameters:
- in: path
name: organizationId
description: ID of the organization that owns the Postgres service.
required: true
schema:
type: string
format: uuid
- in: path
name: postgresId
description: ID of the requested Postgres service.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PostgresServiceReadReplicaRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 200
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
result:
$ref: '#/components/schemas/PostgresService'
'400':
description: >-
The request cannot be processed due to a client error. Please verify
your request parameters and try again.
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 400
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
'500':
description: >-
An internal server error has occurred. If this issue persists,
please contact ClickHouse Cloud support for assistance.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP status code.
example: 500
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
components:
schemas:
PostgresServiceReadReplicaRequest:
properties:
name:
$ref: '#/components/schemas/pgNameProperty'
pgConfig:
$ref: '#/components/schemas/pgConfig'
pgBouncerConfig:
$ref: '#/components/schemas/pgBouncerConfig'
tags:
$ref: '#/components/schemas/pgTags'
required:
- name
PostgresService:
properties:
name:
$ref: '#/components/schemas/pgNameProperty'
provider:
$ref: '#/components/schemas/pgProvider'
region:
$ref: '#/components/schemas/pgRegion'
postgresVersion:
$ref: '#/components/schemas/pgVersion'
size:
$ref: '#/components/schemas/pgSize'
haType:
$ref: '#/components/schemas/pgHaType'
tags:
$ref: '#/components/schemas/pgTags'
id:
$ref: '#/components/schemas/pgIdProperty'
storageSize:
$ref: '#/components/schemas/pgStorageSize'
state:
$ref: '#/components/schemas/pgStateProperty'
createdAt:
$ref: '#/components/schemas/pgCreatedAtProperty'
isPrimary:
$ref: '#/components/schemas/pgIsPrimaryProperty'
connectionString:
description: >-
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.
type: string
username:
description: Username for the Postgres service
type: string
password:
description: >-
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.
type: string
hostname:
description: Hostname for the Postgres service
type: string
pgNameProperty:
type: string
title: Postgres Service Name
description: >-
Name of the Postgres service. Alphanumerical string with whitespaces up
to 50 characters.
minLength: 1
maxLength: 50
pgConfig:
type: object
title: Postgres Configuration
description: >-
Postgres [runtime
configuration](https://www.postgresql.org/docs/current/runtime-config.html)
configuration.
properties:
max_connections:
type:
- string
- integer
description: >-
Sets the maximum number of concurrent connections to the database
server.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/max_connections/
example: 500
minimum: 1
default_transaction_isolation:
type: string
description: Sets the default transaction isolation level for new transactions.
externalDocs:
url: >-
https://postgresqlco.nf/doc/en/param/default_transaction_isolation/
example: read committed
enum:
- read committed
- repeatable read
- serializable
ssl_min_protocol_version:
type: string
description: >-
Sets the minimum SSL/TLS protocol version allowed for client
connections.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/ssl_min_protocol_version/
example: TLSv1.3
enum:
- TLSv1
- TLSv1.1
- TLSv1.2
- TLSv1.3
maintenance_work_mem:
type:
- string
- integer
description: Sets the maximum memory to be used for maintenance operations.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/maintenance_work_mem/
example: 64MB
minimum: 64
work_mem:
type:
- string
- integer
description: >-
Sets the amount of memory Postgres will use for internal operations
like sorting and hashing as part of executing a query.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/work_mem/
example: 4MB
minimum: 64
effective_cache_size:
type:
- string
- integer
description: Sets the planner's assumption about the total size of data caches.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/effective_cache_size/
example: 4GB
minimum: 8
random_page_cost:
type:
- string
- number
description: >-
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.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/random_page_cost/
example: 1.1
minimum: 0
effective_io_concurrency:
type:
- string
- integer
description: >-
Number of concurrent disk I/O operations the planner expects. Higher
values (100-200) benefit SSDs.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/effective_io_concurrency/
example: 200
minimum: 0
max_worker_processes:
type:
- string
- integer
description: >-
Maximum number of background processes the system can support.
Includes parallel query workers, logical replication, and more.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/max_worker_processes/
example: 8
minimum: 0
max_parallel_workers:
type:
- string
- integer
description: >-
Maximum number of workers that can be used for parallel operations.
Cannot exceed max_worker_processes.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/max_parallel_workers/
example: 4
minimum: 0
max_parallel_workers_per_gather:
type:
- string
- integer
description: >-
Maximum number of parallel workers per executor node for parallel
queries. Use 0 to disable parallel queries.
externalDocs:
url: >-
https://postgresqlco.nf/doc/en/param/max_parallel_workers_per_gather/
example: 2
minimum: 0
max_parallel_maintenance_workers:
type:
- string
- integer
description: >-
Maximum number of parallel workers for maintenance operations like
CREATE INDEX and VACUUM.
externalDocs:
url: >-
https://postgresqlco.nf/doc/en/param/max_parallel_maintenance_workers/
example: 2
minimum: 0
statement_timeout:
type:
- string
- integer
description: >-
Abort any statement that runs longer than the specified time. Use 0
to disable.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/statement_timeout/
example: 60s
minimum: 0
lock_timeout:
type:
- string
- integer
description: >-
Abort any statement that waits longer than the specified time while
attempting to acquire a lock. Use 0 to disable.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/lock_timeout/
example: 10s
minimum: 0
idle_session_timeout:
type:
- string
- integer
description: >-
Terminate any session that has been idle for longer than the
specified time. Use 0 to disable.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/idle_session_timeout/
example: 2m
minimum: 0
idle_in_transaction_session_timeout:
type:
- string
- integer
description: >-
Terminate any session that has been idle within an open transaction
for longer than the specified time. Use 0 to disable.
externalDocs:
url: >-
https://postgresqlco.nf/doc/en/param/idle_in_transaction_session_timeout/
example: 2h
minimum: 0
transaction_timeout:
type:
- string
- integer
description: >-
Terminate any statement that takes more than the specified time,
even while active. Use 0 to disable.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/transaction_timeout/
example: 120s
minimum: 0
wal_sender_timeout:
type:
- string
- integer
description: >-
Terminate replication connections that are inactive for longer than
this time. Use 0 to disable.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/wal_sender_timeout/
example: 120m
minimum: 0
wal_keep_size:
type:
- string
- integer
description: >-
Minimum size of past WAL files kept in pg_wal for standby servers.
Use 0 to disable.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/wal_keep_size/
example: 1GB
minimum: 0
min_wal_size:
type:
- string
- integer
description: >-
Minimum size to shrink the WAL to. WAL files are recycled rather
than removed when below this size.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/min_wal_size/
example: 80MB
minimum: 32768
max_wal_size:
type:
- string
- integer
description: >-
Maximum size WAL can grow between checkpoints. Larger values improve
write performance but increase crash recovery time.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/max_wal_size/
example: 5GB
minimum: 32768
max_slot_wal_keep_size:
type:
- string
- integer
description: >-
Specifies the maximum size of WAL files that replication slots are
allowed to retain. Use -1 for unlimited.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/max_slot_wal_keep_size/
example: '-1'
minimum: 0
wal_compression:
type: string
description: >-
Compress full-page writes in WAL. Reduces I/O at the cost of CPU.
Options vary by PostgreSQL version.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/wal_compression/
example: 'off'
enum:
- 'off'
- 'on'
- lz4
- zstd
autovacuum_max_workers:
type:
- string
- integer
description: >-
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.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/autovacuum_max_workers/
example: 8
minimum: 1
autovacuum_naptime:
type:
- string
- integer
description: >-
Minimum delay between autovacuum runs. Lower values make autovacuum
check for work more frequently.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/autovacuum_naptime/
example: 5s
minimum: 1
autovacuum_work_mem:
type:
- string
- integer
description: >-
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.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/autovacuum_work_mem/
example: 64000kB
minimum: 1024
autovacuum_vacuum_scale_factor:
type:
- string
- number
description: >-
Fraction of a table's rows that must change before autovacuum runs.
Lower values vacuum large tables more frequently.
externalDocs:
url: >-
https://postgresqlco.nf/doc/en/param/autovacuum_vacuum_scale_factor/
example: 0.2
minimum: 0
autovacuum_analyze_scale_factor:
type:
- string
- number
description: >-
Fraction of a table's rows that must change before autovacuum runs
ANALYZE to refresh planner statistics.
externalDocs:
url: >-
https://postgresqlco.nf/doc/en/param/autovacuum_analyze_scale_factor/
example: 0.1
minimum: 0
autovacuum_vacuum_insert_scale_factor:
type:
- string
- number
description: >-
Fraction of a table's rows that must be inserted before autovacuum
runs. Helps vacuum insert-heavy, rarely-updated tables.
externalDocs:
url: >-
https://postgresqlco.nf/doc/en/param/autovacuum_vacuum_insert_scale_factor/
example: 0.2
minimum: 0
autovacuum_vacuum_cost_limit:
type:
- string
- integer
description: >-
Cost-accounting limit shared across all autovacuum workers before
they pause. Use -1 to inherit vacuum_cost_limit.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/autovacuum_vacuum_cost_limit/
example: '-1'
minimum: 1
autovacuum_vacuum_cost_delay:
type:
- string
- integer
description: >-
Time autovacuum sleeps when the cost limit is reached. Lower values
speed up vacuuming at the cost of more I/O.
externalDocs:
url: https://postgresqlco.nf/doc/en/param/autovacuum_vacuum_cost_delay/
example: 2ms
minimum: 0
additionalProperties: false
minProperties: 1
example:
max_connections: 100
pgBouncerConfig:
type: object
title: PgBouncer Configuration
description: >-
PgBouncer [runtime configuration](https://www.pgbouncer.org/config.html)
configuration.
additionalProperties:
type: string
description: Any PgBouncer configuration parameter.
minProperties: 1
maxProperties: 64
example:
default_pool_size: '16'
pgTags:
type: array
items:
$ref: '#/components/schemas/ResourceTagsV1'
maxItems: 50
title: Postgres Tags
description: >-
Tags associated with the Postgres service. Tag keys starting with “chc_”
are reserved for internal use.
pgProvider:
type: string
enum:
- aws
title: Cloud provider
description: The cloud provider for a Postgres service.
pgRegion:
type: string
title: Service region
description: The cloud region for a Postgres service.
pgVersion:
type: string
title: Postgres major version
enum:
- '18'
- '17'
pgSize:
type: string
title: VM size
description: The VM size for a Postgres service.
enum:
- c6gd.large
- c6gd.xlarge
- c6gd.2xlarge
- c6gd.4xlarge
- c6gd.8xlarge
- c6gd.16xlarge
- i7i.large
- i7i.xlarge
- i7i.2xlarge
- i7i.4xlarge
- i7i.8xlarge
- i7i.12xlarge
- i7i.16xlarge
- i7i.24xlarge
- i7ie.large
- i7ie.xlarge
- i7ie.2xlarge
- i7ie.3xlarge
- i7ie.6xlarge
- i7ie.12xlarge
- i7ie.18xlarge
- i7ie.24xlarge
- i8g.large
- i8g.xlarge
- i8g.2xlarge
- i8g.4xlarge
- i8g.8xlarge
- i8g.16xlarge
- i8g.24xlarge
- i8ge.large
- i8ge.xlarge
- i8ge.2xlarge
- i8ge.3xlarge
- i8ge.6xlarge
- i8ge.12xlarge
- i8ge.18xlarge
- i8ge.24xlarge
- m6gd.large
- m6gd.xlarge
- m6gd.2xlarge
- m6gd.4xlarge
- m6gd.8xlarge
- m6gd.16xlarge
- m6id.large
- m6id.xlarge
- m6id.2xlarge
- m6id.4xlarge
- m6id.8xlarge
- m6id.16xlarge
- m8gd.large
- m8gd.xlarge
- m8gd.2xlarge
- m8gd.4xlarge
- m8gd.8xlarge
- m8gd.16xlarge
- r6gd.medium
- r6gd.large
- r6gd.xlarge
- r6gd.2xlarge
- r6gd.4xlarge
- r6gd.8xlarge
- r6gd.12xlarge
- r6gd.16xlarge
- r6id.large
- r6id.xlarge
- r6id.2xlarge
- r6id.4xlarge
- r6id.8xlarge
- r6id.12xlarge
- r6id.16xlarge
- r6id.24xlarge
- r6id.32xlarge
- r8gd.medium
- r8gd.large
- r8gd.xlarge
- r8gd.2xlarge
- r8gd.4xlarge
- r8gd.8xlarge
- r8gd.12xlarge
- r8gd.16xlarge
- r8gd.24xlarge
- r8gd.48xlarge
pgHaType:
type: string
description: >-
Type of high availability: “none” for no replication, “async” for
asynchronous replication to a single standby, and “sync” for synchronous
replication to two standbys.
enum:
- none
- async
- sync
pgIdProperty:
type: string
title: Unique Postgres service ID
format: uuid
example: f71df78e-ddad-82d0-8dfa-abbec741b82e
pgStorageSize:
type: integer
title: Storage Size
description: >-
The storage size, in GiB, which must be supported by the specified
`size`.
pgStateProperty:
type: string
title: Postgres Service State
description: Current state of the service
enum:
- creating
- restarting
- running
- replaying_wal
- restoring_backup
- finalizing_restore
- unavailable
- stopped
- deleting
pgCreatedAtProperty:
type: string
format: date-time
title: Postgres Service creation timestamp
example: '2026-03-26T20:51:16.384Z'
pgIsPrimaryProperty:
type: boolean
title: Postgres Service is Primary
description: True if this service is the primary service in the data warehouse
default: false
ResourceTagsV1:
type: object
properties:
key:
type: string
description: Tag key. Must be alphanumeric with dashes, underscores and dots.
minLength: 1
maxLength: 128
pattern: ^[a-zA-Z0-9._-]+$
value:
type: string
description: Tag value. Must be alphanumeric with dashes, underscores and dots.
maxLength: 256
pattern: ^[a-zA-Z0-9._-]+$
required:
- key
example:
key: Environment
value: staging
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Use key ID and key secret obtained in ClickHouse Cloud console:
https://clickhouse.com/docs/cloud/manage/openapi
````