From 3be5ec69a11d9769c8fd98d82e0d17237ea286ed Mon Sep 17 00:00:00 2001 From: "David E. Wheeler" Date: Tue, 26 May 2026 14:01:46 +0200 Subject: [PATCH] Update Postgres FAQ & OpenAPI docs Uncomment and correct the APIs that weren't yet implemented at the time I originally wrote the docs. Also change the IDs from UBIDs to UUIDs and remove `storageSize` from requests, as it's no longer needed. Update the FAQ with information about Query Performance Insights, link to the OpenAPI docs, fix the number of extensions, and do some mild copy editing. --- docs/cloud/managed-postgres/faq.md | 16 +++--- docs/cloud/managed-postgres/openapi.md | 80 +++++++++++++++----------- 2 files changed, 52 insertions(+), 44 deletions(-) diff --git a/docs/cloud/managed-postgres/faq.md b/docs/cloud/managed-postgres/faq.md index d2b764a4beb..2993e136ab0 100644 --- a/docs/cloud/managed-postgres/faq.md +++ b/docs/cloud/managed-postgres/faq.md @@ -17,9 +17,7 @@ import BetaBadge from '@theme/badges/BetaBadge'; You can monitor CPU, memory, IOPS, and storage usage directly from the ClickHouse Cloud console in the **Monitoring** tab of your Managed Postgres instance. -:::note -Query Performance Insights for detailed query analysis is coming soon. -::: +In addition, you can explore [Query Performance Insights](https://clickhouse.com/blog/postgres-query-insights-clickhouse-cloud) for detailed analysis of your queries in the **Query Insights** tab. ## Backup and recovery {#backup-and-recovery} @@ -33,13 +31,13 @@ For complete details on backup frequency, retention, and how to perform point-in ### Is Terraform support available for Managed Postgres? {#terraform-support} -Terraform support for Managed Postgres isn't currently available. We recommend using the ClickHouse Cloud console to create and manage your instances. +Terraform support for Managed Postgres isn't currently available. We recommend using the ClickHouse Cloud console or [OpenAPI](openapi.md) to create and manage your instances. ## Extensions and configuration {#extensions-and-configuration} ### What extensions are supported? {#extensions-supported} -Managed Postgres includes 100+ PostgreSQL extensions, including popular ones like PostGIS, pgvector, pg_cron, and many more. For the complete list of available extensions and installation instructions, see the [Extensions](/cloud/managed-postgres/extensions) documentation. +Managed Postgres includes over 90 PostgreSQL extensions, including popular ones like PostGIS, pgvector, pg_cron, and many more. For the complete list of available extensions and installation instructions, see the [Extensions](/cloud/managed-postgres/extensions) documentation. ### Can I customize PostgreSQL configuration parameters? {#config-customization} @@ -55,7 +53,7 @@ If you need a parameter that isn't currently available, contact [support](https: Managed Postgres runs PgBouncer in **transaction pooling** mode. In this mode, a backend Postgres connection is only assigned to your client for the duration of a single transaction, then returned to the pool — the next transaction from the same client may land on a different backend. -That breaks **server-side prepared statements**, which are tied to the specific backend that ran the `PREPARE` (or the extended-query `Parse`). When the matching `Execute` lands on a different backend, you get errors like: +That breaks **server-side prepared statements**, which are tied to the specific backend that ran the `PREPARE` (or the extended-query `Parse`). When the matching `EXECUTE` lands on a different backend, you get errors like: ```text ERROR: prepared statement "..." does not exist @@ -78,14 +76,14 @@ Symptoms that often trace back to this same root cause: | **JDBC** (Java) | `prepareThreshold=0` | | **node-postgres / pg** (Node.js) | Don't pass a `name` to `query()` (named queries become server-prepared) | -If your workload depends on prepared statements, connect **directly to PostgreSQL** (port 5432) instead of going through the PgBouncer pooler — direct connections support prepared statements normally. See [Connection](/cloud/managed-postgres/connection) for details on choosing between the pooled and direct endpoints. +If your workload depends on prepared statements, connect **directly to PostgreSQL** (port 5432) rather than the PgBouncer pooler — direct connections support prepared statements normally. See [Connection](/cloud/managed-postgres/connection) for details on choosing between the pooled and direct endpoints. -### What does the "max_client_conn" setting in PgBouncer mean, and how does it relate to `max_connections` in Postgres? {#pgbouncer-vs-pg-connections} +### What does the `max_client_conn` setting in PgBouncer mean, and how does it relate to `max_connections` in Postgres? {#pgbouncer-vs-pg-connections} They control different things: - **Postgres `max_connections`** caps the number of **backend** connections to PostgreSQL itself. This is the expensive number — each backend uses memory and a process slot. -- **PgBouncer `max_client_conn`** caps the number of **client** connections that can be open to the pooler at once. PgBouncer multiplexes these many client connections onto a much smaller set of backend connections. +- **PgBouncer `max_client_conn`** caps the number of **client** connections that can be open in the pooler at once. PgBouncer multiplexes these many client connections onto a much smaller set of backend connections. A typical Managed Postgres instance is configured so PgBouncer accepts roughly **10× more client connections than there are Postgres backends** (e.g. 5000 client / 500 backend). If you see connection errors at the pooler, you're far more likely to be hitting a per-pool backend limit (`default_pool_size`) than the headline client limit. diff --git a/docs/cloud/managed-postgres/openapi.md b/docs/cloud/managed-postgres/openapi.md index 69346e19fc5..76bc65262d3 100644 --- a/docs/cloud/managed-postgres/openapi.md +++ b/docs/cloud/managed-postgres/openapi.md @@ -34,17 +34,13 @@ curl -s --user "$KEY_ID:$KEY_SECRET" https://api.clickhouse.cloud/v1/organizatio ## Organization ID {#organization-id} -Next you'll need your organization ID. +Next you'll need your organization ID. 1. Select your organization name in the lower left corner of the console. 2. Select **Organization details**. 3. Hit the copy icon to the right of **Organization ID** to copy it directly to your clipboard. - - ## CRUD {#crud} Let's explore the lifecycle of a Postgres service. @@ -91,7 +92,6 @@ of the request: * `region`: Region within the provider's network in which to deploy the service * `size`: The VM size -* `storageSize`: The storage size for the VM See the [create API] docs for the possible values for these properties. In addition, let's specify Postgres 18 rather than the default, 17: @@ -102,8 +102,7 @@ create_data='{ "provider": "aws", "region": "us-west-2", "postgresVersion": "18", - "size": "r8gd.large", - "storageSize": 118 + "size": "r8gd.large" }' ``` @@ -122,7 +121,7 @@ including connection data: ```json { "result": { - "id": "pg7myrd1j06p3gx4zrm2ze8qz6", + "id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6", "name": "my postgres", "provider": "aws", "region": "us-west-2", @@ -148,7 +147,7 @@ including connection data: Use the `id` from the response to fetch the service again: ```bash -PG_ID=pg7myrd1j06p3gx4zrm2ze8qz6 +PG_ID=67b4bc12-8582-45d0-8806-fe9b2e5a54e6 curl -s --user "$KEY_ID:$KEY_SECRET" \ "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \ | jq @@ -181,7 +180,7 @@ psql (18.3) SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql) Type "help" for help. -postgres=# +postgres=# ``` Type `\q` to exit [psql]. @@ -203,7 +202,7 @@ The returned data should include the new tags: ```json { - "id": "$PG_ID", + "id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6", "name": "my postgres", "provider": "aws", "region": "us-west-2", @@ -226,10 +225,6 @@ The returned data should include the new tags: } ``` -