Easy-to-use PostgreSQL instance manager
Create, manage, and backup PostgreSQL databases with ease. pgcli provides a simple CLI to launch isolated PostgreSQL instances in containers — one command to spin up a database, automatic backups, and point-in-time recovery when you need it.
Whether you're running multiple dev databases, managing staging environments, or need reliable backup strategies, pgcli handles the complexity so you can focus on your application.
Key capabilities:
- One-command to manage multiple database instances
- Advanced features such as: replica/backup/restore/extensions/psql/shell/import-export/clone/dsn-connection
- Cross-platform support (Linux and macOS)
Full documentation site: https://pgcli.pages.dev (EN / 中文)
| Document | Description |
|---|---|
| Quick Start | Install, init config, start/stop instances, multi-instance, multi-config isolation (namespace + port ranges), interactive psql session, container shell, remote connection via --dsn |
| exec and psql | One-shot SQL vs interactive sessions, container command mode, stdin scripts, psql passthrough args, remote --dsn mode and its rules |
| Data Import/Export | Export/import in custom or SQL format, gzip compression, specific database, stream piping between instances, across hosts via SSH, and to remote databases via --dsn |
| Clone | Copy an instance into a new one via logical dump pipe, remote --dsn source, pre-flight connectivity check, live progress |
| Backup and Restore | Full/differential snapshots, snapshot list/delete, point-in-time recovery (PITR) with read-only inspection before promoting |
| Replica | Read-only physical standby of an instance: create/list, live WAL streaming, lag, slot lifecycle |
| Failover | 3-step manual failover: promote replica to primary, re-point other replicas, demote old primary |
| Extensions | Install PostgreSQL extensions from Pigsty DEB repo, baked into container image, shared_preload_libraries management |
| Administration | Shell completion (bash/zsh/fish/PowerShell), PostgreSQL parameter tuning, instance destroy/rebuild |
| Test Report | Core functionality test report: DSN piping, PITR verification, known issues, install script test |
| Platform | Architecture | Status | Notes |
|---|---|---|---|
| Linux | amd64, arm64 | ✅ Recommended | Native podman, best performance |
| macOS | amd64, arm64 | Supported | Requires podman machine (VM overhead) |
| Windows | - | ❌ Not supported | Use WSL2 with Linux |
Tested and verified on:
- Debian 12 (bookworm) - LTS
- Debian 13 (trixie) - Current stable
- Ubuntu 24.04 (noble) - LTS
- Ubuntu 26.04 (resolute) - LTS
- Fedora 44 - SELinux Enforcing mode supported
- Rocky Linux 10 - SELinux auto-disabled by installer
- Other distributions with podman 4.0+ may work
On RHEL/CentOS/Rocky/AlmaLinux with SELinux Enforcing, rootless podman-static cannot run containers. The installer automatically detects SELinux status and:
- Disables it via
sudo setenforce 0and persists the change in/etc/selinux/config - Errors out with clear instructions if sudo permissions are insufficient:
Sudo privileges are recommended for the best experience:
| Privilege Level | Installation Path | Auto-setup |
|---|---|---|
| With sudo (recommended) | /usr/local/bin |
✅ Automatically installs dependencies, creates policy.json |
| Without sudo | ~/.local/bin |
The installer automatically detects available privileges and adapts accordingly.
- Containerized PostgreSQL — Each instance runs in an isolated Podman container with separate data directories
- Extension Management — Install, remove, and manage 440+ PostgreSQL extensions from the Pigsty DEB repository
- Smart image ID-based change detection for container replacement (detects content changes even when tags stay the same)
- Automatic extension configuration with restart confirmation prompts
- Extensions baked into container images for persistence across rebuilds
- PITR (Point-In-Time Recovery) — Full backup and time-travel recovery via pgBackRest with differential/incremental snapshots
- Snapshot Management — Create, list, and delete database snapshots for quick rollback
- Read-only Replicas — Physical standby instances streaming WAL from a primary, supporting read/write split and failover scenarios
- Failover — 3-step manual failover: promote replica to primary, re-point remaining replicas, demote old primary back to replica. Same-host and cross-host supported
- Multi-Instance Support — Run multiple isolated PostgreSQL instances on different ports with independent configurations
- Multi-Config Isolation — Multiple config files on one host with namespaced containers and disjoint port ranges (use pg config init -h for details)
- Data Import/Export — Export/import in custom or SQL format with gzip compression, stream piping between instances, and cross-host support via SSH or
--dsn - Instance Cloning — Copy an instance into a new one via logical dump pipe with live progress and pre-flight connectivity checks
- Interactive Shell — Open psql or bash sessions directly in containers, or connect to remote databases via
--dsn - Linux + macOS — Native Podman on Linux, podman machine on macOS with automatic setup
curl -fsSL https://raw.githubusercontent.com/mars-base/pgcli/main/scripts/install.sh | bashThe installer auto-detects sudo privileges and installs to /usr/local/bin (with sudo) or ~/.local/bin (without sudo). PATH is configured automatically.
# Initialize config (creates ~/.pgcli/pg.yaml with default instance)
pg config init --add default --base-dir /data/pg
# Alternatively, Isolated environments on one host: distinct namespace + disjoint port ranges (use pg config init -h for details)
pg config init -o ~/.pgcli-t1/pg.yaml --namespace t1 --pg-start-port 38000 --pg-ssh-port 43000 --add proj1
pg -c ~/.pgcli-t1/pg.yaml start
# Start instance
pg start
# Check status and connection info
pg status
# Connect via psql
psql postgres://admin:<password>@localhost:35432/default_db
# Execute SQL directly
pg exec "SELECT version()"
# Stop
pg stopSee the full Quick Start guide for multi-instance setup, interactive psql sessions, and container shell usage.
Apache 2.0