Managed Postgres OpenAPI

Beta

使用 ClickHouse OpenAPI 以编程方式管理您的 Managed Postgres 服务，就像管理 ClickHouse 服务一样。该 API 还提供了一个 [Prometheus 端点]，用于抓取服务指标。已熟悉 OpenAPI？获取您的 [API 密钥] 后，直接前往 Managed Postgres API reference。否则，请继续阅读，快速了解一下。

API 密钥

使用 ClickHouse OpenAPI 需要身份验证；有关如何创建 API 密钥，请参见 [API 密钥]。然后按如下方式通过 basic auth 凭据使用它们：

KEY_ID=mykeyid
KEY_SECRET=mykeysecret

curl -s --user "$KEY_ID:$KEY_SECRET" https://api.clickhouse.cloud/v1/organizations | jq

组织 ID

接下来，您需要获取组织 ID。

在控制台左下角选择您的组织名称。
选择 组织详细信息。
点击 Organization ID 右侧的复制图标，直接将其复制到剪贴板。

现在可以像这样在请求中使用它：

ORG_ID=myorgid

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres" | jq

现在，你已经发出了第一个 Postgres API 请求：list API 列出了你的组织中的所有 Postgres 服务器。输出应类似于：

{
  "result": [
    {
      "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
}

增删改查

让我们来看看 Postgres 服务的生命周期。

创建

首先，使用 create API 创建一个新的实例。请求的 JSON 正文中需要包含以下属性：

name：新 Postgres 服务的名称
provider：云服务商名称
region：云服务商网络中部署服务的区域
size：VM 规格

这些属性的可选值请参阅 create API 文档。此外，这里指定使用 Postgres 18，而不是默认的 17：

create_data='{
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large"
}'

现在使用这些数据创建一个新实例；请注意，这需要设置 Content-Type 标头：

curl -s --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres" \
    -d "$create_data" | jq

成功后，系统会创建一个新实例，并返回其实例信息，其中包括连接数据：

{
  "result": {
    "id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6",
    "name": "my postgres",
    "provider": "aws",
    "region": "us-west-2",
    "postgresVersion": "18",
    "size": "r8gd.large",
    "storageSize": 118,
    "haType": "none",
    "tags": [],
    "connectionString": "postgres://postgres:vV6cfEr2p_-TzkCDrZOx@my-postgres-6d8d2e3e.pg7myrd1j06p3gx4zrm2ze8qz6.c0.us-west-2.aws.pg.clickhouse-dev.com:5432/postgres?channel_binding=require",
    "username": "postgres",
    "password": "vV6cfEr2p_-TzkCDrZOx",
    "hostname": "my-postgres-6d8d2e3e.pg7myrd1j06p3gx4zrm2ze8qz6.c0.us-west-2.aws.pg.clickhouse-dev.com",
    "isPrimary": true,
    "state": "creating"
  },
  "requestId": "a5957990-dbe5-46fd-b5ce-a7f8f79e50fe",
  "status": 200
}

查询

使用响应中的 id 再次查询该服务：

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

输出将与创建时返回的 JSON 类似，但请留意 state；当其变为 running 时，服务器即表示已就绪：

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq .result.state

"running"

现在，您可以使用 connectionString 属性连接，例如通过 psql：

$ psql "$(
    curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq -r .result.connectionString
)"

psql (18.3)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql)
Type "help" for help.

postgres=#

输入 \q 退出 psql。

更新

patch API 支持通过 RFC 7396 JSON Merge Patch 更新 Managed Postgres 服务的部分属性。对于复杂部署，标签可能尤其有用；只需在请求中单独发送标签即可：

curl -sX PATCH --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    -d '{"tags": [{"key": "Environment", "value": "production"}]}' \
    | jq .result

返回的数据中应包含新的标签：

{
  "id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6",
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large",
  "storageSize": 118,
  "haType": "none",
  "tags": [
    {
      "key": "Environment",
      "value": "production"
    }
  ],
  "connectionString": "postgres://postgres:vV6cfEr2p_-TzkCDrZOx@my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com:5432/postgres?channel_binding=require",
  "username": "postgres",
  "password": "vV6cfEr2p_-TzkCDrZOx",
  "hostname": "my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com",
  "isPrimary": true,
  "state": "running"
}

OpenAPI 提供了额外的端点，用于更新 patch API 不支持的属性。例如，要更新 Postgres configuration，请使用 config API：

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 '{"pgConfig": {"max_connections": "42"}, "pgBouncerConfig": {}}' | jq

输出将显示更新后的配置，以及一条说明该更改后果的消息：

{
  "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
}

删除

使用[删除 API]删除 Postgres 服务。

注意

删除 Postgres 服务会彻底移除该服务及其全部数据。删除服务前，请务必先确认您已完成备份，或已将某个副本提升为主节点。

curl -sX DELETE --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq

成功时，响应会返回状态码 200，例如：

{
  "requestId": "ac9bbffa-e370-410c-8bdd-bd24bf3d7f82",
  "status": 200
}

监控

两个与 Prometheus 兼容的端点会公开 Managed Postgres 服务的 CPU、内存、I/O、连接和事务指标：一个返回组织中所有服务的指标，另一个返回单个服务的指标。有关设置，请参阅 Prometheus endpoint 页面；有关完整指标列表，请参阅 metrics reference。

API 密钥​

组织 ID​

增删改查​

创建​

查询​

更新​

删除​

监控​

API 密钥

组织 ID

增删改查

创建

查询

更新

删除

监控