Docker pgAdmin: cómo configurar una GUI de PostgreSQL con Docker Compose
Guía paso a paso para configurar pgAdmin 4 y PostgreSQL con Docker Compose: incluye la configuración de contenedores, el registro del servidor y las funciones clave de pgAdmin como Query Tool, navegador de esquemas y copia de seguridad/restauración.
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.
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:
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=[email protected]PGADMIN_DEFAULT_PASSWORD=secretCon la tecnología de
Luego referencia las variables en tu archivo Compose:
# postgresenvironment:POSTGRES_USER: ${POSTGRES_USER}POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}POSTGRES_DB: ${POSTGRES_DB}# pgadminenvironment:PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}Con la tecnología de
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:
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:
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:
CREATETABLE orders (
order_id SERIALPRIMARYKEY,
customer_name VARCHAR(100)NOTNULL,
product VARCHAR(100)NOTNULL,
quantity INTNOTNULL,
order_date DATEDEFAULTCURRENT_DATE);Con la tecnología de
Inserta unas cuantas filas:
INSERTINTO orders (customer_name, product, quantity)VALUES('Alice Johnson','Wireless Keyboard',2),('Bob Smith','USB-C Hub',1),('Carol White','Mechanical Keyboard',3);Con la tecnología de
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:
EXPLAINANALYZESELECT*FROM orders WHERE customer_name ='Alice Johnson';Con la tecnología de
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:
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í:
{"Servers":{"1":{"Name":"local-dev-postgres","Group":"Servers","Host":"postgres","Port":5432,"MaintenanceDB":"mydb","Username":"admin","SSLMode":"prefer"}}}Con la tecnología de
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.
Científico de Datos Senior con base en Croacia. Top Tech Writer con más de 700 artículos publicados, generando más de 10M de visitas. Autor del libro Automatización del aprendizaje automático con TPOT.
Docker pgAdmin: preguntas frecuentes
¿Puedo ejecutar pgAdmin 4 en Docker en Windows y macOS?⌄
Sí. La imagen dpage/pgadmin4 funciona en cualquier sistema operativo que admita Docker, incluidos Windows y macOS. El proceso de configuración y el archivo docker-compose.yml son idénticos en todas las plataformas.
¿Tengo que reinstalar pgAdmin 4 cada vez que actualizo la imagen de Docker?⌄
No. Descargar una nueva versión de la imagen no afecta a tus datos guardados mientras hayas mapeado /var/lib/pgadmin a un volumen con nombre. Tus conexiones a servidores, datos de sesión y configuración sobreviven a actualizaciones de imagen y reinicios del contenedor.
¿Es seguro usar pgAdmin 4 en Docker con bases de datos de producción?⌄
pgAdmin 4 en Docker es válido para desarrollo y herramientas internas, pero debes blindarlo antes de apuntarlo a una base de datos en producción. No expongas nunca el puerto de pgAdmin públicamente, usa siempre un archivo .env o secretos de Docker para credenciales y plantéate poner pgAdmin detrás de un reverse proxy con autenticación si necesitas acceso remoto.
¿Por qué no puedo usar `localhost` como hostname al conectar pgAdmin con PostgreSQL?⌄
Dentro de una red de Docker, localhost resuelve al propio contenedor, no a tu máquina host ni a otros contenedores. Docker tiene un DNS interno que resuelve nombres de contenedor usando los nombres de servicio definidos en tu docker-compose.yml. Usa el nombre del servicio de PostgreSQL —normalmente postgres— como hostname.
¿Cuál es la diferencia entre los formatos de copia de seguridad Custom, Plain y Tar en pgAdmin?⌄
Custom es un formato binario comprimido que te da la máxima flexibilidad: puedes restaurar tablas individuales en lugar de la base de datos completa. Plain genera un script SQL legible que puedes abrir con cualquier editor de texto, útil para revisar o editar antes de restaurar. Tar es un archivo sin comprimir, menos común, pero compatible con pg_restore para restauraciones selectivas.
Aprende a instalar y configurar la base de datos MySQL dentro de contenedores Docker. El tutorial incluye conceptos como conectarse a servidores MySQL, ejecutar clientes MySQL para conectarse a contenedores, etc.
Descubre cómo mejorar PostgreSQL con capacidades de búsqueda vectorial utilizando pgvector. Este tutorial te guía a través de la instalación, las operaciones básicas y la integración con herramientas de IA.
Aprende a crear, conectar, gestionar, consultar y proteger tu base de datos Azure SQL. Esta guía paso a paso cubre todo lo esencial para una configuración óptima de la base de datos.
Aprende a utilizar los disparadores SQL para automatizar tareas, mantener la integridad de los datos y mejorar el rendimiento de la base de datos. Prueba ejemplos prácticos como los comandos CREATE, ALTER y DROP en MySQL y Oracle.
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.ymlque 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 downlo 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.ymly 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:
El campo
depends_onle indica a Docker Compose que inicie el contenedorpostgresantes quepgadmin. 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 pgAdminPGADMIN_DEFAULT_PASSWORD: la contraseña de esa cuentaHay 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 en5050mantiene 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
.enven el mismo directorio que tudocker-compose.yml:Luego referencia las variables en tu archivo Compose:
Docker Compose detecta archivos
.enval ejecutar el comando, así que no necesitas configuración extra. Solo recuerda añadir.enva tu.gitignorey tus credenciales se quedarán fuera del repo.Volúmenes y persistencia de datos
El volumen mapeado a
/var/lib/pgadmines 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.ymllisto, arrancar el stack requiere un solo comando:La opción
-dejecuta ambos contenedores en modo desacoplado: se inician en segundo plano y tu terminal queda libre. Para verificar que ambos están en marcha:Deberías ver
postgresypgadminlistados con estadoUp.Estado de los contenedores
Si algo no cuadra, revisa los logs de 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_PASSWORDfalta o está mal formado en el archivo.envEl 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_EMAILyPGADMIN_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
localhostaquí.Dentro de una red de Docker,
localhostse 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 tudocker-compose.yml. Así que si tu servicio de PostgreSQL se llamapostgres, ese es el hostname que debes usar.Rellena los campos así:
Host name/address:
postgres(el nombre del servicio endocker-compose.yml)Port:
5432Maintenance database: el valor de
POSTGRES_DBen tu archivo Compose (p. ej.,mydb)Username: el valor de
POSTGRES_USER(p. ej.,admin)Password: el valor de
POSTGRES_PASSWORDHaz 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:
Query tool
Escribir y ejecutar SQL
Vamos a crear una tabla sencilla
ordersy 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:
Inserta unas cuantas filas:
Y ahora consulta los datos:
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 ANALYZEsobre tuSELECT: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
EXPLAINes 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;
btreees 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:
Tras elegir formato y ruta de destino, pgAdmin ejecuta
pg_dumpen 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.ymlacaba en control de versiones —y suele hacerlo—, las contraseñas hardcodeadas irán con él. Usa un archivo.envpara 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 a127.0.0.1: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:latestdescargará una versión nueva la próxima vez que alguien ejecutedocker compose pull. Esa versión puede comportarse distinto, romper tu configuración o introducir cambios inesperados. Usa una etiqueta específica comodpage/pgadmin4:9.13para que todo el equipo ejecute exactamente la misma versión.Precarga conexiones de servidor con
servers.jsonSi 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.jsonque preconfigura conexiones al arrancar. Móntalo en el contenedor así:Así luce un
servers.jsonmínimo: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, unservers.jsony un.envson 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.