Visualizar tus bases de datos PostgreSQL con pgAdmin

Muchas aplicaciones utilizan bases de datos PostgreSQL en su pila de aplicaciones. Sin embargo, no todos los desarrolladores están familiarizados con la navegación y el trabajo con bases de datos PostgreSQL.

Afortunadamente, cuando utilizas contenedores en el desarrollo, es sencillo agregar servicios adicionales para ayudar con la resolución de problemas y la depuración.

La herramienta pgAdmin es una opción popular de código abierto diseñada para ayudar a administrar y visualizar bases de datos PostgreSQL.

En esta guía aprenderás a:

1. Agregar pgAdmin a tu pila de aplicaciones
2. Configurar pgAdmin para conectarse automáticamente a la base de datos de desarrollo

Agregar pgAdmin a tu pila

1. En tu archivo compose.yaml, agrega el servicio pgadmin junto a tu servicio postgres existente:

   services:
     postgres:
       image: postgres:18
       environment:
         POSTGRES_USER: postgres
         POSTGRES_PASSWORD: secret
         POSTGRES_DB: demo
   
     pgadmin:
       image: dpage/pgadmin4:9.8
       ports:
         - 5050:80
       environment:
         # Requerido por pgAdmin
         PGADMIN_DEFAULT_EMAIL: [email protected]
         PGADMIN_DEFAULT_PASSWORD: secret
   
         # No requiere que el usuario inicie sesión
         PGADMIN_CONFIG_SERVER_MODE: 'False'
   
         # No requiere una contraseña "maestra" después de iniciar sesión
         PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: 'False'

2. Inicia la pila de Compose con el siguiente comando:

   $ docker compose up
   

   Después de que se descargue la imagen y el contenedor se inicie, verás una salida similar a la siguiente indicando que pgAdmin está listo:

   pgadmin-1   | [2025-09-22 15:52:47 +0000] [1] [INFO] Starting gunicorn 23.0.0
   pgadmin-1   | [2025-09-22 15:52:47 +0000] [1] [INFO] Listening at: http://[::]:80 (1)
   pgadmin-1   | [2025-09-22 15:52:47 +0000] [1] [INFO] Using worker: gthread
   pgadmin-1   | [2025-09-22 15:52:47 +0000] [119] [INFO] Booting worker with pid: 119
   

3. Abre pgAdmin yendo a http://localhost:5050.

4. Una vez en el panel de administración, selecciona el enlace Add New Server para definir un nuevo servidor. Ingresa los siguientes detalles:

   • Pestaña General:
     • Name: postgres
   • Pestaña Connection:
     • Host name/address: postgres
     • Username: postgres
     • Password: secret
     • Activa el campo Save password?

   Important

   Estos detalles de conexión asumen que estás utilizando el fragmento de archivo Compose anterior. Si estás usando un archivo Compose existente, ajusta los detalles de conexión según sea necesario. El campo Host name/address debe coincidir con el nombre de tu servicio postgres.

5. Selecciona el botón Save para crear la base de datos.

Ahora tienes pgAdmin configurado y conectado a tu base de datos contenedorizada. Siéntete libre de navegar, ver las tablas y explorar tu base de datos.

Configurar pgAdmin para que se conecte automáticamente a la base de datos

Aunque tengas pgAdmin en funcionamiento, sería ideal si pudieras abrir la aplicación directamente sin necesidad de configurar la conexión de la base de datos. Reducir los pasos de configuración es una excelente manera de facilitar que tus compañeros aprovechen esta herramienta.

Afortunadamente, existe la posibilidad de conectarse automáticamente a la base de datos.

Warning

Para conectarse automáticamente, las credenciales de la base de datos se comparten mediante archivos de texto plano. Durante el desarrollo local, esto suele ser aceptable ya que los datos locales no son datos reales de clientes. Sin embargo, si estás utilizando datos de producción o confidenciales, se desaconseja totalmente esta práctica.

1. Primero, necesitas definir el servidor en sí, lo cual pgAdmin hace usando un archivo servers.json.

   Agrega lo siguiente a tu archivo compose.yaml para definir un archivo de configuración para el archivo servers.json:

   configs:
     pgadmin-servers:
       content: |
         {
           "Servers": {
             "1": {
               "Name": "Local Postgres",
               "Group": "Servers",
               "Host": "postgres",
               "Port": 5432,
               "MaintenanceDB": "postgres",
               "Username": "postgres",
               "PassFile": "/config/pgpass"
             }
           }
         }

2. El archivo servers.json define un campo PassFile, que es una referencia a los archivos de contraseña de PostgreSQL. A menudo se les conoce como archivo pgpass.

   Agrega la siguiente configuración a tu archivo compose.yaml para definir un archivo pgpass:

   configs:
     pgadmin-pgpass:
       content: |
         postgres:5432:*:postgres:secret

   Esto indicará que cualquier solicitud de conexión a postgres:5432 utilizando el usuario postgres debe proporcionar la contraseña secret.

3. En tu archivo compose.yaml, actualiza el servicio pgadmin para inyectar los archivos de configuración:

   services:
     pgadmin:
       ...
       configs:
         - source: pgadmin-pgpass
           target: /config/pgpass
           uid: "5050"
           gid: "5050"
           mode: 0400
         - source: pgadmin-servers
           target: /pgadmin4/servers.json
           mode: 0444

4. Actualiza la pila de la aplicación ejecutando docker compose up nuevamente:

   $ docker compose up
   

5. Una vez que la aplicación se haya reiniciado, abre tu navegador en http://localhost:5050. Deberías poder acceder a la base de datos sin necesidad de iniciar sesión ni realizar ninguna configuración.

Conclusión

El uso de contenedores facilita no solo la ejecución de las dependencias de tu aplicación, sino también de herramientas adicionales para ayudar con la resolución de problemas y la depuración.

Cuando agregues herramientas, piensa en la experiencia y en las posibles dificultades que tus compañeros de equipo puedan experimentar, y en cómo podrías eliminarlas. En este caso, pudiste dar un paso adicional agregando una configuración para configurar y conectar automáticamente las bases de datos, ahorrando un tiempo valioso a tu equipo.