Try pgview

This guide walks you through spinning up a local PostgreSQL instance with realistic seed data and exploring every feature of pgview hands-on. Everything runs locally — no cloud account, no installer, no runtime dependencies beyond a container engine you likely already have.

Quick Start

Two commands. The only hard requirement is a container runtime (Docker Desktop, Colima, or Podman) — curl and bash are both pre-installed on macOS and most Linux distros. The script auto-detects your OS and architecture, starts a seeded PostgreSQL container on port 5433, downloads the correct pgview binary, and launches it.

# Download the start script (curl or wget — one will be available)
curl -fsSL https://raw.githubusercontent.com/sibasismukherjee/pgview/main/demo/start.sh -o start.sh

# Run it — fetches docker-compose.yml, seed.sql, and the pgview binary automatically
bash start.sh

docker compose down && rm pgview start.sh docker-compose.yml seed.sql

curl -fsSL https://raw.githubusercontent.com/sibasismukherjee/pgview/main/demo/start.sh -o start.sh
bash start.sh

What the script does

Manual Setup

Prefer to control each step yourself, or already have a container running? Expand the relevant tab below.

Container runtime

# macOS
brew install --cask docker   # then open Docker Desktop once

# Linux
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER   # log out and back in

brew install colima docker
colima start   # start a lightweight Lima VM; docker CLI works as normal

# macOS
brew install podman && podman machine init && podman machine start

# Linux (Debian/Ubuntu)
sudo apt-get install -y podman

alias docker=podman   # all docker commands work identically

Start PostgreSQL & seed

# Using docker-compose (recommended)
docker compose up -d
# seed.sql is loaded automatically on first boot via /docker-entrypoint-initdb.d/

# Or run a bare container and seed manually
docker run -d --name pgview-demo \
  -e POSTGRES_PASSWORD=demo -e POSTGRES_DB=demodb \
  -p 5433:5432 postgres:16-alpine

# Wait until ready
until docker exec pgview-demo pg_isready -U postgres -d demodb -q; do sleep 1; done

# Apply seed
curl -fsSL https://raw.githubusercontent.com/sibasismukherjee/pgview/main/demo/seed.sql \
  | docker exec -i pgview-demo psql -U postgres -d demodb

Download pgview

TAG=$(curl -sfL "https://api.github.com/repos/sibasismukherjee/pgview/releases/latest" | grep '"tag_name"' | cut -d'"' -f4)
curl -sfL "https://github.com/sibasismukherjee/pgview/releases/download/${TAG}/pgview_${TAG}_darwin_arm64" -o pgview
chmod +x pgview && sudo mv pgview /usr/local/bin/

TAG=$(curl -sfL "https://api.github.com/repos/sibasismukherjee/pgview/releases/latest" | grep '"tag_name"' | cut -d'"' -f4)
curl -sfL "https://github.com/sibasismukherjee/pgview/releases/download/${TAG}/pgview_${TAG}_darwin_amd64" -o pgview
chmod +x pgview && sudo mv pgview /usr/local/bin/

TAG=$(curl -sfL "https://api.github.com/repos/sibasismukherjee/pgview/releases/latest" | grep '"tag_name"' | cut -d'"' -f4)
curl -sfL "https://github.com/sibasismukherjee/pgview/releases/download/${TAG}/pgview_${TAG}_linux_amd64" -o pgview
chmod +x pgview && sudo mv pgview /usr/local/bin/

Connect to PostgreSQL

Run pgview and point it at the container you started earlier:

# One-liner (if you used make try, this is already running)
pgview -url localhost:5433 -username postgres -password demo -dbname demodb -sslmode disable

Or run interactively and enter each value at the prompt:

pgview
# Connection URL (host:port): localhost:5433
# Username: postgres
# Database [postgres]: demodb
# Password: demo  ← not echoed

pgview opens directly on the Table List. You'll see tables across two schemas: demo.* (customers, orders, products, order_items — used in this walkthrough) and public.* (routes, orders — used in the demo GIF).

Feature 1 — Table List

The table list is the home screen. Use ↑ / ↓ to move the selection. Try these keys:

Feature 2 — Fuzzy Table Search

From the table list, press / to open the full-screen fuzzy finder. It searches all schemas simultaneously.

Feature 3 — Data View & Filter DSL

Navigate to demo.orders (fuzzy search ord then Enter). The data view shows 200 rows per page with type-aware colouring: numeric values are green, timestamps orange, NULL is dim gray, booleans are teal/red.

status=paid               # exact match
status!=cancelled         # negation
total>100                 # numeric comparison
total>=50 status=shipped  # AND — two terms

tags=vip          # element-wise: ANY(tags) = 'vip'
tags=%newsletter% # substring per element

notes=%web%      # matches rows where notes contains "web"

Feature 4 — Schema Browser

From the table list or data view, press d to open the 4-tab schema panel. Try it on demo.orders, which has a FK, a CHECK constraint, two indexes, and a rich DDL.

Feature 5 — Row Viewer & Inline Editor

Navigate into demo.customers, select any row, and press f.

UPDATE demo.customers SET status = 'inactive' WHERE id = <original_id>

Feature 6 — SQL Editor & Templates

Press e from any view to open the full-screen SQL editor. From the data view the editor is pre-filled with the last query.

SELECT c.name, COUNT(o.id) AS order_count, SUM(o.total) AS total_spent
FROM demo.customers c
LEFT JOIN demo.orders o ON o.customer_id = c.id
GROUP BY c.name
ORDER BY total_spent DESC NULLS LAST;

Feature 7 — Export to CSV / JSON

From any data view (table browse or SQL results), press E (Shift+E) to start the interactive export flow.

head -5 ~/export_orders_*.csv

Feedback & Roadmap

Thank you for trying pgview! Your feedback shapes what gets built next.

Feature requests are also welcome as GitHub Issues — browse the open issues first to see if your idea already has a thread, or open a new one with the enhancement label.

Clean up

When you are done, tear down the demo container and remove the binary:

make stop && make clean

# Or manually
docker compose down