Docker pgAdmin: cómo configurar una GUI de PostgreSQL con Docker Compose

Cambiar de sesión, memorizar sintaxis y rezar para no haber tecleado mal una consulta destructiva se hace pesado enseguida. No hay plan de ejecución visual, ni navegador de esquemas, ni una forma sencilla de hacer copias de seguridad. Funciona, sí, pero está lejos de ser ideal.

pgAdmin 4 soluciona esto con una GUI en el navegador diseñada específicamente para PostgreSQL. Y ejecutarlo en Docker significa instalación local cero. Solo tienes que iniciar el contenedor.

En este artículo, te muestro cómo configurar PostgreSQL y pgAdmin 4 con Docker Compose, conectar ambos contenedores y usar el Query Tool de pgAdmin, el navegador de esquemas y las funciones de copia de seguridad.

Para seguir el tutorial, necesitas tener Docker instalado y en ejecución en tu equipo. Si eres nuevo con Docker Compose, lee nuestra guía para ver cómo simplifica el desarrollo con múltiples contenedores.

¿Qué es pgAdmin 4?

pgAdmin 4 es una plataforma de administración y desarrollo para PostgreSQL, de código abierto y basada en el navegador. Accedes desde un navegador web, así que no hay aplicación de escritorio que instalar. Te ofrece una GUI para gestionar bases de datos, ejecutar consultas, inspeccionar esquemas y manejar copias de seguridad, todo sin tocar la línea de comandos.

La imagen oficial de Docker es dpage/pgadmin4, mantenida por el equipo de desarrollo de pgAdmin.

Ejecutar pgAdmin 4 en Docker tiene un par de ventajas claras frente a una instalación local. La primera es la portabilidad: todo tu entorno de base de datos vive en un archivo docker-compose.yml que puedes compartir con tu equipo. La segunda, que no hay conflictos de versiones: pgAdmin se ejecuta en su propio contenedor, completamente aislado de todo lo demás en tu máquina. Y cuando termines, docker compose down lo deja todo limpio.

pgAdmin 4 frente a otras GUIs de PostgreSQL

Hay muchas herramientas GUI para gestionar bases de datos. Así se compara pgAdmin 4 con dos alternativas populares.

pgAdmin 4 frente a alternativas populares

DBeaver y TablePlus son buenas herramientas, pero ninguna tiene imagen oficial de Docker. Si tu instancia de PostgreSQL ya se ejecuta en Docker, pgAdmin 4 encaja de maravilla: solo necesitas añadir un servicio a tu docker-compose.yml y todo funcionará junto en la misma red.

Configuración del entorno con Docker Compose

La forma más rápida de poner PostgreSQL y pgAdmin 4 a correr juntos es con un único archivo docker-compose.yml. Si es tu primera vez con el tema, nuestra guía de Docker Compose cubre los fundamentos. Aquí me centro en la configuración específica de pgAdmin.

Aquí tienes el archivo completo para copiar y pegar:

services:
  postgres:
    image: postgres:18
    container_name: postgres
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql
    networks:
      - pgnetwork

  pgadmin:
    image: dpage/pgadmin4:9.13
    container_name: pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: you@yourdomain.com
      PGADMIN_DEFAULT_PASSWORD: password
      PGADMIN_LISTEN_PORT: 5050 
    ports:
      - "5050:5050"                
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    depends_on:
      - postgres
    networks:
      - pgnetwork

volumes:
  postgres_data:
  pgadmin_data:

networks:
  pgnetwork:

El campo depends_on le indica a Docker Compose que inicie el contenedor postgres antes que pgadmin. Sin esto, pgAdmin podría arrancar antes de que PostgreSQL esté listo y fallar la conexión. No espera a que PostgreSQL esté totalmente saludable, solo a que el contenedor arranque. Aun así, basta para evitar la mayoría de condiciones de carrera.

Variables de entorno de pgAdmin 4

Hay dos variables de entorno obligatorias:

• PGADMIN_DEFAULT_EMAIL: el correo con el que iniciarás sesión en la interfaz web de pgAdmin
• PGADMIN_DEFAULT_PASSWORD: la contraseña de esa cuenta

Hay una tercera opcional que conviene especificar:

• PGADMIN_LISTEN_PORT: el puerto en el que pgAdmin escucha dentro del contenedor. Por defecto es 80, pero ponerlo en 5050 mantiene todo más claro al mapear puertos.

Ahora bien, hardcodear credenciales en el archivo de Compose es mala idea, sobre todo si acaba en control de versiones. Muévelas a un archivo .env.

Crea un archivo .env en el mismo directorio que tu docker-compose.yml:

POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
POSTGRES_DB=mydb
PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=secret

Luego referencia las variables en tu archivo Compose:

# postgres
environment:
  POSTGRES_USER: ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB: ${POSTGRES_DB}
  
# pgadmin
environment:
  PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}
  PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}

Docker Compose detecta archivos .env al ejecutar el comando, así que no necesitas configuración extra. Solo recuerda añadir .env a tu .gitignore y tus credenciales se quedarán fuera del repo.

Volúmenes y persistencia de datos

El volumen mapeado a /var/lib/pgadmin es donde pgAdmin guarda datos como las sesiones, conexiones guardadas a servidores y configuración. Si lo quitas del archivo de Compose, perderás todo cada vez que el contenedor se reinicie.

En el archivo actual de Compose, tienes un volumen con nombre que Docker gestiona en tu host. Los datos persisten a reinicios, recreaciones y actualizaciones de imagen, siempre que no borres explícitamente el volumen con docker volume rm.

Arrancar el stack y acceder a pgAdmin 4

Con tu docker-compose.yml listo, arrancar el stack requiere un solo comando:

docker compose up -d

La opción -d ejecuta ambos contenedores en modo desacoplado: se inician en segundo plano y tu terminal queda libre. Para verificar que ambos están en marcha:

docker ps

Deberías ver postgres y pgadmin listados con estado Up.

Estado de los contenedores

Si algo no cuadra, revisa los logs de pgAdmin:

docker logs pgadmin

Un arranque saludable se ve así:

Logs de inicio de pgAdmin

Si ves un error, probablemente sea uno de estos tres:

• Error de autenticación por contraseña: tu PGADMIN_DEFAULT_PASSWORD falta o está mal formado en el archivo .env

• El puerto ya está asignado: hay algo más usando el puerto 5050; cambia el puerto del host en tu archivo Compose

• No existe el archivo o directorio: la ruta del volumen es incorrecta o el contenedor no tiene permisos de escritura

Cuando ambos contenedores estén arriba y los logs limpios, abre el navegador y ve a http://localhost:5050:

Página de inicio de sesión de pgAdmin

Inicia sesión con el correo y la contraseña que fijaste en PGADMIN_DEFAULT_EMAIL y PGADMIN_DEFAULT_PASSWORD. Llegarás al panel de pgAdmin, listo para registrar tu servidor de PostgreSQL:

Página de inicio de pgAdmin

Conectar pgAdmin 4 a tu contenedor de PostgreSQL

En la barra lateral de pgAdmin, haz clic derecho en Servers - Register - Server. Se abre un diálogo con dos pestañas que debes completar: General y Connection.

La pestaña General

Ponle al servidor un nombre descriptivo, algo como local-dev-postgres. Es solo una etiqueta dentro de pgAdmin, así que elige lo que más sentido tenga para tu configuración.

Registro del servidor - pestaña General

La pestaña Connection

No uses localhost aquí. 

Dentro de una red de Docker, localhost se refiere al propio contenedor, no a tu máquina host ni al contenedor de PostgreSQL. Docker tiene su propio DNS interno y resuelve los nombres de contenedor usando los nombres de servicio definidos en tu docker-compose.yml. Así que si tu servicio de PostgreSQL se llama postgres, ese es el hostname que debes usar.

Rellena los campos así:

• Host name/address: postgres (el nombre del servicio en docker-compose.yml)

• Port: 5432

• Maintenance database: el valor de POSTGRES_DB en tu archivo Compose (p. ej., mydb)

• Username: el valor de POSTGRES_USER (p. ej., admin)

• Password: el valor de POSTGRES_PASSWORD

Haz clic en Save. 

Registro del servidor - pestaña Connection

Si todo está correcto, el servidor aparecerá en la barra lateral y podrás desplegarlo para ver tus bases de datos:

Registro de servidor correcto

Esto significa que ya estás conectado.

Uso del Query Tool

Como ya estás conectado, te enseño lo básico de pgAdmin 4 y de Postgres en general.

Abre el Query Tool desde Tools - Query Tool en el menú superior. La interfaz tiene tres paneles:

• Editor: donde escribes SQL
• Data Output: donde aparecen los resultados tras ejecutar una consulta
• Messages: donde PostgreSQL envía mensajes de estado, errores e información de ejecución

Query tool

Escribir y ejecutar SQL

Vamos a crear una tabla sencilla orders y a añadir algunos datos. Puedes ejecutar cada bloque con el botón Play o con F5, que es el atajo.

Ejecuta esto para crear la tabla:

CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100) NOT NULL,
    product VARCHAR(100) NOT NULL,
    quantity INT NOT NULL,
    order_date DATE DEFAULT CURRENT_DATE
);

Inserta unas cuantas filas:

INSERT INTO orders (customer_name, product, quantity)
VALUES
    ('Alice Johnson', 'Wireless Keyboard', 2),
    ('Bob Smith', 'USB-C Hub', 1),
    ('Carol White', 'Mechanical Keyboard', 3);

Y ahora consulta los datos:

SELECT * FROM orders;

Consulta de datos

Los resultados aparecen en el panel Data Output como una tabla. Puedes ordenar columnas, redimensionarlas y copiar filas directamente desde la cuadrícula.

Leer el plan de consulta visual

Para ver qué pasa por debajo cuando ejecutas una consulta, ejecuta EXPLAIN ANALYZE sobre tu SELECT:

EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_name = 'Alice Johnson';

Resultados de Explain Analyze

El panel Data Output muestra la salida en crudo. Pero pgAdmin tiene una opción mejor. Haz clic en el botón Explain de la barra de herramientas y pgAdmin renderiza el plan de consulta como un gráfico interactivo.

Plan de consulta como gráfico

Ahora es sencillo para esta consulta, pero te dirá mucho más si unes tablas o haces agregaciones de datos más complejas.

Esto importa porque leer la salida cruda de EXPLAIN es lento y propenso a errores. El plan visual deja claro cuándo PostgreSQL hace un escaneo completo de tabla sobre una tabla grande o cuándo existe un índice pero no se está usando.

Gestionar tu esquema de base de datos

La barra lateral de pgAdmin te muestra toda la estructura de tu base de datos y te permite modificarla desde la GUI.

El árbol de la barra lateral es: Servers - el nombre de tu servidor - Databases - tu base de datos - Schemas - public - Tables. Despliega cualquier tabla y verás sus Columns, Indexes y Constraints como nodos hijos. Haz clic en cualquiera para ver los detalles en el panel derecho.

Crear y modificar tablas

Para crear una nueva tabla, haz clic derecho sobre Tables en tu esquema y elige Create - Table. Se abre un diálogo con varias pestañas.

Creación de tablas

En la pestaña General defines el nombre de la tabla. Cambia a la pestaña Columns para añadir columnas: cada fila te permite definir nombre, tipo de dato, longitud y si admite nulos. La pestaña Constraints gestiona claves primarias, foráneas y restricciones únicas.

Para añadir un índice a una tabla existente, despliega la tabla en la barra lateral, haz clic derecho en Indexes y selecciona Create - Index. Elige las columnas a indexar y el tipo de índice; btree es el predeterminado y sirve para la mayoría de casos.

Creación de un índice

Copias de seguridad y restauración

Para hacer una copia de seguridad de una base de datos, ve a Tools - Backup. Tendrás que elegir un formato:

• Custom: formato binario comprimido; la opción más flexible y, en la mayoría de casos, la mejor, ya que permite restaurar tablas individuales
• Plain: un script SQL plano que puedes abrir y leer con cualquier editor de texto
• Tar: un archivo sin comprimir; menos común, pero útil para algunos flujos de restauración

Tras elegir formato y ruta de destino, pgAdmin ejecuta pg_dump en segundo plano y guarda el archivo en tu máquina local.

Creación de una copia de seguridad

Para restaurar, ve a Tools - Restore, selecciona tu archivo de copia y apúntalo a la base de datos destino.

Restaurar desde una copia de seguridad

Si te preguntas por qué es útil, imagina que pruebas una migración destructiva en tu base de datos de desarrollo. Haz primero una copia, ejecuta la migración y, si algo se rompe, restaura la copia para volver a un estado conocido.

Buenas prácticas para ejecutar pgAdmin 4 en Docker

Poner pgAdmin 4 en marcha es una cosa. Mantenerlo funcionando sin problemas requiere saber un par de cosas más. Aquí van algunos consejos prácticos.

Mantén las credenciales fuera de tu archivo Compose

Si tu docker-compose.yml acaba en control de versiones —y suele hacerlo—, las contraseñas hardcodeadas irán con él. Usa un archivo .env para las credenciales y añádelo a .gitignore. En producción, ve un paso más allá y utiliza secretos de Docker, que montan valores sensibles como archivos en lugar de variables de entorno.

No expongas nunca el puerto de pgAdmin públicamente

Por defecto, Docker enlaza puertos a 0.0.0.0, es decir, a cualquier interfaz de red, incluidas las públicas. En un servidor remoto, eso hace que tu instancia de pgAdmin sea accesible desde Internet. Enlaza explícitamente a 127.0.0.1:

ports:
  - "127.0.0.1:5050:5050"

Así, pgAdmin solo será accesible desde el propio servidor. Usa un túnel SSH o un reverse proxy si necesitas acceso remoto.

Fija las etiquetas de imagen

Usar dpage/pgadmin4:latest descargará una versión nueva la próxima vez que alguien ejecute docker compose pull. Esa versión puede comportarse distinto, romper tu configuración o introducir cambios inesperados. Usa una etiqueta específica como dpage/pgadmin4:9.13 para que todo el equipo ejecute exactamente la misma versión.

Precarga conexiones de servidor con servers.json

Si todo tu equipo comparte el mismo setup de Compose, no hagas que cada persona registre el servidor de PostgreSQL tras levantar el stack. pgAdmin admite un archivo servers.json que preconfigura conexiones al arrancar. Móntalo en el contenedor así:

volumes:
  - ./servers.json:/pgadmin4/servers.json

Así luce un servers.json mínimo:

{
  "Servers": {
    "1": {
      "Name": "local-dev-postgres",
      "Group": "Servers",
      "Host": "postgres",
      "Port": 5432,
      "MaintenanceDB": "mydb",
      "Username": "admin",
      "SSLMode": "prefer"
    }
  }
}

El servidor aparecerá al iniciar pgAdmin, sin necesidad de configuración manual.

Conclusión

En este artículo, te guié para configurar pgAdmin 4 en Docker desde cero. Escribiste un archivo Docker Compose que levanta PostgreSQL y pgAdmin 4 juntos, conectaste ambos contenedores usando el DNS interno de Docker y usaste las funciones clave de pgAdmin: el Query Tool, el navegador de esquemas y el flujo de copia de seguridad/restauración.

La idea central aquí es la reproducibilidad. 

Un archivo docker-compose.yml, un servers.json y un .env son todo lo que necesitas para darle a un compañero un entorno de base de datos totalmente configurado. Así te aseguras de que el problema de “en mi máquina funciona” no vuelva a ocurrir.

Si quieres profundizar en Docker y la contenerización, echa un vistazo a nuestro curso Intermediate Docker. Está lleno de consejos útiles sobre builds multi-stage, redes y un repaso a fondo de Compose.