Quickstart

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:

pgconsole.toml

[[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.

That’s the minimum config. See Config Reference for authentication, access control, AI providers, and more.

Step 2: Start

Docker (Recommended)

docker run -p 9876:9876 -v /path/to/pgconsole.toml:/etc/pgconsole.toml pgplex/pgconsole

npx

npx @pgplex/pgconsole --config /path/to/pgconsole.toml

npm

npm install -g @pgplex/pgconsole
pgconsole --config /path/to/pgconsole.toml

Once you see the banner in your terminal, pgconsole is ready:

    /\_ \
 _____      __     ___    ___     ___     ____    ___\//\ \      __
/\ '__`\  /'_ `\  /'___\ / __`\ /' _ `\  /',__\  / __`\\ \ \   /'__`\
\ \ \L\ \/\ \L\ \/\ \__//\ \L\ \/\ \/\ \/\__, `\/\ \L\ \\_\ \_/\  __/
 \ \ ,__/\ \____ \ \____\ \____/\ \_\ \_\/\____/\ \____//\____\ \____\
  \ \ \/  \/___L\ \/____/\/___/  \/_/\/_/\/___/  \/___/ \/____/\/____/
   \ \_\    /\____/
    \/_/    \_/__/

Server running on http://localhost:9876

Open 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

docker run -p 9876:9876 pgplex/pgconsole

npx

npx @pgplex/pgconsole

npm

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:

docker-compose.yml

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"

docker compose up

Open 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:

pgconsole.yaml

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

Open http://localhost:9876 to access pgconsole.

To expose pgconsole externally with TLS, see Kubernetes Ingress and Kubernetes Gateway API.

Cloudflare

pgconsole can run on Cloudflare using Containers — our own demo.pgconsole.com is deployed this way.

Prerequisites: A Cloudflare account with Containers enabled and the Wrangler CLI installed.

See the demo worker source for a complete example — it powers demo.pgconsole.com.

Deploy

Push the Docker image to the Cloudflare container registry and deploy the worker:

# Cloudflare Containers requires an explicit version tag — `latest` is not supported
npx wrangler containers push pgplex/pgconsole:<version>
npx wrangler deploy

Next steps

External Access

Expose pgconsole to your team

SQL Editor

Autocomplete, formatting, inline editing, and more