infra-postgres
clickhouse/agent-skills
Set up and manage Postgres locally or in ClickHouse Cloud using clickhousectl.
What is infra-postgres?
Manages Postgres in two environments: local Docker-backed instances for development, and managed services in ClickHouse Cloud for production. Use this when you need a Postgres database for development, testing, or production deployment, or when migrating an existing Postgres instance (Neon, Supabase, RDS, Aurora, Cloud SQL) to ClickHouse Cloud.
- Run local Docker-backed Postgres instances for development and testing
- Create and operate managed Postgres services in ClickHouse Cloud with high availability
- Configure TLS, runtime settings, and database connections
- Set up read replicas and failover for production Postgres
- Perform point-in-time restore and database migrations
- Migrate existing Postgres databases from other providers into ClickHouse Cloud
How to install infra-postgres
npx skills add https://github.com/clickhouse/agent-skills --skill infra-postgres- clickhousectl CLI installed (install via: curl -fsSL https://clickhouse.com/cli | sh)
- Docker installed and running (for local Postgres instances)
- ClickHouse Cloud account (for managed cloud Postgres services)
How to use infra-postgres
- 1.Verify clickhousectl is installed by running: which clickhousectl
- 2.Choose your workflow: local development (ref/local.md), cloud production (ref/cloud.md), or migration (ref/migrate.md)
- 3.For local: create a named Docker-backed Postgres instance and connect via psql
- 4.For cloud: authenticate with ClickHouse Cloud and create a managed Postgres service
- 5.Configure TLS, passwords, replicas, or failover settings as needed for your environment
- 6.Use --json flag with commands for machine-readable output in scripts
Use cases
- Local development: spin up a named Postgres instance for prototyping without cloud costs
- Production deployment: create a managed, highly-available Postgres service in ClickHouse Cloud
- Database migration: move an existing Postgres from Neon, Supabase, RDS, or self-hosted to ClickHouse Cloud
- CI/CD testing: run tests against a local Postgres instance in your pipeline
- Disaster recovery: configure read replicas and point-in-time restore for production databases
- Backend developers building applications that need Postgres
- DevOps engineers managing production database infrastructure
- Teams migrating from other Postgres providers to ClickHouse Cloud
- QA engineers setting up test databases for CI/CD pipelines
infra-postgres FAQ
No. For local development, you only need Docker and clickhousectl. A ClickHouse Cloud account is required only if you want to create managed Postgres services in the cloud.
Yes. Use the ref/migrate.md workflow to migrate existing Postgres databases from other providers into ClickHouse Cloud Postgres.
Start with ref/local.md for local development. When ready for production, ref/local.md points you to ref/cloud.md to create a managed ClickHouse Cloud Postgres service.
ClickHouse Cloud Postgres supports read replicas, automatic failover, point-in-time restore, and TLS configuration for production workloads.
Add the --json flag to any clickhousectl command for JSON-formatted output suitable for scripts and automation.
Full instructions (SKILL.md)
Source of truth, from clickhouse/agent-skills.
name: infra-postgres description: 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. license: Apache-2.0 metadata: author: ClickHouse Inc version: "0.2.0"
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. Exit codes follow gh conventions: 0 success, 1 error, 2 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-clickhouseskill.
Related skills
More from clickhouse/agent-skills and the wider catalog.
chdb-datastore
Drop-in pandas replacement with ClickHouse speed for filtering, grouping, joining, and cross-source data operations.
chdb-sql
Run ClickHouse SQL on local files, URLs, S3, and remote databases without a server.
clickhouse-architecture-advisor
Workload-aware ClickHouse architecture decisioning with provenance-labeled recommendations.
clickhouse-best-practices
31 ClickHouse best-practice rules for schema design, query optimization, and data ingestion.
create-pull-request
Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, PR template usage, and PR creation using the gh CLI tool.
cline-sdk
Comprehensive SDK for building AI agents with custom tools, plugins, LLM providers, and multi-agent orchestration.