docker.recipes

PostgreSQL + pgAdmin

beginner

PostgreSQL database with pgAdmin web interface for easy database management and visualization.

Overview

PostgreSQL is a powerful, open-source object-relational database system with over 35 years of active development, known for its reliability, ACID compliance, and advanced features like JSON/JSONB support, full-text search, and extensible type system. Unlike simpler databases, PostgreSQL excels at complex queries, data integrity, and mixed relational-document workloads, making it the preferred choice for enterprise applications and data-intensive systems. pgAdmin4 complements PostgreSQL by providing a comprehensive web-based administration platform specifically designed for PostgreSQL management. This combination eliminates the complexity of command-line database administration while maintaining full access to PostgreSQL's advanced features through an intuitive graphical interface that includes visual query building, performance monitoring, and automated backup tools. This stack is ideal for development teams, database administrators, and organizations that need robust database capabilities with user-friendly management tools. The pairing is particularly valuable for development environments where multiple team members need database access, production systems requiring regular monitoring and maintenance, and educational settings where visual database exploration enhances learning.

Key Features

  • ACID compliance with advanced transaction support and multi-version concurrency control
  • JSON and JSONB data types for hybrid relational-document data models
  • Web-based SQL editor with syntax highlighting and intelligent autocomplete
  • Visual query builder for constructing complex queries without writing SQL
  • Real-time database performance monitoring with query statistics and execution plans
  • Built-in backup and restore functionality with scheduling capabilities
  • Full-text search with ranking, highlighting, and multiple language support
  • PostGIS compatibility for geospatial data operations and geographic queries

Common Use Cases

  • 1Development teams building web applications requiring complex relational data with occasional document-style storage
  • 2Small to medium businesses needing enterprise-grade database features with intuitive management tools
  • 3Educational institutions teaching database concepts with hands-on PostgreSQL experience
  • 4Startups migrating from SQLite or MySQL seeking better JSON support and query capabilities
  • 5Data analysts requiring visual query building and result export functionality
  • 6Organizations implementing microservices that need shared database infrastructure with centralized administration
  • 7GIS applications leveraging PostGIS extensions for location-based services and mapping

Prerequisites

  • Minimum 1.5GB RAM for both services (PostgreSQL: 1GB, pgAdmin: 512MB)
  • Ports 5432 and 5050 available on the host system
  • Basic understanding of SQL concepts and database relationships
  • Familiarity with environment variables for database credentials configuration
  • Docker Engine 20.10+ with Docker Compose V2 support

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  postgres: 
3    image: postgres:16-alpine
4    container_name: postgres
5    restart: unless-stopped
6    environment: 
7      POSTGRES_USER: ${POSTGRES_USER}
8      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
9      POSTGRES_DB: ${POSTGRES_DB}
10    volumes: 
11      - postgres_data:/var/lib/postgresql/data
12    ports: 
13      - "5432:5432"
14    networks: 
15      - postgres-network
16
17  pgadmin: 
18    image: dpage/pgadmin4:latest
19    container_name: pgadmin
20    restart: unless-stopped
21    environment: 
22      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL}
23      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
24    volumes: 
25      - pgadmin_data:/var/lib/pgadmin
26    ports: 
27      - "5050:80"
28    depends_on: 
29      - postgres
30    networks: 
31      - postgres-network
32
33volumes: 
34  postgres_data: 
35  pgadmin_data: 
36
37networks: 
38  postgres-network: 
39    driver: bridge

.env Template

.env
1# PostgreSQL Configuration
2POSTGRES_USER=admin
3POSTGRES_PASSWORD=changeme
4POSTGRES_DB=myapp
5
6# pgAdmin Configuration
7PGADMIN_EMAIL=admin@example.com
8PGADMIN_PASSWORD=changeme

Usage Notes

  1. 1Docs: https://www.postgresql.org/docs/ | pgAdmin: https://www.pgadmin.org/docs/
  2. 2Access pgAdmin at http://localhost:5050 with your PGADMIN_EMAIL/PASSWORD
  3. 3In pgAdmin, add server with hostname 'postgres', port 5432, and your POSTGRES_USER credentials
  4. 4Enable pg_stat_statements for query performance monitoring
  5. 5Backup: docker exec postgres pg_dumpall -U admin > backup.sql
  6. 6Data persisted in postgres_data volume - backup regularly

Individual Services(2 services)

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

postgres
postgres:
  image: postgres:16-alpine
  container_name: postgres
  restart: unless-stopped
  environment:
    POSTGRES_USER: ${POSTGRES_USER}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_DB: ${POSTGRES_DB}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  ports:
    - "5432:5432"
  networks:
    - postgres-network
pgadmin
pgadmin:
  image: dpage/pgadmin4:latest
  container_name: pgadmin
  restart: unless-stopped
  environment:
    PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL}
    PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
  volumes:
    - pgadmin_data:/var/lib/pgadmin
  ports:
    - "5050:80"
  depends_on:
    - postgres
  networks:
    - postgres-network

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  postgres:
5    image: postgres:16-alpine
6    container_name: postgres
7    restart: unless-stopped
8    environment:
9      POSTGRES_USER: ${POSTGRES_USER}
10      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
11      POSTGRES_DB: ${POSTGRES_DB}
12    volumes:
13      - postgres_data:/var/lib/postgresql/data
14    ports:
15      - "5432:5432"
16    networks:
17      - postgres-network
18
19  pgadmin:
20    image: dpage/pgadmin4:latest
21    container_name: pgadmin
22    restart: unless-stopped
23    environment:
24      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL}
25      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
26    volumes:
27      - pgadmin_data:/var/lib/pgadmin
28    ports:
29      - "5050:80"
30    depends_on:
31      - postgres
32    networks:
33      - postgres-network
34
35volumes:
36  postgres_data:
37  pgadmin_data:
38
39networks:
40  postgres-network:
41    driver: bridge
42EOF
43
44# 2. Create the .env file
45cat > .env << 'EOF'
46# PostgreSQL Configuration
47POSTGRES_USER=admin
48POSTGRES_PASSWORD=changeme
49POSTGRES_DB=myapp
50
51# pgAdmin Configuration
52PGADMIN_EMAIL=admin@example.com
53PGADMIN_PASSWORD=changeme
54EOF
55
56# 3. Start the services
57docker compose up -d
58
59# 4. View logs
60docker compose logs -f

One-Liner

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

terminal
1curl -fsSL https://docker.recipes/api/recipes/postgres-pgadmin/run | bash

Troubleshooting

  • Connection refused on port 5432: Ensure PostgreSQL container is fully started before pgAdmin attempts connection, check docker logs postgres
  • pgAdmin login fails with 'Invalid credentials': Verify PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD environment variables are set correctly
  • Cannot connect to server 'postgres' in pgAdmin: Use hostname 'postgres' (container name) not 'localhost' when adding server in pgAdmin interface
  • PostgreSQL data lost after container restart: Confirm postgres_data volume is properly mounted and check volume permissions
  • High memory usage warnings: Adjust PostgreSQL shared_buffers and work_mem settings via POSTGRES_INITDB_ARGS environment variable
  • pgAdmin interface loads slowly: Increase pgAdmin container memory allocation or disable unnecessary pgAdmin features in configuration

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

postgresqlpgadmin4

Tags

#sql#postgres#admin-ui#database

Category

Database Stacks

Related Recipes

Ad Space