Get pgconsole running and execute your first query in under a minute.
Step 1: Add a database connection
Create a pgconsole.toml file with at least one connection:
[[connections]]
id = "local"
name = "Local PostgreSQL"
host = "localhost"
port = 5432
database = "postgres"
username = "postgres"
password = "postgres"
If connecting to a database on your host machine from Docker, use host.docker.internal instead of localhost in your config.
Step 2: Start
Docker (Recommended)
npx
npm
docker run -p 9876:9876 -v /path/to/pgconsole.toml:/etc/pgconsole.toml pgplex/pgconsole
npx @pgplex/pgconsole --config /path/to/pgconsole.toml
npm install -g @pgplex/pgconsole
pgconsole --config /path/to/pgconsole.toml
/\_ \
_____ __ ___ ___ ___ ____ ___\//\ \ __
/\ '__`\ /'_ `\ /'___\ / __`\ /' _ `\ /',__\ / __`\\ \ \ /'__`\
\ \ \L\ \/\ \L\ \/\ \__//\ \L\ \/\ \/\ \/\__, `\/\ \L\ \\_\ \_/\ __/
\ \ ,__/\ \____ \ \____\ \____/\ \_\ \_\/\____/\ \____//\____\ \____\
\ \ \/ \/___L\ \/____/\/___/ \/_/\/_/\/___/ \/___/ \/____/\/____/
\ \_\ /\____/
\/_/ \_/__/
Server running on http://localhost:9876
http://localhost:9876 in your browser. You’ll see the SQL editor with the schema browser on the left.
Demo mode
If you run pgconsole without --config, it starts in demo mode with an embedded in-memory PostgreSQL database pre-loaded with sample data:
docker run -p 9876:9876 pgplex/pgconsole
npm install -g @pgplex/pgconsole
pgconsole
Demo mode data is ephemeral and resets on every restart. To connect to a real database, create a pgconsole.toml as shown in Step 1. Docker Compose
Add pgconsole as a service alongside your existing PostgreSQL in Docker Compose:
services:
postgres:
image: postgres:17
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
pgconsole:
image: pgplex/pgconsole
ports:
- "9876:9876"
configs:
- source: pgconsole_config
target: /etc/pgconsole.toml
depends_on:
- postgres
configs:
pgconsole_config:
content: |
[[connections]]
id = "local"
name = "Local PostgreSQL"
host = "postgres"
port = 5432
database = "postgres"
username = "postgres"
password = "postgres"
http://localhost:9876 — pgconsole connects to your database and you can browse schemas, run queries, and edit data immediately.
Kubernetes
Deploy pgconsole as a Deployment with a ConfigMap for the configuration:
apiVersion: v1
kind: ConfigMap
metadata:
name: pgconsole-config
data:
pgconsole.toml: |
[[connections]]
id = "main"
name = "Production PostgreSQL"
host = "postgres.default.svc.cluster.local"
port = 5432
database = "postgres"
username = "postgres"
password = "postgres"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: pgconsole
spec:
replicas: 1
selector:
matchLabels:
app: pgconsole
template:
metadata:
labels:
app: pgconsole
spec:
containers:
- name: pgconsole
image: pgplex/pgconsole
ports:
- containerPort: 9876
volumeMounts:
- name: config
mountPath: /etc/pgconsole.toml
subPath: pgconsole.toml
volumes:
- name: config
configMap:
name: pgconsole-config
---
apiVersion: v1
kind: Service
metadata:
name: pgconsole
spec:
selector:
app: pgconsole
ports:
- port: 9876
targetPort: 9876
kubectl apply -f pgconsole.yaml
kubectl port-forward svc/pgconsole 9876:9876
http://localhost:9876 to access pgconsole.
To expose pgconsole externally with TLS, see Kubernetes Ingress and Kubernetes Gateway API.
Next steps
