diff --git a/crates/clickhouse-cloud-api/CHANGELOG.md b/crates/clickhouse-cloud-api/CHANGELOG.md index 566a428f..c633a470 100644 --- a/crates/clickhouse-cloud-api/CHANGELOG.md +++ b/crates/clickhouse-cloud-api/CHANGELOG.md @@ -225,6 +225,15 @@ type. Struct-literal callers need `min_auto_granularity: None`. `ClickStackCASLPermissionSubject` adds `App`; exhaustive matches without a wildcard arm need the new variant. +Breaking: `organization_roles_get_list` takes `limit: Option` and +`cursor: Option<&str>` after the organization ID, because the API now pages +the role list. A page holds at most `limit` roles (the server default and +maximum is 250), ordered by role ID; `ApiResponse::next_cursor` is set while +more pages remain and `ApiResponse::limit` echoes the page size. Migrate +`organization_roles_get_list(org)` to `organization_roles_get_list(org, None, None)`; +the request sent is unchanged, but an organization with more than 250 roles +now needs to follow `next_cursor` to see them all. + ## 0.5.1 No changes to this crate; released in lockstep with `clickhousectl` 0.5.1. diff --git a/crates/clickhouse-cloud-api/clickhouse_cloud_openapi.json b/crates/clickhouse-cloud-api/clickhouse_cloud_openapi.json index 3f2e33bf..482e9af9 100644 --- a/crates/clickhouse-cloud-api/clickhouse_cloud_openapi.json +++ b/crates/clickhouse-cloud-api/clickhouse_cloud_openapi.json @@ -5,7 +5,7 @@ "version": "1.0", "contact": { "name": "ClickHouse Support", - "url": "https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1418320", + "url": "https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1443100", "email": "support@clickhouse.com" } }, @@ -710,7 +710,7 @@ "/v1/organizations/{organizationId}/roles": { "get": { "summary": "List all available roles for an organization", - "description": "Returns all available roles (system + custom) for an organization.", + "description": "Returns available roles (system + custom) for an organization, ordered by unique role ID ascending. Results are capped at `limit` (default and maximum 250) per page. Pass `nextCursor` as the `cursor` query parameter to fetch the next page until it is null.", "operationId": "organizationRolesGetList", "parameters": [ { @@ -722,6 +722,24 @@ "type": "string", "format": "uuid" } + }, + { + "in": "query", + "name": "limit", + "description": "Maximum number of results to return.", + "schema": { + "type": "integer", + "minimum": 1, + "default": 250 + } + }, + { + "in": "query", + "name": "cursor", + "description": "Opaque cursor from a previous response's `nextCursor`, marking where to resume the list.", + "schema": { + "type": "string" + } } ], "responses": { @@ -747,6 +765,17 @@ "items": { "$ref": "#/components/schemas/RBACRole" } + }, + "limit": { + "type": "integer", + "description": "Maximum number of results returned in this page." + }, + "nextCursor": { + "type": [ + "string", + "null" + ], + "description": "Cursor for the next page, to be sent as the `cursor` query parameter. Null on the last page." } } } @@ -3832,7 +3861,7 @@ }, "post": { "summary": "Create or replace service autoscaling schedule", - "description": "Creates or fully replaces the autoscaling schedule for a service. Pass an empty `entries` array to clear the schedule \u2014 a subsequent GET will return 404, and the response will contain an empty `baseConfig` (all fields absent). The base scaling config (applied when no entry is active) is managed separately via the `replicaScaling` endpoint. Requires the scheduled autoscaling feature to be enabled for the organization. Gen 2 (v2-default) services use a fixed size and cannot idle. An entry may leave out fields it takes from the base config, but each entry combined with those fields must have equal minReplicaMemoryGb and maxReplicaMemoryGb, a fixed replica count (numReplicas, or equal minReplicas and maxReplicas), and idling off; otherwise the request is rejected.", + "description": "Creates or fully replaces the autoscaling schedule for a service. Pass an empty `entries` array to clear the schedule — a subsequent GET will return 404, and the response will contain an empty `baseConfig` (all fields absent). The base scaling config (applied when no entry is active) is managed separately via the `replicaScaling` endpoint. Requires the scheduled autoscaling feature to be enabled for the organization. Gen 2 (v2-default) services use a fixed size and cannot idle. An entry may leave out fields it takes from the base config, but each entry combined with those fields must have equal minReplicaMemoryGb and maxReplicaMemoryGb, a fixed replica count (numReplicas, or equal minReplicas and maxReplicas), and idling off; otherwise the request is rejected.", "operationId": "scalingScheduleUpsert", "parameters": [ { @@ -4188,7 +4217,7 @@ }, "put": { "summary": "Set service upgrade window", - "description": "Creates or fully replaces the upgrade window for a service. The upgrade window currently lasts 6 hours from `startHourUtc`. The upgrade window can only be set on primary services; secondary services inherit the primary service window.\n\nErrors:\n- 400: invalid field values (`weekday` not in 0\u20136, `startHourUtc` not in {0, 6, 12, 18}), or the service is a secondary service.\n- 401: missing, invalid, or disabled API key.\n- 403: caller lacks `control-plane:service:manage` on the service, or the organization does not have the scheduled upgrades feature enabled.\n- 404: service does not exist or is not visible to the caller.", + "description": "Creates or fully replaces the upgrade window for a service. The upgrade window currently lasts 6 hours from `startHourUtc`. The upgrade window can only be set on primary services; secondary services inherit the primary service window.\n\nErrors:\n- 400: invalid field values (`weekday` not in 0–6, `startHourUtc` not in {0, 6, 12, 18}), or the service is a secondary service.\n- 401: missing, invalid, or disabled API key.\n- 403: caller lacks `control-plane:service:manage` on the service, or the organization does not have the scheduled upgrades feature enabled.\n- 404: service does not exist or is not visible to the caller.", "operationId": "upgradeWindowUpdate", "parameters": [ { @@ -9630,7 +9659,7 @@ "/v1/organizations/{organizationId}/members/{userId}/notificationSettings": { "get": { "summary": "List a member's notification settings", - "description": "**Disclaimer:** This beta endpoint is evolving; the API contract may change.

Returns the notification settings an organization member has explicitly chosen. A member who has never changed a setting has none, so an empty list means every notification follows the platform default for their role \u2014 it does not mean notifications are off. Settings for notification types the member cannot use are omitted, which depends on their permissions rather than the caller's. Slack is configured for the whole organization and never appears here. A page holds at most `limit` settings (default 100, maximum 250; a larger value is clamped) and the server may return fewer. Every response carries `limit` and `nextCursor`; pass `nextCursor` as the `cursor` query parameter to fetch the next page, repeating until it is null.", + "description": "**Disclaimer:** This beta endpoint is evolving; the API contract may change.

Returns the notification settings an organization member has explicitly chosen. A member who has never changed a setting has none, so an empty list means every notification follows the platform default for their role — it does not mean notifications are off. Settings for notification types the member cannot use are omitted, which depends on their permissions rather than the caller's. Slack is configured for the whole organization and never appears here. A page holds at most `limit` settings (default 100, maximum 250; a larger value is clamped) and the server may return fewer. Every response carries `limit` and `nextCursor`; pass `nextCursor` as the `cursor` query parameter to fetch the next page, repeating until it is null.", "operationId": "memberNotificationSettingsGetList", "parameters": [ { @@ -13288,7 +13317,7 @@ }, "post": { "summary": "ClickStack: Create Source", - "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

ClickStack: Creates a new source. The request body is a source object without the `id` field. If an `id` is sent anyway it is silently ignored (stripped before validation \u2014 the request is never rejected because of it). Granularity fields (`materializedViews[].minGranularity` and `metadataMaterializedViews.granularity`) accept the same short format the API returns (e.g. `5m`, `15s`, `1h`, `1d`).", + "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

ClickStack: Creates a new source. The request body is a source object without the `id` field. If an `id` is sent anyway it is silently ignored (stripped before validation — the request is never rejected because of it). Granularity fields (`materializedViews[].minGranularity` and `metadataMaterializedViews.granularity`) accept the same short format the API returns (e.g. `5m`, `15s`, `1h`, `1d`).", "operationId": "clickStackCreateSource", "parameters": [ { @@ -13552,7 +13581,7 @@ }, "put": { "summary": "ClickStack: Update Source", - "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

ClickStack: Updates an existing source. The full source object must be provided; this is a replace, not a patch. The request body is a source object without the `id` field. If an `id` is sent anyway it is silently ignored (stripped before validation \u2014 never a 400); the path parameter alone identifies the source. Granularity fields (`materializedViews[].minGranularity` and `metadataMaterializedViews.granularity`) accept the same short format the API returns (e.g. `5m`, `15s`, `1h`, `1d`).", + "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

ClickStack: Updates an existing source. The full source object must be provided; this is a replace, not a patch. The request body is a source object without the `id` field. If an `id` is sent anyway it is silently ignored (stripped before validation — never a 400); the path parameter alone identifies the source. Granularity fields (`materializedViews[].minGranularity` and `metadataMaterializedViews.granularity`) accept the same short format the API returns (e.g. `5m`, `15s`, `1h`, `1d`).", "operationId": "clickStackUpdateSource", "parameters": [ { @@ -14775,7 +14804,7 @@ }, "delete": { "summary": "ClickStack: Delete Webhook", - "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

ClickStack: Deletes a webhook. Blocked with a 409 while any alert still references it \u2014 reassign or remove those alerts first \u2014 so deletion never leaves an alert pointing at a missing webhook (which would silently drop notifications). Mirrors the internal webhook delete guard.", + "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

ClickStack: Deletes a webhook. Blocked with a 409 while any alert still references it — reassign or remove those alerts first — so deletion never leaves an alert pointing at a missing webhook (which would silently drop notifications). Mirrors the internal webhook delete guard.", "operationId": "clickStackDeleteWebhook", "parameters": [ { @@ -16952,18 +16981,527 @@ "responses": { "200": { "description": "Successful response", - "headers": { - "Content-Disposition": { - "schema": { - "type": "string", - "example": "attachment; filename=\"postgres-ca-certificate.pem\"" - } - } - }, + "headers": { + "Content-Disposition": { + "schema": { + "type": "string", + "example": "attachment; filename=\"postgres-ca-certificate.pem\"" + } + } + }, + "content": { + "application/x-pem-file": { + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "number", + "description": "HTTP status code.", + "example": 400 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } + } + } + }, + "500": { + "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code.", + "example": 500 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } + } + } + } + }, + "security": [ + { + "basicAuth": [ + "control-plane:postgres-service:view" + ] + } + ], + "tags": [ + "Postgres" + ] + } + }, + "/v1/organizations/{organizationId}/postgres/{postgresId}/restoredService": { + "post": { + "summary": "Restore a Postgres service", + "description": "Restore a Postgres database from continuous backup, optionally at a specific point in time.", + "operationId": "postgresInstanceRestore", + "parameters": [ + { + "in": "path", + "name": "organizationId", + "description": "ID of the organization that owns the Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "in": "path", + "name": "postgresId", + "description": "ID of the requested Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostgresServiceRestoreRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "number", + "description": "HTTP status code.", + "example": 200 + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + }, + "result": { + "$ref": "#/components/schemas/PostgresService" + } + } + } + } + } + }, + "400": { + "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "number", + "description": "HTTP status code.", + "example": 400 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } + } + } + }, + "500": { + "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code.", + "example": 500 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } + } + } + } + }, + "security": [ + { + "basicAuth": [ + "control-plane:postgres-service:manage", + "control-plane:organization:create-service" + ] + } + ], + "tags": [ + "Postgres" + ] + } + }, + "/v1/organizations/{organizationId}/postgres/{postgresId}/password": { + "patch": { + "summary": "Update Postgres superuser password", + "description": "Sets a new password for a Postgres service's superuser account.", + "operationId": "postgresServiceSetPassword", + "parameters": [ + { + "in": "path", + "name": "organizationId", + "description": "ID of the organization that owns the Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "in": "path", + "name": "postgresId", + "description": "ID of the requested Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostgresServiceSetPassword" + } + } + } + }, + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "number", + "description": "HTTP status code.", + "example": 200 + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + }, + "result": { + "$ref": "#/components/schemas/PostgresServicePasswordResource" + } + } + } + } + } + }, + "400": { + "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "number", + "description": "HTTP status code.", + "example": 400 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } + } + } + }, + "500": { + "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code.", + "example": 500 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } + } + } + } + }, + "security": [ + { + "basicAuth": [ + "control-plane:postgres-service:manage" + ] + } + ], + "tags": [ + "Postgres" + ] + } + }, + "/v1/organizations/{organizationId}/postgres/{postgresId}/state": { + "patch": { + "summary": "Update Postgres service state", + "description": "Initiate a process for a Postgres service:\n* restart: Initiates a service restart\n* promote: Promotes a read replica to primary\n* switchover: Switch a primary over to a standby. If there is no standby, replace the primary with a newly provisioned server and switch over to it.\n", + "operationId": "postgresServicePatchState", + "parameters": [ + { + "in": "path", + "name": "organizationId", + "description": "ID of the organization that owns the Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "in": "path", + "name": "postgresId", + "description": "ID of the requested Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostgresServiceSetState" + } + } + } + }, + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "number", + "description": "HTTP status code.", + "example": 200 + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + }, + "result": { + "$ref": "#/components/schemas/PostgresService" + } + } + } + } + } + }, + "400": { + "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "number", + "description": "HTTP status code.", + "example": 400 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } + } + } + }, + "500": { + "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code.", + "example": 500 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } + } + } + } + }, + "security": [ + { + "basicAuth": [ + "control-plane:postgres-service:manage" + ] + } + ], + "tags": [ + "Postgres" + ] + } + }, + "/v1/organizations/{organizationId}/postgres/{postgresId}/readReplica": { + "post": { + "summary": "Create a read replica for a Postgres service", + "description": "Initiate the process to create a new read replica for a Postgres service.", + "operationId": "postgresInstanceCreateReadReplica", + "parameters": [ + { + "in": "path", + "name": "organizationId", + "description": "ID of the organization that owns the Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "in": "path", + "name": "postgresId", + "description": "ID of the requested Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostgresServiceReadReplicaRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful response", "content": { - "application/x-pem-file": { + "application/json": { "schema": { - "type": "string" + "type": "object", + "properties": { + "status": { + "type": "number", + "description": "HTTP status code.", + "example": 200 + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + }, + "result": { + "$ref": "#/components/schemas/PostgresService" + } + } } } } @@ -17024,7 +17562,8 @@ "security": [ { "basicAuth": [ - "control-plane:postgres-service:view" + "control-plane:postgres-service:manage", + "control-plane:organization:create-service" ] } ], @@ -17033,11 +17572,11 @@ ] } }, - "/v1/organizations/{organizationId}/postgres/{postgresId}/restoredService": { - "post": { - "summary": "Restore a Postgres service", - "description": "Restore a Postgres database from continuous backup, optionally at a specific point in time.", - "operationId": "postgresInstanceRestore", + "/v1/organizations/{organizationId}/postgres/{postgresId}/config": { + "get": { + "summary": "Get PostgreSQL service configuration", + "description": "Returns the configuration data for a Postgres service and its PgBouncer service.", + "operationId": "postgresInstanceConfigGet", "parameters": [ { "in": "path", @@ -17060,15 +17599,6 @@ } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PostgresServiceRestoreRequest" - } - } - } - }, "responses": { "200": { "description": "Successful response", @@ -17088,7 +17618,7 @@ "format": "uuid" }, "result": { - "$ref": "#/components/schemas/PostgresService" + "$ref": "#/components/schemas/postgresInstanceConfig" } } } @@ -17151,21 +17681,18 @@ "security": [ { "basicAuth": [ - "control-plane:postgres-service:manage", - "control-plane:organization:create-service" + "control-plane:postgres-service:view" ] } ], "tags": [ "Postgres" ] - } - }, - "/v1/organizations/{organizationId}/postgres/{postgresId}/password": { - "patch": { - "summary": "Update Postgres superuser password", - "description": "Sets a new password for a Postgres service's superuser account.", - "operationId": "postgresServiceSetPassword", + }, + "post": { + "summary": "Replace Postgres service configuration", + "description": "Replace the existing Postgres service and pgBouncer configuration.", + "operationId": "postgresInstanceConfigPost", "parameters": [ { "in": "path", @@ -17192,7 +17719,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PostgresServiceSetPassword" + "$ref": "#/components/schemas/postgresInstanceConfig" } } } @@ -17216,7 +17743,7 @@ "format": "uuid" }, "result": { - "$ref": "#/components/schemas/PostgresServicePasswordResource" + "$ref": "#/components/schemas/postgresInstanceUpdateConfigResponse" } } } @@ -17286,13 +17813,11 @@ "tags": [ "Postgres" ] - } - }, - "/v1/organizations/{organizationId}/postgres/{postgresId}/state": { + }, "patch": { - "summary": "Update Postgres service state", - "description": "Initiate a process for a Postgres service:\n* restart: Initiates a service restart\n* promote: Promotes a read replica to primary\n* switchover: Switch a primary over to a standby. If there is no standby, replace the primary with a newly provisioned server and switch over to it.\n", - "operationId": "postgresServicePatchState", + "summary": "Update Postgres service configuration", + "description": "Update the existing Postgres service and pgBouncer configuration.", + "operationId": "postgresInstanceConfigPatch", "parameters": [ { "in": "path", @@ -17319,7 +17844,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PostgresServiceSetState" + "$ref": "#/components/schemas/postgresInstanceConfig" } } } @@ -17343,7 +17868,7 @@ "format": "uuid" }, "result": { - "$ref": "#/components/schemas/PostgresService" + "$ref": "#/components/schemas/postgresInstanceUpdateConfigResponse" } } } @@ -17415,11 +17940,11 @@ ] } }, - "/v1/organizations/{organizationId}/postgres/{postgresId}/readReplica": { - "post": { - "summary": "Create a read replica for a Postgres service", - "description": "Initiate the process to create a new read replica for a Postgres service.", - "operationId": "postgresInstanceCreateReadReplica", + "/v1/organizations/{organizationId}/postgres/{postgresId}/prometheus": { + "get": { + "summary": "Get PostgreSQL service metrics", + "description": "Returns Prometheus metrics for a PostgreSQL service.", + "operationId": "postgresInstancePrometheusGet", "parameters": [ { "in": "path", @@ -17442,15 +17967,138 @@ } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PostgresServiceReadReplicaRequest" + "responses": { + "200": { + "description": "Successful response", + "content": { + "text/plain; charset=UTF-8": { + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "number", + "description": "HTTP status code.", + "example": 400 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } + } + } + }, + "500": { + "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code.", + "example": 500 + }, + "error": { + "type": "string", + "description": "Detailed error description." + }, + "requestId": { + "type": "string", + "description": "Unique id assigned to every request. UUIDv4", + "format": "uuid" + } + } + } } } } }, + "security": [ + { + "basicAuth": [ + "control-plane:postgres-service:view" + ] + } + ], + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/postgres/{postgresId}/metrics": { + "get": { + "summary": "Get Postgres time-series metrics", + "description": "Returns bucketed time-series metrics for a PostgreSQL service over the requested window (CPU, memory, disk, network, connections, cache hit ratio, throughput, transactions, wait events, lock waits, and more). Use this to chart or analyze how a service behaved over time.", + "operationId": "postgresInstanceMetricsGet", + "parameters": [ + { + "in": "path", + "name": "organizationId", + "description": "ID of the organization that owns the Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "in": "path", + "name": "postgresId", + "description": "ID of the Postgres service.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "in": "query", + "name": "from_date", + "description": "Inclusive start of the time window (RFC 3339 date-time).", + "schema": { + "type": "string", + "format": "date-time" + }, + "required": true + }, + { + "in": "query", + "name": "to_date", + "description": "Exclusive end of the time window (RFC 3339 date-time).", + "schema": { + "type": "string", + "format": "date-time" + }, + "required": true + }, + { + "in": "query", + "name": "bucket_size_seconds", + "description": "Time-series bucket size in seconds. When omitted, a bucket size is derived from the requested window. Requests are capped at 250 data points.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], "responses": { "200": { "description": "Successful response", @@ -17470,7 +18118,7 @@ "format": "uuid" }, "result": { - "$ref": "#/components/schemas/PostgresService" + "$ref": "#/components/schemas/PostgresMetrics" } } } @@ -17533,8 +18181,7 @@ "security": [ { "basicAuth": [ - "control-plane:postgres-service:manage", - "control-plane:organization:create-service" + "control-plane:postgres-service:view" ] } ], @@ -17543,11 +18190,11 @@ ] } }, - "/v1/organizations/{organizationId}/postgres/{postgresId}/config": { + "/v1/organizations/{organizationId}/postgres/{postgresId}/privateEndpoint": { "get": { - "summary": "Get PostgreSQL service configuration", - "description": "Returns the configuration data for a Postgres service and its PgBouncer service.", - "operationId": "postgresInstanceConfigGet", + "summary": "Get the PostgreSQL private endpoint", + "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

Returns the AWS private endpoint service of a Postgres service, or 404 if it has not been created. Private endpoints are available only for AWS Postgres services, and only for organizations with the feature enabled.", + "operationId": "postgresPrivateEndpointGet", "parameters": [ { "in": "path", @@ -17562,7 +18209,7 @@ { "in": "path", "name": "postgresId", - "description": "ID of the requested Postgres service.", + "description": "ID of the Postgres service.", "required": true, "schema": { "type": "string", @@ -17589,7 +18236,7 @@ "format": "uuid" }, "result": { - "$ref": "#/components/schemas/postgresInstanceConfig" + "$ref": "#/components/schemas/PostgresPrivateEndpoint" } } } @@ -17658,12 +18305,18 @@ ], "tags": [ "Postgres" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } ] }, "post": { - "summary": "Replace Postgres service configuration", - "description": "Replace the existing Postgres service and pgBouncer configuration.", - "operationId": "postgresInstanceConfigPost", + "summary": "Create the PostgreSQL private endpoint", + "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

Creates the AWS private endpoint service of a Postgres service. Creation takes about 5 to 10 minutes: `state` is `creating` until the service is `available`. A VPC endpoint can connect only after its ID is approved with the update endpoint. Private endpoints are available only for AWS Postgres services, and only for organizations with the feature enabled.", + "operationId": "postgresPrivateEndpointPost", "parameters": [ { "in": "path", @@ -17678,7 +18331,7 @@ { "in": "path", "name": "postgresId", - "description": "ID of the requested Postgres service.", + "description": "ID of the Postgres service.", "required": true, "schema": { "type": "string", @@ -17690,7 +18343,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/postgresInstanceConfig" + "$ref": "#/components/schemas/PostgresPrivateEndpointPostRequest" } } } @@ -17714,7 +18367,7 @@ "format": "uuid" }, "result": { - "$ref": "#/components/schemas/postgresInstanceUpdateConfigResponse" + "$ref": "#/components/schemas/PostgresPrivateEndpoint" } } } @@ -17783,12 +18436,18 @@ ], "tags": [ "Postgres" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } ] }, "patch": { - "summary": "Update Postgres service configuration", - "description": "Update the existing Postgres service and pgBouncer configuration.", - "operationId": "postgresInstanceConfigPatch", + "summary": "Update the PostgreSQL private endpoint", + "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

Approves VPC endpoints by ID and sets the supported regions. At least one of `allowedVpcEndpoints` and `supportedRegions` is required, and each one provided replaces the existing list in full, so include every entry to keep. Private endpoints are available only for AWS Postgres services, and only for organizations with the feature enabled.", + "operationId": "postgresPrivateEndpointPatch", "parameters": [ { "in": "path", @@ -17803,7 +18462,7 @@ { "in": "path", "name": "postgresId", - "description": "ID of the requested Postgres service.", + "description": "ID of the Postgres service.", "required": true, "schema": { "type": "string", @@ -17815,7 +18474,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/postgresInstanceConfig" + "$ref": "#/components/schemas/PostgresPrivateEndpointPatchRequest" } } } @@ -17839,7 +18498,7 @@ "format": "uuid" }, "result": { - "$ref": "#/components/schemas/postgresInstanceUpdateConfigResponse" + "$ref": "#/components/schemas/PostgresPrivateEndpoint" } } } @@ -17908,117 +18567,18 @@ ], "tags": [ "Postgres" - ] - } - }, - "/v1/organizations/{organizationId}/postgres/{postgresId}/prometheus": { - "get": { - "summary": "Get PostgreSQL service metrics", - "description": "Returns Prometheus metrics for a PostgreSQL service.", - "operationId": "postgresInstancePrometheusGet", - "parameters": [ - { - "in": "path", - "name": "organizationId", - "description": "ID of the organization that owns the Postgres service.", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "in": "path", - "name": "postgresId", - "description": "ID of the requested Postgres service.", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } ], - "responses": { - "200": { - "description": "Successful response", - "content": { - "text/plain; charset=UTF-8": { - "schema": { - "type": "string" - } - } - } - }, - "400": { - "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "status": { - "type": "number", - "description": "HTTP status code.", - "example": 400 - }, - "error": { - "type": "string", - "description": "Detailed error description." - }, - "requestId": { - "type": "string", - "description": "Unique id assigned to every request. UUIDv4", - "format": "uuid" - } - } - } - } - } - }, - "500": { - "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "status": { - "type": "integer", - "description": "HTTP status code.", - "example": 500 - }, - "error": { - "type": "string", - "description": "Detailed error description." - }, - "requestId": { - "type": "string", - "description": "Unique id assigned to every request. UUIDv4", - "format": "uuid" - } - } - } - } - } - } - }, - "security": [ + "x-badges": [ { - "basicAuth": [ - "control-plane:postgres-service:view" - ] + "name": "Beta", + "position": "after" } - ], - "tags": [ - "Prometheus" ] - } - }, - "/v1/organizations/{organizationId}/postgres/{postgresId}/metrics": { - "get": { - "summary": "Get Postgres time-series metrics", - "description": "Returns bucketed time-series metrics for a PostgreSQL service over the requested window (CPU, memory, disk, network, connections, cache hit ratio, throughput, transactions, wait events, lock waits, and more). Use this to chart or analyze how a service behaved over time.", - "operationId": "postgresInstanceMetricsGet", + }, + "delete": { + "summary": "Delete the PostgreSQL private endpoint", + "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.

Deletes the AWS private endpoint service of a Postgres service. Connections through approved VPC endpoints stop working. Private endpoints are available only for AWS Postgres services, and only for organizations with the feature enabled.", + "operationId": "postgresPrivateEndpointDelete", "parameters": [ { "in": "path", @@ -18039,35 +18599,6 @@ "type": "string", "format": "uuid" } - }, - { - "in": "query", - "name": "from_date", - "description": "Inclusive start of the time window (RFC 3339 date-time).", - "schema": { - "type": "string", - "format": "date-time" - }, - "required": true - }, - { - "in": "query", - "name": "to_date", - "description": "Exclusive end of the time window (RFC 3339 date-time).", - "schema": { - "type": "string", - "format": "date-time" - }, - "required": true - }, - { - "in": "query", - "name": "bucket_size_seconds", - "description": "Time-series bucket size in seconds. When omitted, a bucket size is derived from the requested window. Requests are capped at 250 data points.", - "schema": { - "type": "integer", - "minimum": 1 - } } ], "responses": { @@ -18087,9 +18618,6 @@ "type": "string", "description": "Unique id assigned to every request. UUIDv4", "format": "uuid" - }, - "result": { - "$ref": "#/components/schemas/PostgresMetrics" } } } @@ -18152,12 +18680,18 @@ "security": [ { "basicAuth": [ - "control-plane:postgres-service:view" + "control-plane:postgres-service:manage" ] } ], "tags": [ "Postgres" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } ] } }, @@ -26691,20 +27225,20 @@ }, "weekdays": { "type": "array", - "description": "Days of the week this entry applies to. 0 = Sunday, 1 = Monday, \u2026, 6 = Saturday.", + "description": "Days of the week this entry applies to. 0 = Sunday, 1 = Monday, …, 6 = Saturday.", "items": { "type": "integer" }, "minItems": 1 }, "startHourUtc": { - "description": "UTC hour (0\u201323) when this entry becomes active (inclusive).", + "description": "UTC hour (0–23) when this entry becomes active (inclusive).", "type": "integer", "minimum": 0, "maximum": 23 }, "endHourUtc": { - "description": "UTC hour (1\u201324) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight.", + "description": "UTC hour (1–24) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight.", "type": "integer", "minimum": 1, "maximum": 24 @@ -26742,7 +27276,7 @@ "type": "integer" }, "isActiveNow": { - "description": "Whether this entry is currently active. Scheduled times are indicative \u2014 actions are applied on a best-effort basis and may be delayed by a few minutes.", + "description": "Whether this entry is currently active. Scheduled times are indicative — actions are applied on a best-effort basis and may be delayed by a few minutes.", "type": "boolean" } }, @@ -26824,7 +27358,7 @@ }, "weekdays": { "type": "array", - "description": "Days of the week this entry applies to. 0 = Sunday, 1 = Monday, \u2026, 6 = Saturday.", + "description": "Days of the week this entry applies to. 0 = Sunday, 1 = Monday, …, 6 = Saturday.", "items": { "type": "integer" }, @@ -26838,14 +27372,14 @@ "minItems": 1 }, "startHourUtc": { - "description": "UTC hour (0\u201323) when this entry becomes active (inclusive).", + "description": "UTC hour (0–23) when this entry becomes active (inclusive).", "type": "integer", "minimum": 0, "maximum": 23, "example": 9 }, "endHourUtc": { - "description": "UTC hour (1\u201324) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight.", + "description": "UTC hour (1–24) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight.", "type": "integer", "minimum": 1, "maximum": 24, @@ -26861,7 +27395,7 @@ "example": "vertical" }, "minReplicaMemoryGb": { - "description": "Minimum memory per replica (Gb). Optional for vertical entries \u2014 provide both bounds for a memory range, or omit both to inherit memory from the base scaling config. Required for horizontal (both bounds, equal to maxReplicaMemoryGb \u2014 memory is fixed while the replica count scales). The upper bound is tier-dependent (lower for non-paid organizations) and enforced when the entry is applied.", + "description": "Minimum memory per replica (Gb). Optional for vertical entries — provide both bounds for a memory range, or omit both to inherit memory from the base scaling config. Required for horizontal (both bounds, equal to maxReplicaMemoryGb — memory is fixed while the replica count scales). The upper bound is tier-dependent (lower for non-paid organizations) and enforced when the entry is applied.", "type": "number", "minimum": 8, "maximum": 356, @@ -26869,7 +27403,7 @@ "example": 16 }, "maxReplicaMemoryGb": { - "description": "Maximum memory per replica (Gb). Optional for vertical entries \u2014 provide both bounds for a memory range, or omit both to inherit memory from the base scaling config. Required for horizontal (both bounds, equal to minReplicaMemoryGb \u2014 memory is fixed while the replica count scales). The upper bound is tier-dependent (lower for non-paid organizations) and enforced when the entry is applied.", + "description": "Maximum memory per replica (Gb). Optional for vertical entries — provide both bounds for a memory range, or omit both to inherit memory from the base scaling config. Required for horizontal (both bounds, equal to minReplicaMemoryGb — memory is fixed while the replica count scales). The upper bound is tier-dependent (lower for non-paid organizations) and enforced when the entry is applied.", "type": "number", "minimum": 8, "maximum": 356, @@ -27363,7 +27897,7 @@ "BackupEncryptionConfig": { "type": "object", "additionalProperties": true, - "description": "The `encryption_config.json` stored alongside this backup in your bucket, passed through unchanged. Supply the file contents verbatim rather than constructing this object \u2014 its shape is versioned and depends on your cloud provider. See [Export backups to your own cloud account](https://clickhouse.com/docs/cloud/manage/backups/export-backups-to-own-cloud-account) for what it contains.\n\nAccepted only for organizations enrolled in the private preview, and only when the backup is of a service that has transparent data encryption enabled. Such a restore always produces a service with transparent data encryption enabled, inherited from the source service.", + "description": "The `encryption_config.json` stored alongside this backup in your bucket, passed through unchanged. Supply the file contents verbatim rather than constructing this object — its shape is versioned and depends on your cloud provider. See [Export backups to your own cloud account](https://clickhouse.com/docs/cloud/manage/backups/export-backups-to-own-cloud-account) for what it contains.\n\nAccepted only for organizations enrolled in the private preview, and only when the backup is of a service that has transparent data encryption enabled. Such a restore always produces a service with transparent data encryption enabled, inherited from the source service.", "example": { "schema_version": 1, "restore_key_pairs": [ @@ -28394,7 +28928,7 @@ "example": "*.my-service.example.com" }, "targetId": { - "description": "Optional DNS target ID. For VPC_RESOURCE, it is the CHILD resource configuration ID (rcfg-\u2026), or the configuration ID for a single resource. For VPC_ENDPOINT_SERVICE, it is an AWS availability zone ID (for example use1-az1, not the zone name us-east-1a) that the endpoint service offers and ClickPipes supports in the region; if the endpoint is not in that zone yet, ClickPipes adds the zone to the endpoint. Cross-region VPC endpoint services reject targetId. Not supported for other endpoint types. Set it at create time to route a custom DNS name to that target. If the target is not reported in dnsTargets yet, the mapping is not served until it appears; it does not fall back to the default target. If omitted, the default target is used. For VPC_RESOURCE, once dnsTargets is non-empty, adding or changing a targetId requires an ID in that list; unchanged target IDs are not re-checked.", + "description": "Optional DNS target ID. For VPC_RESOURCE, it is the CHILD resource configuration ID (rcfg-…), or the configuration ID for a single resource. For VPC_ENDPOINT_SERVICE, it is an AWS availability zone ID (for example use1-az1, not the zone name us-east-1a) that the endpoint service offers and ClickPipes supports in the region; if the endpoint is not in that zone yet, ClickPipes adds the zone to the endpoint. Cross-region VPC endpoint services reject targetId. Not supported for other endpoint types. Set it at create time to route a custom DNS name to that target. If the target is not reported in dnsTargets yet, the mapping is not served until it appears; it does not fall back to the default target. If omitted, the default target is used. For VPC_RESOURCE, once dnsTargets is non-empty, adding or changing a targetId requires an ID in that list; unchanged target IDs are not re-checked.", "type": "string", "example": "rcfg-097648d8068504966" } @@ -31601,7 +32135,7 @@ "ClickPipePubSubSource": { "properties": { "format": { - "description": "Format of messages in the Pub/Sub topic. GCP Pub/Sub ClickPipes are in private preview \u2014 contact support to enable this feature for your organization.", + "description": "Format of messages in the Pub/Sub topic. GCP Pub/Sub ClickPipes are in private preview — contact support to enable this feature for your organization.", "type": "string", "enum": [ "JSONEachRow", @@ -31684,7 +32218,7 @@ "ClickPipePostPubSubServiceAccountSource": { "properties": { "format": { - "description": "Format of messages in the Pub/Sub topic. GCP Pub/Sub ClickPipes are in private preview \u2014 contact support to enable this feature for your organization.", + "description": "Format of messages in the Pub/Sub topic. GCP Pub/Sub ClickPipes are in private preview — contact support to enable this feature for your organization.", "type": "string", "enum": [ "JSONEachRow", @@ -31771,7 +32305,7 @@ "ClickPipePostPubSubWorkloadIdentitySource": { "properties": { "format": { - "description": "Format of messages in the Pub/Sub topic. GCP Pub/Sub ClickPipes are in private preview \u2014 contact support to enable this feature for your organization.", + "description": "Format of messages in the Pub/Sub topic. GCP Pub/Sub ClickPipes are in private preview — contact support to enable this feature for your organization.", "type": "string", "enum": [ "JSONEachRow", @@ -32565,7 +33099,7 @@ "example": 2000 }, "replicaMemoryGb": { - "description": "Memory in GiB for DB ClickPipes. Must be 4\u00d7 the CPU core count.", + "description": "Memory in GiB for DB ClickPipes. Must be 4× the CPU core count.", "type": "number", "minimum": 4, "maximum": 128, @@ -33094,7 +33628,7 @@ "type": "number" }, "backupRetentionPeriodInHours": { - "description": "The minimum duration in hours for which the backups are available. Must be a whole number of days between 24 (1 day) and 1080 (45 days) \u2014 i.e. a multiple of 24.", + "description": "The minimum duration in hours for which the backups are available. Must be a whole number of days between 24 (1 day) and 1080 (45 days) — i.e. a multiple of 24.", "type": "number" }, "backupStartTime": { @@ -33209,7 +33743,7 @@ "type": "number" }, "type": { - "description": "Snapshot type. Always \"full\" \u2014 snapshots never chain off a parent.", + "description": "Snapshot type. Always \"full\" — snapshots never chain off a parent.", "type": "string", "enum": [ "full" @@ -34595,7 +35129,7 @@ }, "select": { "type": "array", - "description": "Exactly one aggregated value to display as a single number \u2014 unless \"formulas\" is set, in which case the select items are the formula's operands and the (single) formula value is displayed instead.", + "description": "Exactly one aggregated value to display as a single number — unless \"formulas\" is set, in which case the select items are the formula's operands and the (single) formula value is displayed instead.", "items": { "$ref": "#/components/schemas/ClickStackSelectItem" } @@ -37472,7 +38006,7 @@ ] }, "isBroadcastEnabled": { - "description": "Must be false \u2014 there is no expression to broadcast. Omit it and it is false. Allowed values: false.", + "description": "Must be false — there is no expression to broadcast. Omit it and it is false. Allowed values: false.", "type": "boolean", "example": false }, @@ -37626,7 +38160,7 @@ ] }, "isBroadcastEnabled": { - "description": "Must be true if provided, and is true when omitted \u2014 a source filter should always broadcast to at least its own source. Allowed values: true.", + "description": "Must be true if provided, and is true when omitted — a source filter should always broadcast to at least its own source. Allowed values: true.", "type": "boolean", "example": true }, @@ -43302,7 +43836,7 @@ }, "pgHaType": { "type": "string", - "description": "Type of high availability: \u201cnone\u201d for no replication, \u201casync\u201d for asynchronous replication to a single standby, and \u201csync\u201d for synchronous replication to the number of standbys in `standbyCount` (two by default).", + "description": "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).", "enum": [ "none", "async", @@ -43311,7 +43845,7 @@ }, "pgStandbyCount": { "type": "integer", - "description": "Number of hot standby instances. Accepted values and defaults depend on `haType`:\n- \u201cnone\u201d: 0 (default)\n- \u201casync\u201d: 1 (default)\n- \u201csync\u201d: 1, or 2 (default)\n\nWhen `haType` is updated without `standbyCount`, the default for the new `haType` applies.", + "description": "Number of hot standby instances. Accepted values and defaults depend on `haType`:\n- “none”: 0 (default)\n- “async”: 1 (default)\n- “sync”: 1, or 2 (default)\n\nWhen `haType` is updated without `standbyCount`, the default for the new `haType` applies.", "enum": [ 0, 1, @@ -43348,7 +43882,7 @@ }, "maxItems": 50, "title": "Postgres Tags", - "description": "Tags associated with the Postgres service. Tag keys starting with \u201cchc_\u201d are reserved for internal use." + "description": "Tags associated with the Postgres service. Tag keys starting with “chc_” are reserved for internal use." }, "pgDeletionProtectionProperty": { "type": "boolean", @@ -43473,7 +44007,7 @@ "$ref": "#/components/schemas/pgIsPrimaryProperty" }, "connectionString": { - "description": "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 \u2014 treat as optional.", + "description": "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.", "type": "string" }, "username": { @@ -43481,7 +44015,7 @@ "type": "string" }, "password": { - "description": "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 \u2014 treat as optional.", + "description": "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.", "type": "string" }, "hostname": { @@ -43740,6 +44274,160 @@ "pgBouncerConfig" ] }, + "PostgresPrivateEndpointVpcEndpoint": { + "properties": { + "vpcEndpointId": { + "description": "ID of the AWS VPC endpoint that is allowed to connect.", + "type": "string", + "example": "vpce-0123456789abcdef0", + "pattern": "^vpce-[0-9a-f]{17}$" + }, + "description": { + "description": "Optional description of the VPC endpoint.", + "type": "string", + "example": "Production VPC", + "maxLength": 255 + } + }, + "required": [ + "vpcEndpointId" + ] + }, + "PostgresPrivateEndpointPort": { + "properties": { + "port": { + "description": "Port exposed by the endpoint service.", + "type": "integer", + "example": 5432 + }, + "targetPort": { + "description": "Port on the Postgres service it forwards to.", + "type": "integer", + "example": 5432 + } + }, + "required": [ + "port", + "targetPort" + ] + }, + "PostgresPrivateEndpoint": { + "properties": { + "id": { + "description": "ID of the private endpoint service.", + "type": "string", + "example": "ps0123456789abcdefghjkmnpq" + }, + "state": { + "description": "State of the private endpoint service: one of 'creating', 'available', 'deleting'. More states may be added. It is `creating` for about 5 to 10 minutes after creation, then `available`.", + "type": "string", + "example": "available" + }, + "endpointServiceName": { + "description": "Name of the AWS endpoint service. Use it as the service name when creating a VPC endpoint. Omitted until the service is created.", + "type": "string", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0" + }, + "endpointServiceId": { + "description": "ID of the AWS endpoint service. Omitted until the service is created.", + "type": "string", + "example": "vpce-svc-0123456789abcdef0" + }, + "privateHostname": { + "description": "Hostname that resolves to the Postgres service from an approved VPC endpoint. Omitted until the service is available.", + "type": "string" + }, + "privateDnsName": { + "description": "Private DNS name of the endpoint service. Omitted until it is assigned.", + "type": "string" + }, + "privateDnsVerificationState": { + "description": "Verification state of the private DNS name. Omitted until it is assigned.", + "type": "string" + }, + "ipAddressType": { + "description": "IP address type of the endpoint service.", + "type": "string", + "example": "dual" + }, + "ports": { + "type": "array", + "description": "Ports the endpoint service forwards.", + "items": { + "$ref": "#/components/schemas/PostgresPrivateEndpointPort" + } + }, + "supportedRegions": { + "type": "array", + "description": "AWS region IDs, other than the service region, from which VPC endpoints can connect, such as `us-west-2`. Requires cross-region private endpoints to be enabled for the organization.", + "items": { + "type": "string" + }, + "example": [ + "us-west-2" + ] + }, + "allowedVpcEndpoints": { + "type": "array", + "description": "VPC endpoints approved to connect.", + "items": { + "$ref": "#/components/schemas/PostgresPrivateEndpointVpcEndpoint" + } + } + }, + "required": [ + "id", + "state", + "ipAddressType", + "ports", + "supportedRegions", + "allowedVpcEndpoints" + ] + }, + "PostgresPrivateEndpointPostRequest": { + "properties": { + "supportedRegions": { + "type": "array", + "description": "AWS region IDs, other than the service region, from which VPC endpoints can connect, such as `us-west-2`. Requires cross-region private endpoints to be enabled for the organization.", + "items": { + "type": "string" + }, + "example": [ + "us-west-2" + ], + "uniqueItems": true + } + } + }, + "PostgresPrivateEndpointPatchRequest": { + "properties": { + "allowedVpcEndpoints": { + "type": "array", + "description": "Full replacement of the approved VPC endpoints: endpoints not listed are no longer allowed to connect. Each endpoint ID must be unique.", + "items": { + "$ref": "#/components/schemas/PostgresPrivateEndpointVpcEndpoint" + }, + "example": [ + { + "vpcEndpointId": "vpce-0123456789abcdef0", + "description": "Production VPC" + } + ], + "maxItems": 50 + }, + "supportedRegions": { + "type": "array", + "description": "Full replacement of the supported regions. AWS region IDs, other than the service region, from which VPC endpoints can connect, such as `us-west-2`. Requires cross-region private endpoints to be enabled for the organization.", + "items": { + "type": "string" + }, + "example": [ + "us-west-2" + ], + "uniqueItems": true + } + } + }, "PostgresBackup": { "properties": { "key": { @@ -44207,7 +44895,7 @@ "UpgradeWindow": { "properties": { "weekday": { - "description": "Day of the week the upgrade window starts. 0 = Sunday, 1 = Monday, \u2026, 6 = Saturday.", + "description": "Day of the week the upgrade window starts. 0 = Sunday, 1 = Monday, …, 6 = Saturday.", "type": "integer", "minimum": 0, "maximum": 6, @@ -44242,7 +44930,7 @@ "UpgradeWindowPutRequest": { "properties": { "weekday": { - "description": "Day of the week the upgrade window starts. 0 = Sunday, 1 = Monday, \u2026, 6 = Saturday.", + "description": "Day of the week the upgrade window starts. 0 = Sunday, 1 = Monday, …, 6 = Saturday.", "type": "integer", "minimum": 0, "maximum": 6, @@ -45180,7 +45868,7 @@ ] }, "backupRetentionPeriodInHours": { - "description": "The minimum duration in hours for which the backups are available. Must be a whole number of days between 24 (1 day) and 1080 (45 days) \u2014 i.e. a multiple of 24.", + "description": "The minimum duration in hours for which the backups are available. Must be a whole number of days between 24 (1 day) and 1080 (45 days) — i.e. a multiple of 24.", "type": [ "number", "null" @@ -45526,7 +46214,7 @@ "example": 2000 }, "replicaMemoryGb": { - "description": "Memory in GiB for DB ClickPipes. Must be 4\u00d7 the CPU core count.", + "description": "Memory in GiB for DB ClickPipes. Must be 4× the CPU core count.", "type": "number", "minimum": 4, "maximum": 128, @@ -45974,7 +46662,7 @@ "const": "executable" }, "poolSize": { - "description": "Always null \u2014 an executable UDF has no command pool.", + "description": "Always null — an executable UDF has no command pool.", "default": null, "anyOf": [ { @@ -46228,7 +46916,7 @@ "const": "executable" }, "poolSize": { - "description": "Always null \u2014 an executable UDF has no command pool.", + "description": "Always null — an executable UDF has no command pool.", "default": null, "anyOf": [ { @@ -46857,7 +47545,7 @@ "type": "http", "scheme": "basic", "description": "Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi", - "x-permission-scopes": "The scope list of a `security` requirement holds ClickHouse Cloud API key permission ids (for example `control-plane:organization:view`), not OAuth scopes. OpenAPI has no field for API key permissions, so this is the closest available place. A key must hold every permission listed on an operation to call it; an operation with no scopes needs none beyond a valid key. Every operation declares at most one requirement object, always for this scheme, so the list is only ever conjunctive \u2014 alternative sets of permissions are never expressed." + "x-permission-scopes": "The scope list of a `security` requirement holds ClickHouse Cloud API key permission ids (for example `control-plane:organization:view`), not OAuth scopes. OpenAPI has no field for API key permissions, so this is the closest available place. A key must hold every permission listed on an operation to call it; an operation with no scopes needs none beyond a valid key. Every operation declares at most one requirement object, always for this scheme, so the list is only ever conjunctive — alternative sets of permissions are never expressed." }, "bearerJwt": { "type": "http", diff --git a/crates/clickhouse-cloud-api/src/client/rbac.rs b/crates/clickhouse-cloud-api/src/client/rbac.rs index 6f64712d..c7da9d66 100644 --- a/crates/clickhouse-cloud-api/src/client/rbac.rs +++ b/crates/clickhouse-cloud-api/src/client/rbac.rs @@ -4,12 +4,24 @@ use crate::meta::operations; use crate::models::*; impl Client { - /// List all available roles for an organization + /// Get one page of an organization's roles, system and custom. + /// + /// Roles are ordered by role ID. The server defaults `limit` to 250, which is + /// also the maximum. Pass the response's `next_cursor` as `cursor` until it is + /// `None`. pub async fn organization_roles_get_list( &self, organization_id: &str, + limit: Option, + cursor: Option<&str>, ) -> Result>, Error> { - let req = self.request(&operations::ORGANIZATION_ROLES_GET_LIST, &[organization_id])?; + let mut req = self.request(&operations::ORGANIZATION_ROLES_GET_LIST, &[organization_id])?; + if let Some(limit) = limit { + req = req.query(&[("limit", limit)]); + } + if let Some(cursor) = cursor { + req = req.query(&[("cursor", cursor)]); + } let resp = req.send().await?; let status = resp.status(); let body_text = resp.text().await?; diff --git a/crates/clickhouse-cloud-api/tests/client/main.rs b/crates/clickhouse-cloud-api/tests/client/main.rs index db5cff59..0897ab25 100644 --- a/crates/clickhouse-cloud-api/tests/client/main.rs +++ b/crates/clickhouse-cloud-api/tests/client/main.rs @@ -11,6 +11,7 @@ mod members; mod organizations; mod postgres; mod query_api_endpoints; +mod rbac; mod saved_queries; mod services; mod udfs; diff --git a/crates/clickhouse-cloud-api/tests/client/rbac.rs b/crates/clickhouse-cloud-api/tests/client/rbac.rs new file mode 100644 index 00000000..54a93925 --- /dev/null +++ b/crates/clickhouse-cloud-api/tests/client/rbac.rs @@ -0,0 +1,76 @@ +use wiremock::matchers::{basic_auth, method, path}; +use wiremock::{Mock, ResponseTemplate}; + +use crate::setup; + +// =========================================================================== +// Organization roles +// =========================================================================== + +#[tokio::test] +async fn list_roles_pagination_encodes_parameters_and_preserves_envelope() { + let (server, client) = setup().await; + let cursor = "opaque +/=&?雪"; + Mock::given(method("GET")) + .and(path("/v1/organizations/org-1/roles")) + .and(basic_auth("key", "secret")) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ + "status": 200, "requestId": "req-page", + "result": [{"id": "role-1", "name": "Admin", "type": "system"}], + "limit": 25, "nextCursor": cursor + }))) + .expect(4) + .mount(&server) + .await; + for (limit, cursor_arg) in [ + (None, None), + (Some(25), None), + (None, Some(cursor)), + (Some(25), Some(cursor)), + ] { + let response = client + .organization_roles_get_list("org-1", limit, cursor_arg) + .await + .unwrap(); + let roles = response.result.unwrap(); + assert_eq!(roles.len(), 1); + assert_eq!(roles[0].id.as_deref(), Some("role-1")); + assert_eq!(response.limit, Some(25)); + assert_eq!(response.next_cursor.as_deref(), Some(cursor)); + } + let requests = server.received_requests().await.unwrap(); + let queries: Vec> = requests + .iter() + .map(|request| request.url.query_pairs().into_owned().collect()) + .collect(); + assert_eq!( + queries, + vec![ + vec![], + vec![("limit".into(), "25".into())], + vec![("cursor".into(), cursor.into())], + vec![ + ("limit".into(), "25".into()), + ("cursor".into(), cursor.into()) + ], + ] + ); +} + +#[tokio::test] +async fn list_roles_last_page_has_no_next_cursor() { + let (server, client) = setup().await; + Mock::given(method("GET")) + .and(path("/v1/organizations/org-1/roles")) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ + "result": [], "limit": 250, "nextCursor": null + }))) + .mount(&server) + .await; + let response = client + .organization_roles_get_list("org-1", None, None) + .await + .unwrap(); + assert_eq!(response.result, Some(vec![])); + assert_eq!(response.next_cursor, None); +} diff --git a/crates/clickhouse-cloud-api/tests/common/support.rs b/crates/clickhouse-cloud-api/tests/common/support.rs index 1bedd49e..0b68a8f0 100644 --- a/crates/clickhouse-cloud-api/tests/common/support.rs +++ b/crates/clickhouse-cloud-api/tests/common/support.rs @@ -38,6 +38,33 @@ pub async fn list_all_api_keys(client: &Client, org_id: &str) -> TestResult, +) -> TestResult> { + let mut roles = Vec::new(); + let mut cursor = None; + let mut seen = std::collections::HashSet::new(); + loop { + let response = client + .organization_roles_get_list(org_id, limit, cursor.as_deref()) + .await?; + roles.extend(response.result.ok_or("roles list returned no result")?); + match response.next_cursor { + None => return Ok(roles), + Some(next) => { + if !seen.insert(next.clone()) { + return Err("roles list returned a repeated cursor".into()); + } + cursor = Some(next); + } + } + } +} + const DEFAULT_CREATE_TIMEOUT_SECS: u64 = 1_800; const DEFAULT_DELETE_TIMEOUT_SECS: u64 = 900; const DEFAULT_STEADY_STATE_TIMEOUT_SECS: u64 = 1_800; diff --git a/crates/clickhouse-cloud-api/tests/integration_org_test.rs b/crates/clickhouse-cloud-api/tests/integration_org_test.rs index 74b87334..b8200f92 100644 --- a/crates/clickhouse-cloud-api/tests/integration_org_test.rs +++ b/crates/clickhouse-cloud-api/tests/integration_org_test.rs @@ -305,8 +305,7 @@ async fn cloud_org_lifecycle() -> TestResult<()> { let client = client.clone(); let org_id = ctx.org_id.clone(); async move { - let resp = client.organization_roles_get_list(&org_id).await?; - resp.result.ok_or_else(|| "org roles list returned no result".into()) + list_all_org_roles(&client, &org_id, None).await } }, ) @@ -861,10 +860,8 @@ async fn cloud_org_lifecycle() -> TestResult<()> { let client = client.clone(); let org_id = ctx.org_id.clone(); async move { - let resp = client.organization_roles_get_list(&org_id).await?; - let roles = resp - .result - .ok_or("roles list returned no result")?; + // A one-role page walks the cursor across every page. + let roles = list_all_org_roles(&client, &org_id, Some(1)).await?; Ok(roles.into_iter().flat_map(|r| r.id).collect::>()) } }, @@ -933,10 +930,7 @@ async fn cloud_org_lifecycle() -> TestResult<()> { let role_id = role_id_clone; let pre_ids = pre_ids_clone; async move { - let resp = client.organization_roles_get_list(&org_id).await?; - let roles = resp - .result - .ok_or("roles list returned no result")?; + let roles = list_all_org_roles(&client, &org_id, None).await?; if !roles .iter() .any(|r| r.id.as_deref() == Some(role_id.as_str())) diff --git a/crates/clickhousectl/src/cloud/organizations/client.rs b/crates/clickhousectl/src/cloud/organizations/client.rs index 1095c547..b8ab488b 100644 --- a/crates/clickhousectl/src/cloud/organizations/client.rs +++ b/crates/clickhousectl/src/cloud/organizations/client.rs @@ -402,7 +402,7 @@ impl CloudClient { ) -> crate::cloud::client::Result> { let response = self .api() - .organization_roles_get_list(org_id) + .organization_roles_get_list(org_id, None, None) .await .map_err(|error| { self.convert_error_for_resource(error, ResourceLookup::organization(org_id)) diff --git a/scripts/classify-cloud-integration.py b/scripts/classify-cloud-integration.py index 4cf55783..6da0f074 100644 --- a/scripts/classify-cloud-integration.py +++ b/scripts/classify-cloud-integration.py @@ -253,6 +253,7 @@ "crates/clickhouse-cloud-api/tests/client/organizations.rs": NO_SUITES, "crates/clickhouse-cloud-api/tests/client/postgres.rs": NO_SUITES, "crates/clickhouse-cloud-api/tests/client/query_api_endpoints.rs": NO_SUITES, + "crates/clickhouse-cloud-api/tests/client/rbac.rs": NO_SUITES, "crates/clickhouse-cloud-api/tests/client/saved_queries.rs": NO_SUITES, "crates/clickhouse-cloud-api/tests/client/services.rs": NO_SUITES, "crates/clickhouse-cloud-api/tests/client/udfs.rs": NO_SUITES, diff --git a/scripts/tests/test_classify_cloud_integration.py b/scripts/tests/test_classify_cloud_integration.py index c856d4d5..61c5ef48 100644 --- a/scripts/tests/test_classify_cloud_integration.py +++ b/scripts/tests/test_classify_cloud_integration.py @@ -280,6 +280,7 @@ def test_current_test_mapping_values(self): "crates/clickhouse-cloud-api/tests/client/organizations.rs", "crates/clickhouse-cloud-api/tests/client/postgres.rs", "crates/clickhouse-cloud-api/tests/client/query_api_endpoints.rs", + "crates/clickhouse-cloud-api/tests/client/rbac.rs", "crates/clickhouse-cloud-api/tests/client/saved_queries.rs", "crates/clickhouse-cloud-api/tests/client/services.rs", "crates/clickhouse-cloud-api/tests/client/udfs.rs",