pgcli

Extension Catalog

Mon, 01 Jan 0001 00:00:00 +0000

This page lists all built-in extensions available in the base image. For usage examples, see Popular Extensions.

Built-in Extensions (45)

These extensions ship in the PostgreSQL base image — no image build or pg extension install needed. Just run CREATE EXTENSION to enable them.

Requires shared_preload_libraries

These extensions need a PostgreSQL restart after enabling. pgcli handles this automatically when installed via pg extension install.

Feedback

Mon, 01 Jan 0001 00:00:00 +0000

pgcli collects feedback on GitHub and by email.

Report a bug or request a feature — open an issue at mars-base/pgcli/issues. Include the output of pg version and the steps to reproduce.
By email — write to dw_wang126@126.com if you prefer not to post publicly.

PgBouncer

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer is a lightweight connection pooler for PostgreSQL. As a pgcli addon it runs as a container in front of one or more PostgreSQL instances, reusing server connections across many short-lived client sessions — transaction-level pooling by default.

PgBouncer supports two deployment modes:

Local: pg addon install pgbouncer -i <instance> — stored under instances.<name>.addons
Remote: pg addon install pgbouncer --dsn <dsn> --pg-name <name> — stored in top-level addons.pgbouncer

Platform support

PgBouncer works on Linux (host networking, including cross-host pools) and on macOS for single-host dev/test (the container joins the pgcli-net bridge and publishes its port, the same way a PG instance does under podman machine). On macOS:

Popular Extensions

Mon, 01 Jan 0001 00:00:00 +0000

Usage examples for the most commonly used PostgreSQL extensions, tested on PG 18 with pgcli.

Performance & Monitoring

Extension	Install	Description
`pg_stat_statements`	`pg extension install pg_stat_statements`	SQL performance analysis. Must-have for production.
`pg_repack`	`pg extension install pg_repack`	Online table reorganization. Reclaims bloat.
`pg_prewarm`	`pg extension install pg_prewarm`	Preload table data after restart.

# Install all at once
pg extension install pg_stat_statements,pg_repack,pg_prewarm --auto-restart

# Find top 5 slow queries
pg exec "SELECT query, calls, total_exec_time::numeric(10,2) AS ms
         FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;"

# Repack a bloated table
pg exec -- pg_repack -U admin -d default_db -t my_table --no-superuser-check

# Prewarm a table
pg exec "SELECT pg_prewarm('my_table');"

Data Types & Identifiers

Extension	Install	Description
`uuid-ossp`	builtin	UUID generation (v1/v3/v5). PG 18 has built-in `gen_random_uuid()` (v4) and `uuidv7()` (v7) — no extension needed.
`hstore`	builtin	Key-value pair storage.
`citext`	builtin	Case-insensitive text. `Foo` = `foo`.

# UUID generation (PG 18 built-in — no extension needed)
pg exec "SELECT gen_random_uuid();"  # v4 random UUID (built-in since PG 13)
pg exec "SELECT uuidv7();"           # v7 time-ordered UUID (new in PG 18)

# uuid-ossp extension — only needed for v1/v3/v5 UUIDs
pg exec "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";"
pg exec "SELECT uuid_generate_v1();"  # v1 timestamp + MAC address
pg exec "SELECT uuid_generate_v3(uuid_ns_url(), 'https://example.com');"  # v3 MD5-based
pg exec "SELECT uuid_generate_v5(uuid_ns_url(), 'https://example.com');"  # v5 SHA-1 based

# Key-value storage
pg exec "SELECT 'theme => dark, lang => en'::hstore -> 'theme';"
# Returns: dark

# Case-insensitive matching
pg exec "CREATE TABLE users (email citext);
         INSERT INTO users VALUES ('Alice@Example.COM');
         SELECT * FROM users WHERE email = 'alice@example.com';"

Search & Text

Extension	Install	Description
`pg_trgm`	builtin	Trigram similarity for fuzzy search and autocomplete.
`unaccent`	builtin	Strip accents for flexible international text search.

# Fuzzy search
pg exec "SELECT name, similarity(name, 'John') FROM users
         ORDER BY similarity(name, 'John') DESC LIMIT 5;"

# Create a trigram index for fast fuzzy search
pg exec "CREATE INDEX users_name_trgm_idx ON users USING gin (name gin_trgm_ops);"

# Remove accents
pg exec "SELECT unaccent('Crème Brûlée');"  -- returns 'Creme Brulee'

# Combine for accent-insensitive fuzzy search
pg exec "SELECT name FROM users WHERE name % unaccent('Creme Brulee');"

Security & Encryption

Extension	Install	Description
`pgcrypto`	builtin	Hashing, encryption/decryption, random generation.
`pgaudit`	`pg extension install pgaudit`	Audit logging. Required for compliance (GDPR, HIPAA, SOX).

# Hash a password with bcrypt
pg exec "SELECT crypt('my_password', gen_salt('bf'));"

# Verify a password
pg exec "SELECT (crypt('my_password', stored_hash) = stored_hash);"

# Symmetric encryption/decryption
pg exec "SELECT pgp_sym_decrypt(pgp_sym_encrypt('secret', 'key'), 'key');"

# Enable audit logging for specific operations
pg exec "SET pgaudit.log = 'read, ddl';"

Geospatial

Extension	Install	Description
`postgis`	`pg extension install postgis`	Full spatial database: geometry, spatial indexes, distance/area.

pg extension install postgis --auto-restart

# Create a table with spatial data
pg exec "CREATE TABLE places (id serial, name text, geom geometry(Point, 4326));"
pg exec "INSERT INTO places (name, geom) VALUES
         ('San Francisco', ST_MakePoint(-122.4, 37.8)),
         ('London', ST_MakePoint(-0.1276, 51.5074));"

# Find places within 5km of a point
pg exec "SELECT name FROM places
         WHERE ST_DWithin(geom, ST_MakePoint(-122.4, 37.8)::geography, 5000);"

# Calculate distance between two cities (in meters)
pg exec "SELECT ST_Distance(
           ST_MakePoint(-74.006, 40.7128)::geography,
           ST_MakePoint(-0.1276, 51.5074)::geography);"

AI & Vector Search

Extension	Install	Description
`pgvector`	`pg extension install vector`	Store and search embedding vectors. Standard for AI apps.

pg extension install vector --auto-restart

# Create a table with vector column
pg exec "CREATE TABLE items (id serial PRIMARY KEY, embedding vector(3));"
pg exec "INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[7,8,9]');"

# Find nearest neighbors (Euclidean distance)
pg exec "SELECT id FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;"

# Create an IVFFlat index for fast approximate search
pg exec "CREATE INDEX items_embedding_idx ON items USING ivfflat (embedding vector_l2_ops);"

Time Series

Extension	Install	Description
`timescaledb`	`pg extension install timescaledb`	Optimized time-series storage with hypertables.

pg extension install timescaledb --auto-restart

# Create a hypertable
pg exec "CREATE TABLE sensor (time timestamptz NOT NULL, value float);
         SELECT create_hypertable('sensor', 'time');"

# Time-bucket aggregation
pg exec "SELECT time_bucket('1 hour', time) AS bucket, avg(value)
         FROM sensor GROUP BY bucket ORDER BY bucket;"

Scheduling & Distributed

Extension	Install	Description
`pg_cron`	`pg extension install pg_cron`	Cron-based job scheduler. Auto-configured by pgcli.
`citus`	`pg extension install citus`	Distributed PostgreSQL with sharding.

pg extension install pg_cron --auto-restart

# Schedule a daily cleanup job (runs at midnight)
pg exec "SELECT cron.schedule('cleanup', '0 0 * * *',
         'DELETE FROM logs WHERE created_at < now() - interval ''30 days''');"

# List scheduled jobs
pg exec "SELECT jobid, schedule, command FROM cron.job;"

# Unschedule a job
pg exec "SELECT cron.unschedule('cleanup');"

Foreign Data

Extension	Install	Description
`postgres_fdw`	builtin	Query external PostgreSQL servers as local tables.
`pg_duckdb`	`pg extension install pg_duckdb`	Embedded DuckDB analytics engine. Read Parquet/CSV, offload OLAP queries.

# Create a foreign server
pg exec "CREATE SERVER remote FOREIGN DATA WRAPPER postgres_fdw
         OPTIONS (host '10.0.0.2', port '5432', dbname 'analytics');"

# Create user mapping
pg exec "CREATE USER MAPPING FOR current_user SERVER remote
         OPTIONS (user 'reader', password 'secret');"

# Import remote schema as foreign tables
pg exec "IMPORT FOREIGN SCHEMA public FROM SERVER remote INTO remote_schema;"

# Query remote data as if it were local
pg exec "SELECT * FROM remote_schema.events LIMIT 10;"

pg extension install pg_duckdb --auto-restart

# Run SQL in DuckDB — duckdb.query is a table function (FROM clause required)
pg exec "SELECT * FROM duckdb.query(\$\$ SELECT 42 AS answer, 'hello' AS msg \$\$);"

# Export a table to Parquet
pg exec "COPY my_table TO '/tmp/my_table.parquet' (FORMAT 'parquet');"

# Read Parquet/CSV files directly
pg exec "SELECT * FROM duckdb.query(\$\$
         SELECT * FROM read_parquet('/tmp/my_table.parquet') WHERE id > 2 \$\$);"

# Offload an entire query to DuckDB (OLAP acceleration)
pg exec "SET duckdb.force_execution = true;
         SELECT category, sum(amount) FROM sales GROUP BY category;"

# Pure DuckDB SQL (no PostgreSQL planner involved)
pg exec "SELECT * FROM duckdb.raw_query(\$\$ SELECT range AS n FROM range(1, 6) \$\$);"

# --- Read files from S3 / MinIO (no file copy needed) ---

# Create an S3 secret once (use_ssl is text: 'true'/'false')
pg exec "SELECT duckdb.create_simple_secret('S3', '<access_key>', '<secret_key>',
         '', 'us-east-1', 'path', '', 'minio.example.com:9000',
         's3://bucket', '', 'false');"

# Query a CSV in the bucket directly
pg exec "SELECT * FROM duckdb.query(\$\$
         SELECT category, count(*) AS cnt, sum(sales) AS total_sales
         FROM read_csv('s3://bucket/products.csv', auto_detect=true)
         GROUP BY category ORDER BY total_sales DESC \$\$);"

Compatibility Notes

Extension	PG 18 Status	Notes
`pgml`	Not available	Only supports PG 14-17 (no PG 18 package)
`uuid-ossp`	Partially needed	PG 18 built-in: `gen_random_uuid()` (v4), `uuidv7()` (v7). Extension only needed for v1/v3/v5

Technical Support

Mon, 01 Jan 0001 00:00:00 +0000

Questions about installation, instance management, backups, replicas, or HA clusters — reach the pgcli maintainers directly.

WeChat

Scan the QR code with WeChat to add us as a contact, and put 技术咨询 (technical consultation) in the friend-request note:

Scan the QR code with Telegram to start a chat:

Etcd

Mon, 01 Jan 0001 00:00:00 +0000

etcd is a distributed key-value store. pgcli can run one or more etcd members as a standalone, top-level addon — shared infrastructure rather than a per-instance sidecar. This is useful as the DCS (Distributed Concurrent Store) backing a PostgreSQL HA stack, or as a general config/lock service.

Security caveat: pgcli-managed etcd members currently run without TLS/CA certificates and without authentication/RBAC — any client that can reach a client port has full read/write access. Plan a deployment around network isolation (loopback binds by default; keep advertised ports inside a trusted network). CA/TLS and auth/RBAC support is on the roadmap for a later release.

Paid Subscription

Mon, 01 Jan 0001 00:00:00 +0000

pgcli itself is free and open source (Apache 2.0). A paid subscription adds priority response times, help with production deployments, and feature input.

PgDog

Mon, 01 Jan 0001 00:00:00 +0000

PgDog is a high-performance Postgres proxy written in Rust (the successor to PgCat). It provides connection pooling, read/write load balancing across replicas, and horizontal sharding — in front of one or more PostgreSQL backends. pgcli can run PgDog as a standalone, top-level addon: shared infrastructure rather than a per-instance sidecar.

Security caveat: PgDog authenticates clients against plaintext passwords stored in users.toml. pgcli writes that file mode 0600 and mounts it read-only into the container, but the passwords still sit in clear text on disk and in pg.yaml. Keep the listen port on loopback (the default) or inside a trusted network, and treat the config file as a secret.

Garage

Mon, 01 Jan 0001 00:00:00 +0000

Garage is a Rust, AGPLv3 reimplementation of S3-compatible object storage, built by Deuxfleurs for small self-hosted and geo-distributed clusters. pgcli runs it as a standalone, top-level addon with the same CLI surface as minio, silo and rustfs (install, list, logs, autostart, password), but its runtime model diverges from all three in four ways that shape this page:

A rendered TOML config file, not argv/env. Garage reads /etc/garage.toml. pgcli renders it under the instance directory and bind-mounts it read-only; the MinIO/silo/rustfs addons pass argv or env.
Two kinds of directory — and multi-disk is native since Garage v0.9.0. metadata_dir (LMDB) and data_dir (blocks) are separate bind mounts, and metadata_dir is always exactly one. data_dir takes either a single path or, natively upstream, a list of { path = …, capacity = … } entries — one per disk, so a node spreads its blocks across several drives itself rather than needing host LVM/RAID under one big filesystem. pgcli exposes that list as --drive (repeatable); MinIO, silo, rustfs, seaweedfs and garage all take a per-node drive list now — see Multi-disk data dirs and Capacity and sizing.
Four ports, from their own pool. S3 API, node-to-node RPC, the s3_web static site, and the admin/metrics API — allocated together per instance from garage_start_port (default 3900), a separate cursor from the shared minio/silo/rustfs pool.
No native TLS — plaintext HTTP only. pgBackRest’s S3 repository forces HTTPS, so a Garage store meant to receive archive-push must be fronted by the nginx addon — see TLS by fronting with nginx.

Like rustfs, Garage is a good successor route now that the open-source MinIO repository is archived. pgcli runs it single-node by default (replication_factor = 1, garage server --single-node) and, with a handful of cluster flags, as a multi-node cross-host cluster — see Multi-node cluster.

Patroni HA

Mon, 01 Jan 0001 00:00:00 +0000

Patroni is the de-facto standard for PostgreSQL high availability: it manages each postmaster’s lifecycle, streams replication between members, and performs automatic failover when the leader is lost. pgcli exposes Patroni as a distinct mode — pg ha — rather than folding it into the plain pg instance path.

This is a separate mode, not an addon subcommand. Patroni (not pgcli) owns the PostgreSQL process. pg ha members do not appear in cfg.Instances, share no instance lifecycle code, and are not created by pg create. The one thing it borrows from the addon system is the etcd DCS.

Patroni Dynamic Configuration

Mon, 01 Jan 0001 00:00:00 +0000

These parameters are stored in the DCS (etcd) under /service/<scope>/config and applied to every member of the cluster. Modify them with pg ha edit-config:

pg ha edit-config app -- -s loop_wait=5
pg ha edit-config app -- -s 'postgresql.parameters.max_connections=200'
pg ha edit-config app --show          # view current config

Reference: Patroni official docs, Pigsty dynamic config.

bootstrap.dcs is one-time. The bootstrap.dcs block in patroni.yml only takes effect when the first member of a scope bootstraps the cluster. Once Patroni writes the config into the DCS, subsequent changes to bootstrap.dcs in the YAML file are completely ignored — even on re-install (pg ha create). Re-running pg ha create does not re-read bootstrap.dcs — Patroni sees the existing config key in the DCS and uses it directly.

PostgREST

Mon, 01 Jan 0001 00:00:00 +0000

PostgREST is a single-process, stateless web server that turns a PostgreSQL schema into a RESTful API. As a pgcli addon it runs as one container in front of any PG endpoint — no data directory, no rendered config file, everything configured through PGRST_* environment variables.

PostgREST is a proxy-type addon like PgBouncer and PgDog: it holds no state of its own. Two deployment modes mirror PgBouncer’s:

Local: pg addon install postgrest -i <instance> — stored as a sidecar under instances.<name>.addons.postgrest, DSN built from the instance.
Remote: pg addon install postgrest --dsn <dsn> --pg-name <name> — stored in top-level addons.postgrest.

The --dsn in either mode is passed verbatim into the container’s PGRST_DB_URI, so it works against any PG endpoint: a direct managed instance, a PgBouncer pool, or a Patroni cluster behind its HAProxy listener.

SeaweedFS

Mon, 01 Jan 0001 00:00:00 +0000

SeaweedFS is a Go, Apache-2.0 S3-compatible object store whose defining trait is volume-granularity disk management: data is split into fixed-size volumes (.vol files) that the master places across volumeservers, giving O(1) reads and cheap small-file storage. pgcli runs it as a standalone, top-level addon with the same CLI surface as garage, minio, silo and rustfs (install, list, logs, autostart, password, pg mc), but its runtime model diverges in four ways that shape this page:

Patroni REST API

Mon, 01 Jan 0001 00:00:00 +0000

Patroni exposes an HTTP REST API on each member, providing health check endpoints (for load balancers and Kubernetes probes), monitoring data (including Prometheus metrics), and cluster management operations.

Reference: Patroni official docs, Pigsty REST API.

Finding the REST API

Each member’s REST API port is assigned automatically by pgcli and stored in pg.yaml under addons.patroni.<scope>.members.<name>.restapi_port. The port is also embedded in the rendered patroni.yml as restapi.connect_address.

# Find REST API ports
pg ha status app          # shows pg= and rest= ports for each member

Authentication

pgcli enables basic-auth on the REST API (username postgres, auto-generated password). But authentication is method-based, not blanket:

RustFS

Mon, 01 Jan 0001 00:00:00 +0000

rustfs is a Rust reimplementation of S3-compatible object storage: the same S3 API, a web console, erasure-coded multi-drive and multi-node layouts — and a completely different runtime model from MinIO/silo. pgcli runs it as a standalone, top-level addon with the same CLI surface as minio and silo (install, TLS, BYO certs, drives, logs, autostart), sharing the one port pool, but with three differences that shape this page:

A fixed container user. Upstream rustfs bakes User=rustfs (uid/gid 10001) into the image. pgcli works around this entirely inside its own wrapper image — see Privileges and ownership below — so a rustfs store needs no host-side ownership dance.
Three topologies, no multi-node single-drive. rustfs speaks SNSD / SNMD / MNMD only — see Deployment modes.
Its own TLS filenames. rustfs reads rustfs_cert.pem / rustfs_key.pem from RUSTFS_TLS_PATH, not MinIO’s public.crt / private.key.

Pick rustfs when you want a lean, Rust-native S3 endpoint; it can coexist with minio and silo on one host (all three draw from the same port pool).

Extensions in HA Clusters

Mon, 01 Jan 0001 00:00:00 +0000

Installing PostgreSQL extensions in a Patroni-managed HA cluster is fundamentally different from a single-node instance. This page explains why, and walks through the pg ha extension command subtree that handles it.

Why not `pg extension install`?

The single-node flow (pg extension install <instance> <ext>) works by:

Building a -ext derived image with Pigsty packages
Stopping and recreating the container from the new image
Editing postgresql.conf to set shared_preload_libraries
Running CREATE EXTENSION inside the container

In a Patroni cluster, steps 2-4 all break:

HAProxy

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy is the load balancer the Patroni docs recommend putting in front of a cluster: clients connect to one stable address, HAProxy health-checks each member’s REST API, and routes writes to the current leader (and, in read/write-split mode, reads to the replicas). pgcli runs it as a standalone, top-level addon — shared routing infrastructure, not a per-instance sidecar — pinned to the official haproxy:3.2.23-alpine image.

Platform support: the HAProxy addon is Linux-only for now. It reaches Patroni members over the host network, which the macOS podman machine does not expose to containers. On macOS NewHAProxyManager fails fast with a clear message; pg addon list still shows installed instances without live status.

Silo

Mon, 01 Jan 0001 00:00:00 +0000

silo is Pigsty’s maintained fork of MinIO: S3-compatible object storage with the web console bundled in, keeping MinIO’s wire contract end to end — the S3 API, the MINIO_* environment variables, the server /data --address :9000 --console-address :9001 command line, the --certs-dir layout, and erasure-coded cluster mode. pgcli runs it as a standalone, top-level addon with exactly the same surface as the minio addon — install, TLS, BYO certs, distributed mode, logs, autostart. Pick silo over MinIO if you follow Pigsty’s releases; the two can coexist on one host (they share one port pool, assigned without collision).

MinIO

Mon, 01 Jan 0001 00:00:00 +0000

MinIO is S3-compatible object storage. pgcli runs it as a standalone, top-level addon — shared infrastructure, not a per-instance sidecar — with the web console included. It defaults to single-node mode and supports a genuinely distributed cluster mode across hosts (see below). Either way it is a general-purpose object store. silo — Pigsty’s MinIO fork, kept wire-compatible — is available as a sibling addon with the identical feature surface; the two share one port pool and can coexist on a host.

Patroni Cluster Backup

Mon, 01 Jan 0001 00:00:00 +0000

This page walks the complete procedure for backing up a Patroni HA cluster: getting the backup infrastructure up with pg backup setup, taking full/incr/diff backups with pg ha snapshot, and one operational pitfall — when a replica’s Replay LSN stalls and pg ha status shows members disagreeing on LSN, how to pull it back with patronictl reinit. Command and mechanism details live in Patroni HA and Backup; this page strings them into a path you can run end to end.

Redis

Mon, 01 Jan 0001 00:00:00 +0000

Redis is the in-memory key-value store most applications reach for when they need a cache, a session backend, leaderboards (sorted sets) or atomic counters. pgcli runs it as a standalone, top-level addon with the same CLI surface as the object stores (install / start / stop / logs / autostart / remove), managed entirely through pg.yaml.

It is deliberately the simplest addon in the fleet:

One container, one port, one password. requirepass is generated on the first install and stored in pg.yaml — an unauthenticated Redis is not a reachable state.
Version selection. It is the first version-selectable addon: --version 7|8 resolves through a built-in table to a pinned docker.io/library/redis tag (7 → 7.4.11, 8 → 8.10.2, the default). --image still bypasses the table with any tag you like.
Persistence you can dial in. By default the dataset is an RDB snapshot in a bind-mounted host directory — it survives restarts, and survives pg addon remove (without --clean-data) so reinstalling the same name revives the data. --aof adds the write-ahead log on top for crash-safe, no-eviction stores, and --save no turns snapshots off entirely (see Parameters).

Pick Redis for cache/session/ranking/counter workloads next to your PostgreSQL instances; it is independent of the PG stack, coexists with any other addon, and several instances (even across majors) can run on one host.

Patroni Cluster Restore

Mon, 01 Jan 0001 00:00:00 +0000

This page is the restore-side companion to Patroni Cluster Backup. Once a cluster has a stanza with WAL archiving (pg backup setup + pg ha snapshot), pg ha restore brings the whole cluster back to a point in time — the Patroni counterpart of the single-instance pg restore. It walks the mechanism (why a cluster PITR is not just pgbackrest restore), the safety pre-check on where the leader lives, an end-to-end runbook, and the re-baseline steps that must follow. Command/flag details also live in Restore → Patroni cluster; this page strings them into a procedure you can run.

Predixy

Mon, 01 Jan 0001 00:00:00 +0000

Predixy is a high-performance Redis protocol proxy. pgcli runs it as a standalone, top-level addon whose job is to take a Redis native cluster — 3+ nodes, 16384 slots, MOVED redirects — and hand it back to your applications as one plain redis:// endpoint. Clients do not need to be cluster-aware: no -c, no redirect handling, just connect and run commands.

Platform support: like HAProxy and Redis, the Predixy addon needs Linux host networking to dial its backend nodes; it is not supported on macOS.

HA Exec / psql

Mon, 01 Jan 0001 00:00:00 +0000

pg ha exec and pg ha psql are the direct way to run SQL against a Patroni cluster. They are the cluster-side twins of the single-instance pg exec and pg psql: you name a scope, they resolve the target and connect. No --dsn to hand-assemble, no member container to podman exec into, and — because the connection is plain TCP — a leader or replica on another host is just as reachable as a local one.

pgAdmin 4

Mon, 01 Jan 0001 00:00:00 +0000

pgAdmin 4 is PostgreSQL’s official web administration UI — the browser console for browsing schemas, running SQL, and watching servers. pgcli runs it as a standalone, top-level addon with the same CLI surface as the other web/infra addons (install / start / stop / logs / autostart / remove), managed entirely through pg.yaml.

It is the fleet’s one UI addon, which shapes its design:

A web app, not a database front. pgAdmin dials the servers you register in its own UI; it does not front one specific PostgreSQL instance the way PostgREST or PgBouncer do. That is why it is a top-level-only addon (addons.pgadmin.<name>) with no per-instance sidecar.
Its own login. The web UI needs an email + password to sign in. That is not a PostgreSQL password — it is pgAdmin’s own account, auto-generated on first install and stored in pg.yaml. Retrieve it later with pg addon password pgadmin.
Persistent session store. pgAdmin keeps its config, saved servers, and browse history in a sqlite DB under a bind-mounted data dir. It survives pg addon remove (without --clean-data) and is revived on reinstall.
Optional one-time seed. --dsn or --pg-name <instance> pre-registers one server in the UI’s servers.json at install, so the browser opens with that server already listed. It is a convenience, not a runtime coupling — pgAdmin never blocks on it, and you can add/remove servers in the UI after.

Tip: one pgAdmin per database, spin up on demand. A pgcli-managed pgAdmin is a single lightweight container that starts in seconds and consumes very little memory — cheap enough to treat as disposable. Rather than running one shared pgAdmin with every server registered in it, create a dedicated instance for the database you are working on right now, and remove it when done:

Example: HA Cluster with a Self-CA MinIO

Mon, 01 Jan 0001 00:00:00 +0000

This page is a worked example, run end to end and verified: create a Patroni HA cluster, stand up a MinIO addon that serves a bring-your-own domain certificate (a self-signed CA of our own making — the same shape as a public-CA or corporate-CA cert, just without buying one), and point the cluster’s pgBackRest backups and WAL archiving at it. Every command below is a real one from the run; only hostnames, ports, passwords, and the certificate material are genericized.

Nginx

Mon, 01 Jan 0001 00:00:00 +0000

nginx is the HTTP reverse proxy that fronts multiple web services — dashboards, APIs, admin panels — with path-based routing and optional TLS termination. pgcli runs it as a standalone, top-level addon with the same CLI surface as the other web/infra addons (install / start / stop / logs / autostart / remove), managed entirely through pg.yaml.

It is the fleet’s HTTP gateway, which shapes its design:

A reverse proxy, not a load balancer. Unlike HAProxy — a TCP load balancer in front of Patroni — nginx is an HTTP reverse proxy that routes by URL path. Each location block forwards to one upstream (web app, API service, etc.), so clients reach multiple services through a single port.
File-driven configuration. pgcli renders nginx.conf from the backends you declare (or accepts a custom file via --conf-file) and bind-mounts it read-only into the official nginx:1.27-alpine image. TLS is optional: when enabled without a BYO cert, pgcli generates a self-signed leaf via tlsca.
Independent log mounting. Each backend gets its own access and error log files (access_<name>.log, error_<name>.log) under a bind-mounted /var/log/nginx/ directory, so per-service traffic is observable without parsing a shared log.
Nginx-specific subcommands. Beyond the generic addon lifecycle (install/start/stop/remove), nginx exposes test (validate config syntax via nginx -t using a temporary container), reload (hot reload via nginx -s reload), and exec (run arbitrary commands inside the container).

Platform support: nginx works on both Linux (host networking) and macOS (pgcli-net bridge with published ports). The upstream image is multi-arch (amd64 + arm64), so any host architecture works.

Generating a Certificate — pg cert

Mon, 01 Jan 0001 00:00:00 +0000

pg cert mints a self-signed certificate — its SubjectAltNames covering any mix of DNS names and IP addresses you ask for — for any place you need TLS without going through a CA: a dev or test server, an internal endpoint, a service whose clients you control. The certificate it writes is a normal TLS server leaf, usable anywhere.

The use this docs tree exercises is pgBackRest’s S3 path: a Patroni cluster’s backups push to an S3 store (MinIO or silo, typically) that must serve TLS — pgBackRest refuses plaintext S3 — and pgcli’s MinIO/silo addons can serve a bring-your-own certificate (pg addon install minio --tls-cert ... --tls-key ...). The quickest way to get a cert to try that with is pg cert:

Grafana

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install grafana runs Grafana — the open-source observability dashboard — as a managed container from the official upstream image. Like pgAdmin it is a top-level addon: it is not attached to any one PostgreSQL instance and fronts none of them automatically — you add datasources and dashboards through the web UI. v1 ships the pure web UI: configuration is environment-only (the GF_* variables), with no datasource or dashboard provisioning mounted.

Prometheus

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install prometheus runs Prometheus — the metrics collection and alerting backend — as a managed container from the official docker.io/prom/prometheus image. Like Grafana it is a top-level addon: it fronts no single PostgreSQL instance (it scrapes many endpoints), so it is not attached to any one of them. The two are natural partners — Prometheus scrapes and stores, Grafana visualises — and share the same lifecycle shape (single container, host networking on Linux, one web port from its own pool, persistent data dir, autostart, logs).

S3 Storage High Availability

Mon, 01 Jan 0001 00:00:00 +0000

A Patroni cluster survives a node loss; the S3 repository its WAL and backups stream into must survive one too, or “high availability” quietly ends at the backup path. The store is a MinIO or silo addon (the two are interchangeable — silo is Pigsty’s MinIO fork with the same feature surface). Two fault domains matter, and they are orthogonal:

Fault	Who absorbs it
A disk dies inside a node	the drive-level EC under SNMD/MNMD, or the storage layer under MinIO’s data directory (ZFS)
A node dies entirely	MinIO’s own erasure coding (EC) across hosts

This page records the shapes pgcli supports for combining the two, and how to pick among them.

Alertmanager

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install alertmanager runs Alertmanager — the alert deduplication, grouping, routing and notification layer that sits downstream of Prometheus — as a managed container from the official docker.io/prom/alertmanager image. Like Prometheus and Grafana it is a top-level addon: it fronts no single PostgreSQL instance, so it is not attached to any one of them. Prometheus and Alertmanager are the natural pair — Prometheus fires alerts, Alertmanager decides who gets notified and how — and this addon is Prometheus’s near-exact twin in shape (single container, host networking on Linux, one web port from its own pool, persistent data dir, autostart, logs, rendered config file + trailing CLI flags, SIGHUP reload, no web login).

Gitea

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install gitea runs Gitea — the lightweight self-hosted Git service — as a managed container from the official upstream image (docker.io/gitea/gitea, rootful build). Like Grafana it is a top-level addon: it is not attached to any one PostgreSQL instance — it fronts none, though it can use one as its metadata database (see --dsn below). One container serves the web UI, the Git HTTP traffic, and git-over-ssh on the image’s OpenSSH sshd (see Git SSH — that sshd runs on every instance whether or not --ssh-port is set; the flag only makes it the live clone endpoint).

VictoriaMetrics

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install victoriametrics runs VictoriaMetrics — a fast, Prometheus-compatible time-series database — as a managed container from the official docker.io/victoriametrics/victoria-metrics image. Like Prometheus and Grafana it is a top-level addon: it fronts no single PostgreSQL instance (it ingests metrics from many sources), so it is not attached to any one of them. The three are natural partners — Prometheus scrapes, VictoriaMetrics stores long-term with superior compression, Grafana visualises — and share the same lifecycle shape (single container, host networking on Linux, one web port from its own pool, persistent data dir, autostart, logs).

BeeGFS

Mon, 01 Jan 0001 00:00:00 +0000

BeeGFS is a parallel filesystem that chose the easy route. It was born in 2004 at Fraunhofer ITWM in Germany — a research group that needed Lustre, found its deployment and operations too heavy, and wrote its own instead, with the goal set from day one: not the biggest scale, but the least human effort to deploy and run. In 2014 the core team spun out as the commercial company ThinkParQ, the product was renamed BeeGFS, and it grew from an institute-internal tool into the shared storage you find on many European universities and regional supercomputers.

VMCluster

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install vmcluster runs VictoriaMetrics cluster edition — three components each in its own container from the official docker.io/victoriametrics/{vminsert,vmselect,vmstorage}:v1.154.1-cluster images. Unlike the single-node victoriametrics addon (one container, one port), this manages up to three containers with three separate images and five ports, supporting cross-host deployment and horizontal scaling.

Architecture:

Component	Role	HTTP Port	Internal TCP
vminsert	Ingestion — shards writes across all vmstorage nodes by metric hash	8480	Dials vmstorage:InternalInsertPort
vmselect	Queries — merges results from all vmstorage nodes	8481	Dials vmstorage:InternalSelectPort
vmstorage	Data storage (sharded, replicable)	8482	Listens on InternalInsertPort + InternalSelectPort

There is NO web login/password. Like the single-node VictoriaMetrics, the cluster edition ships no authentication at all. Its HTTP API runs arbitrary MetricsQL (a superset of PromQL), so remote-exposed instances are guarded only by the network boundary — your firewall, or --listen 127.0.0.1 for loopback. Treat it like an unauthenticated read/write console.

JuiceFS

Mon, 01 Jan 0001 00:00:00 +0000

JuiceFS puts a real POSIX filesystem on top of object storage: file data is split into chunks and stored in an S3 bucket, while a separate metadata engine (SQLite, Redis, PostgreSQL…) keeps the namespace, file attributes and chunk maps. You get an ordinary directory you can ls, cat and grep — every write eventually lands as immutable objects in the bucket. It solves the “I want a filesystem, but the bytes should live in S3” problem: snapshots are cheap (objects are immutable), capacity is the bucket’s, and the same bucket can be re-mounted from any host that knows the metadata URL.

VictoriaLogs

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install victorialogs runs VictoriaLogs — a fast, cost-effective log database from the VictoriaMetrics family — as a managed container from the official docker.io/victoriametrics/victoria-logs image. Like VictoriaMetrics and Prometheus it is a top-level addon: it fronts no single PostgreSQL instance (it ingests logs from many sources), so it is not attached to any one of them. VictoriaMetrics keeps metrics, VictoriaLogs keeps logs, Grafana visualises both — and all three share the same lifecycle shape (single container, host networking on Linux, one web port from its own pool, persistent data dir, restart policy).

vlagent

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install vlagent runs vlagent — the official log agent of the VictoriaLogs family and the log counterpart of vmagent — as a managed container from the official docker.io/victoriametrics/vlagent image. It is a top-level addon (it fronts no single PostgreSQL instance) and the natural partner of the VictoriaLogs addon: VictoriaLogs stores logs, vlagent collects them from files or over HTTP and forwards them to one or more VictoriaLogs instances.

Like VictoriaMetrics and VictoriaLogs there is no config file at all — everything is passed as CLI flags after the image name. pgcli adds the file-collector wiring on top: every --log-path is bind-mounted read-only at the same absolute path inside the container, and --include/--exclude select files using vlagent’s native glob syntax (not regular expressions).

VLCluster

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install vlcluster runs VictoriaLogs cluster edition — the horizontally scalable log database. Unlike the single-node victorialogs addon (one container, one port), this manages up to three containers from the same image (docker.io/victoriametrics/victoria-logs:v1.53.0) and three HTTP ports per host. The role is selected entirely by flags.

Architecture:

Component	Role	HTTP Port	Talks to
vlinsert	Ingestion — shards writes across all vlstorage nodes by stream hash	9430	Dials every `vlstorage:StoragePort`
vlselect	Queries — fans out LogsQL and merges results	9431	Dials every `vlstorage:StoragePort`
vlstorage	Data storage (sharded, not replicated)	9432	Serves `/internal/insert` + `/internal/select/*` on that one port

vlinsert and vlselect are stateless and dial the same single port on each vlstorage node; there are no separate internal TCP ports like VMCluster’s host:insertPort:selectPort. A storage node address is therefore just host:storagePort.

ZeroFS

Mon, 01 Jan 0001 00:00:00 +0000

ZeroFS is an S3-backed filesystem that keeps everything inside the bucket: instead of JuiceFS’s external metadata engine, it runs its own LSM tree directly on object storage, and every object is encrypted with a per-volume data key wrapped by your encryption password. Snapshots and consistency are handled by background compaction — there is no database to back up, no Redis to keep alive. You lose neither property than a normal filesystem gives you (it mounts via FUSE through a local 9P hop), and the bucket alone is a complete, encrypted copy of the volume.

DuckDB

Mon, 01 Jan 0001 00:00:00 +0000

DuckDB is an embedded analytical database — often called “SQLite for analytics”. It is a C++ columnar engine with vectorised execution that queries Parquet, CSV, JSON and Arrow files directly, without a server process. Think of it as a single-binary OLAP engine you point at your data: SELECT * FROM read_parquet('s3://bucket/data.parquet') works out of the box once the httpfs extension is loaded.

As a pgcli addon, DuckDB is a host-binary addon: there is no container and no daemon. pg addon install duckdb downloads the official CLI zip from GitHub releases (sha256-verified; a duckdb already on PATH is reused), installs the httpfs extension (parquet and json are bundled in the binary), and records the entry in pg.yaml.

Node_exporter

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install nodeexporter runs node_exporter — the official Prometheus exporter that publishes the host’s CPU, memory, disk, network and filesystem metrics at /metrics — as a managed container from the official docker.io/prom/node-exporter image. Like Prometheus, VictoriaMetrics and Grafana it is a top-level addon: it describes the machine, not one PostgreSQL instance, so it is attached to none of them. It is the natural companion to a pgcli Prometheus addon — node_exporter exposes, Prometheus scrapes.

InfluxDB

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install influxdb runs InfluxDB 1.13.1 OSS — a single-node time-series database with TSM storage and InfluxQL — as a managed container from pgcli’s own ghcr.io/mars-base/pgcli/pgcli-influxdb image (the official linux/amd64 release binaries on Alpine). Like VictoriaMetrics, it is a top-level addon: it does not front a PostgreSQL instance.

The addon is Linux/amd64 only (the image is single-arch). InfluxDB 1.x has no clustering/HA, no built-in web UI, and upstream has put v1 into maintenance mode; pgcli pins the final 1.13.1 release. For new deployments consider VictoriaMetrics or VictoriaLogs if you need a maintained, auth-free-but-modern engine; InfluxDB 1.x remains a good fit when you need InfluxQL compatibility with existing tooling.

Pg_exporter

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install pgexporter runs pg_exporter — Pigsty’s PostgreSQL metrics exporter — as a managed container from the official docker.io/pgsty/pg_exporter image. Where the node_exporter addon describes the machine, pg_exporter describes a database: it connects to a PostgreSQL server and publishes ~460 pg_* metrics (activity, locks, replication, bloat, WAL, per-database stats…) at /metrics. Like Prometheus, VictoriaMetrics, Grafana and node_exporter it is a top-level addon: it is attached to no instance of its own — instead it points at a target it monitors.

influx2tsdb

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install influx2tsdb runs influx2tsdb-proxy 1.3.2 — an InfluxDB 1.x HTTP API adapter (Line Protocol writes and InfluxQL queries) that stores data in PostgreSQL with the TimescaleDB extension — as a managed container from pgcli’s own ghcr.io/mars-base/pgcli/pgcli-influx2tsdb image. Unlike the InfluxDB addon, there is no TSM engine: every point lives in a TimescaleDB hypertable, and the proxy itself is stateless.

The add-on is Linux/amd64 only (the image is single-arch, built from the upstream release binary on debian:12-slim). The proxy container can be recreated at any time; the data survives because PostgreSQL holds it.

ClickHouse

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install clickhouse runs ClickHouse 26.8 LTS — a single-node columnar OLAP database — as a managed container from the official docker.io/clickhouse/clickhouse-server multi-arch image. Like VictoriaMetrics and InfluxDB, it is a top-level addon: it does not front a PostgreSQL instance.

ClickHouse speaks two protocols on two ports: HTTP (curl, JDBC/ODBC, many drivers) and the native TCP protocol (clickhouse-client). pgcli runs it with host networking, so both are plain host ports. Authentication is always enabled — the install creates an admin account and stores its password in pg.yaml.

Kafka

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install kafka runs Apache Kafka 4.4.0 as a managed container from the official docker.io/apache/kafka multi-arch image. Kafka 4.x is KRaft-only: the metadata controller is built into the broker process (process.roles=broker,controller, combined mode) and ZooKeeper is not installed or used.

Like ClickHouse, Kafka is a top-level addon — it does not front a PostgreSQL instance. pgcli renders server.properties, pins a KRaft cluster id, bind-mounts the data directory and runs the container on the host network. A single command installs a single combined node; adding --cluster, --node-id and --peer installs one node of a multi-host static controller quorum, with every host running its own pg addon install kafka (pgcli never SSHes). See Multi-host cluster.

RabbitMQ

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install rabbitmq runs RabbitMQ 4.4.0 as a managed container from the official docker.io/library/rabbitmq image (the -management variant, which bundles the web UI and HTTP API). Like Kafka and ClickHouse, RabbitMQ is a top-level addon: pgcli renders rabbitmq.conf, owns the administrator account, bind-mounts the data directory and runs the container on the host network.

The addon runs either a single node or one member of a multi-host cluster. Clustering uses etcd peer discovery (rabbitmq_peer_discovery_etcd): you install one member per host with the same --cluster name and the list of etcd endpoints, and the members find each other on first boot — no static peer list and no manual join_cluster. Federation, shovel, MQTT and STOMP are not configured; advanced administration (vhosts, users, permissions, policies and exchanges) is done through the management UI or pg addon rabbitmq shell + rabbitmqctl. Common queue operations are wrapped by pg addon rabbitmq queue (see Queues and messages). In cluster mode declare creates quorum queues by default (see Clustering).

RocketMQ

Mon, 01 Jan 0001 00:00:00 +0000

pg addon install rocketmq runs Apache RocketMQ 5.x as a managed addon from the official docker.io/apache/rocketmq image. Like Kafka, ClickHouse and RabbitMQ it is a top-level addon that does not front a PostgreSQL instance.

Each instance is three containers on the host network: a NameServer, a broker and a proxy. The same shape is used in both modes, so ports, commands, logs and lifecycle behave identically:

Standalone — one NameServer with no controller, one async master broker with no replicas, and a proxy. This is the quickest way to send and receive messages. The 4.x master/slave and DLedger broker deployment modes are not used.
Multi-host cluster — every NameServer embeds a DLedger (Raft) controller, the brokers run in controller mode, and one broker is elected master while another takes over automatically when it fails. The proxy is the client entry point. This is RocketMQ 5.x’s auto-failover deployment mode.

There is no authentication and no TLS. RocketMQ listens on host networking, and cluster ports are fixed. Anyone who can reach the NameServer, broker or proxy ports can read and write every topic. Run it only on a trusted private network or behind a firewall that restricts 9876, 9877, 10911, 10912, 8080 and 8081. There is also no web UI and no ACL in this addon.

pgcli

Extension Catalog

Built-in Extensions (45)

Requires shared_preload_libraries

Feedback

PgBouncer

Platform support

Popular Extensions

Performance & Monitoring

Data Types & Identifiers

Search & Text

Security & Encryption

Geospatial

AI & Vector Search

Time Series

Scheduling & Distributed

Foreign Data

Compatibility Notes

Technical Support

WeChat

Telegram

Etcd

Paid Subscription

PgDog

Garage

Patroni HA

Patroni Dynamic Configuration

PostgREST

SeaweedFS

Patroni REST API

Finding the REST API

Authentication

RustFS

Extensions in HA Clusters

Why not pg extension install?

HAProxy

Silo

MinIO

Patroni Cluster Backup

Redis

Patroni Cluster Restore

Predixy

HA Exec / psql

pgAdmin 4

Example: HA Cluster with a Self-CA MinIO

Nginx

Generating a Certificate — pg cert

Grafana

Prometheus

S3 Storage High Availability

Alertmanager

Gitea

VictoriaMetrics

BeeGFS

VMCluster

JuiceFS

VictoriaLogs

vlagent

VLCluster

ZeroFS

DuckDB

Node_exporter

InfluxDB

Pg_exporter

influx2tsdb

ClickHouse

Kafka

RabbitMQ

RocketMQ

Why not `pg extension install`?