Cloud

Cloud Postgres write operations (create, update, delete, restore, etc.) require API key authentication — OAuth login is read-only. If the user has no ClickHouse Cloud account, point them to https://clickhouse.cloud (opens in a new tab) (or clickhousectl cloud auth signup) first.

Guide the user to create an API key in the ClickHouse Cloud console (Settings → API Keys → Create API Key, Admin role, copy both the Key ID and Secret — the secret is shown once). Then ask them to run the login in a separate terminal so the secret stays out of the chat session:

Alternatively, credentials can come from CLICKHOUSE_CLOUD_API_KEY / CLICKHOUSE_CLOUD_API_SECRET env vars (also picked up from a .env file in the current directory).

Verify:

Step 2: Create a Postgres service

--name, --region, and --size are required:

Options to surface when relevant:

• --provider <provider> — cloud provider (default: aws)
• --pg-version 18|17 — Postgres major version
• --ha-type none|async|sync — high availability
• --tag key=value — resource tags (repeatable)
• --pg-config-file <path> / --pg-bouncer-config-file <path> — JSON files with initial runtime config

The size is validated server-side; if the user is unsure what sizes or regions are available, check the ClickHouse Cloud console or docs rather than guessing.

Then poll until the service is running (service IDs come from postgres list):

The get output includes the connection endpoint details.

Step 3: Connect

Set a known password (ClickHouse cannot reveal the current one):

--generate prints a random compliant password; store it in .env immediately. (Or pass --password <pw>: minimum 12 characters with upper, lower, and digit.)

For TLS verification, fetch the CA bundle:

Connect with psql using the endpoint from postgres get. If psql is not installed locally, reuse the local wrapper’s explicit-host mode (runs psql via Docker if needed):

Step 4: Apply the schema

If the user developed locally first (see local.md), apply the same schema files to the cloud service, e.g.:

Step 5: Runtime configuration (as needed)

Prefer patch over replace for targeted changes. Check --help on each subcommand for the exact flags.

Day-2 operations

restore creates a new service from the source’s backups at the given RFC 3339 timestamp; it does not modify the source. delete, promote, and switchover are disruptive — confirm with the user before running them, and never run delete unless the user explicitly asked to delete that specific service.