From a5236082c9eba32dd2e4a7f5115f6b1d83da1599 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 26 May 2026 12:13:03 +0000 Subject: [PATCH] docs: update Postgres FAQ & OpenAPI docs --- products/managed-postgres/faq.mdx | 16 +++--- products/managed-postgres/openapi.mdx | 72 +++++++++++++++------------ 2 files changed, 48 insertions(+), 40 deletions(-) diff --git a/products/managed-postgres/faq.mdx b/products/managed-postgres/faq.mdx index bb288b09..f259af2f 100644 --- a/products/managed-postgres/faq.mdx +++ b/products/managed-postgres/faq.mdx @@ -17,9 +17,7 @@ import PrivatePreviewBadge from "/snippets/components/PrivatePreviewBadge/Privat You can monitor CPU, memory, IOPS, and storage usage directly from the ClickHouse Cloud console in the **Monitoring** tab of your Managed Postgres instance. - -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](/products/managed-postgres/openapi) 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](/products/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](/products/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](/products/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](/products/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/products/managed-postgres/openapi.mdx b/products/managed-postgres/openapi.mdx index 97d4be3b..d593c9e8 100644 --- a/products/managed-postgres/openapi.mdx +++ b/products/managed-postgres/openapi.mdx @@ -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. -{/* - -TODO: Uncomment and insert correct example output when the API ships. - Now can use it in your requests, like so: ```bash @@ -62,11 +58,18 @@ like: { "result": [ { - "id": "c0d0b15d-5e8b-431d-8943-51b6e233e0b1", - "name": "Customer's Organization", - "createdAt": "2026-03-24T14:21:31Z", - "privateEndpoints": [], - "enableCoreDumps": true + "id": "ee2fef9f-b443-8ad0-8c9b-724390cdb826", + "name": "oltp", + "provider": "aws", + "region": "eu-west-2", + "postgresVersion": "18", + "size": "r6gd.medium", + "storageSize": 59, + "haType": "none", + "tags": [], + "isPrimary": true, + "state": "running", + "createdAt": "2026-05-25T16:42:16+00:00" } ], "requestId": "c128d830-5769-4c82-8235-f79aa69d1ebf", @@ -74,8 +77,6 @@ like: } ``` -*/} - ## 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: } ``` -{/* - -TODO: Expand once implemented. - The OpenAPI provides additional endpoints to update properties not supported by the [patch API]. For example, to update the [Postgres configuration], use the [config API]: @@ -237,15 +232,30 @@ use the [config API]: ```bash curl -s --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \ "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/config" \ - -d '{"max_connections": "42"}' + -d '{"pgConfig": {"max_connections": "42"}, "pgBouncerConfig": {}}' | jq ``` -The output will show the updated configuration: +The output will show the updated configuration as well as a message describing +the consequences of the change: ```json -{"max_connections": "42"} +{ + "result":{ + "pgConfig": { + "max_connections": "42" + }, + "pgBouncerConfig": {}, + "message": "The changes in the following parameters require a database restart to take effect: max_connections. You can restart the database by using the restart endpoint." + }, + "requestId":"fdec06f2-66f7-45b4-9f82-0c051aba20aa", + "status": 200 +} ``` +{/* + +TODO: Uncomment and insert correct example output when the API ships. + Additional update APIs include: * Reset superuser password @@ -281,11 +291,11 @@ On success, the response will report status code 200, e.g.: ## Monitoring {#monitoring} -Two Prometheus-compatible endpoints expose CPU, memory, I/O, connection, -and transaction metrics for Managed Postgres services: one returns -metrics for every service in the organization, the other for a single -service. See the [Prometheus endpoint] page for setup and the -[metrics reference] for the full list of metrics. +Two Prometheus-compatible endpoints expose CPU, memory, I/O, connection, and +transaction metrics for Managed Postgres services: one returns metrics for +every service in the organization, the other for a single service. See the +[Prometheus endpoint] page for setup and the [metrics reference] for the full +list of metrics. [ClickHouse OpenAPI]: /products/cloud/features/admin-features/api "Cloud API" [OpenAPI]: https://www.openapis.org "OpenAPI Initiative"