Skip to content

Update Postgres FAQ & OpenAPI docs #6280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
theory merged 1 commit into from
May 26, 2026
+52 −44
Merged

Update Postgres FAQ & OpenAPI docs #6280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 7 additions & 9 deletions docs/cloud/managed-postgres/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,7 @@

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}

Expand All @@ -33,13 +31,13 @@

### 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.

Check warning on line 34 in docs/cloud/managed-postgres/faq.md

View workflow job for this annotation

GitHub Actions / vale

ClickHouse.CurrentStatus 

Remove 'currently'. The documentation reflects the current state of the product.

## 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}

Expand All @@ -55,7 +53,7 @@

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
Expand All @@ -78,14 +76,14 @@
| **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.

Expand Down
80 changes: 45 additions & 35 deletions docs/cloud/managed-postgres/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,17 +34,13 @@

## 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
Expand All @@ -62,20 +58,25 @@
{
"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",
"status": 200
}
```

-->

## CRUD {#crud}

Let's explore the lifecycle of a Postgres service.
Expand All @@ -91,7 +92,6 @@
* `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:
Expand All @@ -102,8 +102,7 @@
"provider": "aws",
"region": "us-west-2",
"postgresVersion": "18",
"size": "r8gd.large",
"storageSize": 118
"size": "r8gd.large"
}'
```

Expand All @@ -122,7 +121,7 @@
```json
{
"result": {
"id": "pg7myrd1j06p3gx4zrm2ze8qz6",
"id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6",
"name": "my postgres",
"provider": "aws",
"region": "us-west-2",
Expand All @@ -148,7 +147,7 @@
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
Expand Down Expand Up @@ -181,7 +180,7 @@
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].
Expand All @@ -203,7 +202,7 @@

```json
{
"id": "$PG_ID",
"id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6",
"name": "my postgres",
"provider": "aws",
"region": "us-west-2",
Expand All @@ -226,26 +225,37 @@
}
```

<!--

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]:

```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

Check notice on line 238 in docs/cloud/managed-postgres/openapi.md

View workflow job for this annotation

GitHub Actions / vale

ClickHouse.Wordy 

Suggestion: Use 'and' instead of 'as well as'.
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
Expand Down Expand Up @@ -281,19 +291,15 @@

## 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]: /cloud/manage/cloud-api "Cloud API"
[OpenAPI]: https://www.openapis.org "OpenAPI Initiative"
[API keys]: /cloud/manage/openapi "Managing API Keys"
[Prometheus endpoint]: /cloud/managed-postgres/monitoring/prometheus
"Managed Postgres Prometheus endpoint"
[metrics reference]: /cloud/managed-postgres/monitoring/metrics
"Managed Postgres metrics reference"
[pg-openapi]: https://clickhouse.com/docs/cloud/manage/api/swagger#tag/Postgres
"OpenAPI spec for ClickHouse Cloud: Postgres"
[list API]: https://clickhouse.com/docs/cloud/manage/api/swagger#tag/Postgres/operation/postgresServiceGetList
Expand All @@ -311,3 +317,7 @@
"Update a Postgres Service configuration"
[delete API]: https://clickhouse.com/docs/cloud/manage/api/swagger#tag/Postgres/operation/postgresServiceDelete
"Delete a PostgreSQL service"
[Prometheus endpoint]: /cloud/managed-postgres/monitoring/prometheus
"Managed Postgres Prometheus endpoint"
[metrics reference]: /cloud/managed-postgres/monitoring/metrics
"Managed Postgres metrics reference"
Loading