Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Create a read replica for a Postgres service

Beta
POST/v1/organizations/{organizationId}/postgres/{postgresId}/readReplica
API playground

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

Permission

The API key must have the control-plane:postgres-service:manage and control-plane:organization:create-service permissions.

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

  • 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}
    64 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"
    • default_toast_compressionoptionalpglzorlz4

      Sets the default compression method for compressible values stored out of line (TOAST).

      Example: "lz4"
    • 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
    • shared_memory_percentoptionalstring | integer

      Percent of VM memory reserved for the shared_memory, from 25% to 75%. shared_buffers sized to fit in it. Limited to 50% on VMs with memory less or equal 16GB

      maximum: 75, minimum: 25
      Example: 25
    • temp_buffersoptionalstring | integer

      Sets the maximum memory each session uses for temporary table buffers.

      minimum: 800
      Example: "8MB"
    • hash_mem_multiplieroptionalstring | integer

      Multiple of work_mem that hash-based operations may use.

      maximum: 1000, minimum: 1
      Example: 2
    • enable_parallel_hashoptionalonoroff

      Enables the planner's use of parallel hash plans.

      Example: "on"
    • maintenance_io_concurrencyoptionalstring | integer

      Number of concurrent disk I/O operations used for maintenance work such as vacuum.

      maximum: 1000, minimum: 0
      Example: 10
    • io_methodoptionalsyncorworkerorio_uring

      Selects the method used to perform asynchronous I/O. Postgres 18 and later.

      Example: "worker"
    • io_workersoptionalstring | integer

      Number of I/O worker processes used when io_method is worker. Postgres 18 only.

      maximum: 32, minimum: 1
      Example: 3
    • io_min_workersoptionalstring | integer

      Minimum number of I/O worker processes kept running when io_method is worker. Postgres 19 and later.

      maximum: 32, minimum: 1
      Example: 2
    • io_max_workersoptionalstring | integer

      Maximum number of I/O worker processes started when io_method is worker. Postgres 19 and later.

      maximum: 32, minimum: 1
      Example: 8
    • bgwriter_delayoptionalstring | integer

      Sleep time between background writer activity rounds.

      maximum: 10000, minimum: 10
      Example: "200ms"
    • bgwriter_flush_afteroptionalstring | integer

      Amount of data written by the background writer after which the OS is asked to flush it to disk.

      maximum: 2048, minimum: 0
      Example: "512kB"
    • bgwriter_lru_maxpagesoptionalstring | integer

      Maximum number of buffers the background writer writes per round.

      maximum: 1073741823, minimum: 0
      Example: 100
    • bgwriter_lru_multiplieroptionalstring | integer

      Multiple of the average recent buffer demand that the background writer cleans per round.

      maximum: 10, 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"
    • checkpoint_timeoutoptionalstring | integer

      Sets the maximum time between automatic WAL checkpoints.

      maximum: 3600, minimum: 30
      Example: "5min"
    • 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: "lz4"
    • wal_buffersoptionalstring | integer

      Sets the number of disk-page buffers in shared memory for WAL. A number without a unit is in 8 kB pages.

      maximum: 262144, minimum: 32
      Example: "16MB"
    • max_replication_slotsoptionalstring | integer

      Maximum number of replication slots. Standbys and logical replication each use slots.

      maximum: 262143, minimum: 10
      Example: 10
    • max_wal_sendersoptionalstring | integer

      Maximum number of simultaneously running WAL sender processes.

      maximum: 262143, minimum: 10
      Example: 10
    • max_logical_replication_workersoptionalstring | integer

      Maximum number of logical replication workers for subscriptions on this server.

      maximum: 262143, minimum: 0
      Example: 4
    • max_repack_replication_slotsoptionalstring | integer

      Replication slots reserved for REPACK CONCURRENTLY, separate from max_replication_slots. Postgres 19 and later.

      maximum: 262143, minimum: 0
      Example: 5
    • max_sync_workers_per_subscriptionoptionalstring | integer

      Maximum number of table synchronization workers per subscription.

      maximum: 262143, minimum: 0
      Example: 2
    • logical_decoding_work_memoptionalstring | integer

      Maximum memory used for logical decoding before changes spill to disk.

      minimum: 64
      Example: "64MB"
    • 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_max_parallel_workersoptionalstring | integer

      Maximum number of parallel workers a single autovacuum worker can use. 0 (the default) turns parallel autovacuum off. Postgres 19 and later.

      maximum: 1024, minimum: 0
      Example: 2
    • 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_thresholdoptionalstring | integer

      Minimum number of tuple updates or deletes prior to vacuum.

      maximum: 2147483647, minimum: 0
      Example: 50
    • autovacuum_analyze_thresholdoptionalstring | integer

      Minimum number of tuple inserts, updates, or deletes prior to analyze.

      maximum: 2147483647, minimum: 0
      Example: 50
    • autovacuum_vacuum_insert_thresholdoptionalstring | integer

      Minimum number of tuple inserts prior to vacuum, or -1 to disable insert vacuums.

      maximum: 2147483647, minimum: -1
      Example: 1000
    • autovacuum_freeze_max_ageoptionalstring | integer

      Age at which to autovacuum a table to prevent transaction ID wraparound.

      maximum: 2000000000, minimum: 100000
      Example: 200000000
    • 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"
    • vacuum_cost_delayoptionalstring | integer

      Time in milliseconds a manual VACUUM sleeps when its cost limit is exceeded. 0 disables cost-based delay.

      maximum: 100, minimum: 0
      Example: "0"
    • log_min_duration_statementoptionalstring | integer

      Logs statements that run at least this many milliseconds. 0 logs all statements; -1 disables.

      maximum: 2147483647, minimum: -1
      Example: 1000
    • log_temp_filesoptionalstring | integer

      Logs temporary files of at least this size in kilobytes. 0 logs all temporary files; -1 disables.

      maximum: 2147483647, minimum: -1
      Example: "-1"
    • log_lock_waitsoptionalonoroff

      Logs a message when a session waits longer than deadlock_timeout to acquire a lock.

      Example: "off"
    • log_parameter_max_lengthoptionalstring | integer

      Maximum bytes of each bind parameter value logged with statements. 0 disables; -1 logs values in full.

      maximum: 1073741823, minimum: -1
      Example: "-1"
    • track_activity_query_sizeoptionalstring | integer

      Bytes reserved to store the text of the currently running command of each session, shown in pg_stat_activity.

      maximum: 1048576, minimum: 100
      Example: 4096
  • 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
    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