pgweb

Key Features

• Interactive SQL query editor with syntax highlighting and auto-completion for PostgreSQL
• Real-time table browsing with pagination, sorting, and filtering capabilities
• Schema visualization showing tables, indexes, constraints, and relationships
• Built-in data export functionality supporting CSV, JSON, and XML formats
• Query execution history stored locally in browser for session persistence
• Read-only mode accessible via URL parameter for safe production database browsing
• Responsive web interface that works across desktop and mobile devices
• PostgreSQL 16 Alpine integration with automatic connection configuration via environment variables

Common Use Cases

• 1Local development environment for PostgreSQL-based web applications and APIs
• 2Quick database prototyping and schema design without installing desktop tools
• 3Remote database administration when SSH tunneling to command-line tools is impractical
• 4Team collaboration on database queries and data analysis in shared development environments
• 5Educational environments where students need browser-based database access
• 6Docker-based CI/CD pipelines requiring database inspection and validation steps
• 7Homelab setups for personal projects requiring lightweight database management tools

Prerequisites

• Docker Engine 20.10+ and Docker Compose V2 for container orchestration
• Minimum 512MB available RAM for PostgreSQL and pgweb containers combined
• Port 8081 available on host system for pgweb web interface access
• Basic understanding of PostgreSQL concepts like databases, tables, and SQL queries
• Environment file (.env) with DB_NAME, DB_USER, and DB_PASSWORD variables defined
• Web browser with JavaScript enabled for optimal pgweb interface functionality

docker-compose.yml

1services: 
2  pgweb: 
3    image: sosedoff/pgweb:latest
4    container_name: pgweb
5    restart: unless-stopped
6    ports: 
7      - "8081:8081"
8    environment: 
9      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
10    networks: 
11      - pgweb
12
13  postgres: 
14    image: postgres:16-alpine
15    container_name: postgres
16    environment: 
17      POSTGRES_DB: ${DB_NAME}
18      POSTGRES_USER: ${DB_USER}
19      POSTGRES_PASSWORD: ${DB_PASSWORD}
20    volumes: 
21      - postgres_data:/var/lib/postgresql/data
22    networks: 
23      - pgweb
24
25volumes: 
26  postgres_data: 
27
28networks: 
29  pgweb: 
30    driver: bridge

.env Template

1DB_NAME=mydb
2DB_USER=postgres
3DB_PASSWORD=changeme

Usage Notes

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

pgweb:
  image: sosedoff/pgweb:latest
  container_name: pgweb
  restart: unless-stopped
  ports:
    - "8081:8081"
  environment:
    DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
  networks:
    - pgweb

postgres:
  image: postgres:16-alpine
  container_name: postgres
  environment:
    POSTGRES_DB: ${DB_NAME}
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - pgweb

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  pgweb:
5    image: sosedoff/pgweb:latest
6    container_name: pgweb
7    restart: unless-stopped
8    ports:
9      - "8081:8081"
10    environment:
11      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
12    networks:
13      - pgweb
14
15  postgres:
16    image: postgres:16-alpine
17    container_name: postgres
18    environment:
19      POSTGRES_DB: ${DB_NAME}
20      POSTGRES_USER: ${DB_USER}
21      POSTGRES_PASSWORD: ${DB_PASSWORD}
22    volumes:
23      - postgres_data:/var/lib/postgresql/data
24    networks:
25      - pgweb
26
27volumes:
28  postgres_data:
29
30networks:
31  pgweb:
32    driver: bridge
33EOF
34
35# 2. Create the .env file
36cat > .env << 'EOF'
37DB_NAME=mydb
38DB_USER=postgres
39DB_PASSWORD=changeme
40EOF
41
42# 3. Start the services
43docker compose up -d
44
45# 4. View logs
46docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

1curl -fsSL https://docker.recipes/api/recipes/pgweb/run | bash

Troubleshooting