Last updated 2026-10-30 for clickhousectl 0.5.0. (update the CLI with clickhousectl update, update skills with clickhousectl skills)
Postgres with clickhousectl
clickhousectl manages Postgres in two environments:
- Local — named, Docker-backed Postgres instances on the user's machine, for development.
- Cloud — managed Postgres services in ClickHouse Cloud (beta), for production: HA, read replicas, point-in-time restore.
This file routes to the right reference. The step-by-step workflows live in ref/local.md, ref/cloud.md, and ref/migrate.md — read the one that matches the user's situation before running commands.
Which reference to use
| The user wants to... |
Read |
| Develop or prototype locally, run tests/CI against Postgres, no cloud account needed |
ref/local.md |
| Go to production, host a managed Postgres, or use ClickHouse Cloud explicitly |
ref/cloud.md |
| Operate an existing cloud service (passwords, TLS, config, replicas, failover, restore) |
ref/cloud.md |
| Migrate an existing Postgres (Neon, Supabase, RDS, ...) into ClickHouse Cloud Postgres |
ref/migrate.md |
| Develop locally now, ship to production later |
Start with ref/local.md; it points to ref/cloud.md when it's time to go to prod |
If it's genuinely ambiguous (e.g. "set up Postgres for my app"), default to local for development tasks and ask before creating anything in the cloud — cloud services cost money.
Prerequisites (both workflows)
Check that clickhousectl is installed:
which clickhousectl
If not found, install it:
curl -fsSL https://clickhouse.com/cli | sh
This installs to ~/.local/bin/clickhousectl (with a chctl alias). If the command is still not found, suggest export PATH="$HOME/.local/bin:$PATH" or a new terminal.
All commands accept --json for machine-readable output, and switch to JSON automatically when run by a coding agent. SQL output from local client and local postgres client stays in psql or clickhouse-client's native format. Exit codes: 0 success, 1 error, 2 usage error, 3 cancelled, 4 auth required.
Related
- To replicate Postgres data into ClickHouse for analytics, see ClickPipes (
clickhousectl cloud clickpipe --help). ClickPipes cannot target a Postgres service — for Postgres-to-Postgres migration use ref/migrate.md.
- For ClickHouse itself (local development or ClickHouse Cloud services), use the
infra-clickhouse skill.
1---2name: infra-postgres3description: Sets up and manages Postgres using the clickhousectl CLI — runs a local Docker-backed Postgres for development, and creates and operates managed ClickHouse Cloud Postgres services (connections, TLS, runtime config, read replicas, failover, point-in-time restore). Use when the user wants a Postgres or PostgreSQL database for their application, a local Postgres dev environment, psql access, or a managed/production Postgres in ClickHouse Cloud, or mentions moving a local Postgres to production. Also use when migrating an existing Postgres database (Neon, Supabase, RDS, Aurora, Cloud SQL, self-hosted) into ClickHouse Cloud Postgres.4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/stanfish06/infra-postgres7 author: ClickHouse Inc8 version: "0.3.0"9 clickhousectl-version: "0.5.0"10---1112Last updated 2026-10-30 for clickhousectl 0.5.0. (update the CLI with `clickhousectl update`, update skills with `clickhousectl skills`)1314# Postgres with clickhousectl1516`clickhousectl` manages Postgres in two environments:1718- **Local** — named, Docker-backed Postgres instances on the user's machine, for development.19- **Cloud** — managed Postgres services in ClickHouse Cloud (beta), for production: HA, read replicas, point-in-time restore.2021This file routes to the right reference. The step-by-step workflows live in `ref/local.md`, `ref/cloud.md`, and `ref/migrate.md` — read the one that matches the user's situation before running commands.2223## Which reference to use2425| The user wants to... | Read |26|----------------------|------|27| Develop or prototype locally, run tests/CI against Postgres, no cloud account needed | [ref/local.md](ref/local.md) |28| Go to production, host a managed Postgres, or use ClickHouse Cloud explicitly | [ref/cloud.md](ref/cloud.md) |29| Operate an existing cloud service (passwords, TLS, config, replicas, failover, restore) | [ref/cloud.md](ref/cloud.md) |30| Migrate an existing Postgres (Neon, Supabase, RDS, ...) into ClickHouse Cloud Postgres | [ref/migrate.md](ref/migrate.md) |31| Develop locally now, ship to production later | Start with [ref/local.md](ref/local.md); it points to [ref/cloud.md](ref/cloud.md) when it's time to go to prod |3233If it's genuinely ambiguous (e.g. "set up Postgres for my app"), default to local for development tasks and ask before creating anything in the cloud — cloud services cost money.3435## Prerequisites (both workflows)3637Check that `clickhousectl` is installed:3839```bash40which clickhousectl41```4243If not found, install it:4445```bash46curl -fsSL https://clickhouse.com/cli | sh47```4849This installs to `~/.local/bin/clickhousectl` (with a `chctl` alias). If the command is still not found, suggest `export PATH="$HOME/.local/bin:$PATH"` or a new terminal.5051All commands accept `--json` for machine-readable output, and switch to JSON automatically when run by a coding agent. SQL output from `local client` and `local postgres client` stays in psql or clickhouse-client's native format. Exit codes: 0 success, 1 error, 2 usage error, 3 cancelled, 4 auth required.5253## Related5455- To replicate Postgres data into ClickHouse for analytics, see ClickPipes (`clickhousectl cloud clickpipe --help`). ClickPipes cannot target a Postgres service — for Postgres-to-Postgres migration use [ref/migrate.md](ref/migrate.md).56- For ClickHouse itself (local development or ClickHouse Cloud services), use the `infra-clickhouse` skill.