Skip to content

Commit e346b0b

Browse files
mikesir87craig-osterhout
mikesir87
and
craig-osterhout
authored
Add a guide for adding pgAdmin to to application stack (#23441)
## Description Created a new guide that walks users through adding pgAdmin to their application stack to visualize a PostgreSQL database. Also includes details on how to auto-connect to the database using Compose config files. ## Related issues or tickets None ## Reviews - [ ] Technical review - [x] Editorial review - [ ] Product review Would appreciate an editorial review, specifically on the usage of italics/bold around step #4. I believe I followed the editing guidelines correctly, but a second pair of eyes wouldn't hurt. Thanks! --------- Co-authored-by: Craig Osterhout <[email protected]>
1 parent a57178a commit e346b0b

File tree

2 files changed

+171
-0
lines changed

2 files changed

+171
-0
lines changed

‎_vale/config/vocabularies/Docker/accept.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,7 @@ PAT
154154
perl
155155
pgAdmin
156156
PKG
157+
plaintext
157158
plist
158159
Postgres
159160
PowerShell

‎content/guides/pgadmin.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
description: Visualizing your PostgreSQL databases with pgAdmin
3+
keywords: pgadmin, container-supported development
4+
title: Visualizing your PostgreSQL databases with pgAdmin
5+
linktitle: Visualizing your PostgreSQL databases with pgAdmin
6+
summary: |
7+
Explore how to add pgAdmin to your development stack and make it as easy as possible for your teammates to navigate through your PostgreSQL databases.
8+
tags: [databases]
9+
params:
10+
time: 10 minutes
11+
---
12+
13+
Many applications use PostgreSQL databases in the application stack. However, not all developers are knowledgeable about navigating and working with PostgreSQL databases.
14+
15+
Fortunately, when you use containers in development, it is easy to add additional services to help with troubleshooting and debugging.
16+
17+
The [pgAdmin](https://www.pgadmin.org/) tool is a popular open-source tool designed to help administer and visualize PostgreSQL databases.
18+
19+
In this guide you will learn how to:
20+
21+
1. Add pgAdmin to your application stack
22+
2. Configure pgAdmin to automatically connect to the development database
23+
24+
25+
26+
## Adding pgAdmin to your stack
27+
28+
1. In your `compose.yaml` file, add the `pgadmin` service next to your existing `postgres` service:
29+
30+
```yaml
31+
services:
32+
postgres:
33+
image: postgres:17.4
34+
environment:
35+
POSTGRES_USER: postgres
36+
POSTGRES_PASSWORD: secret
37+
POSTGRES_DB: demo
38+
39+
pgadmin:
40+
image: dpage/pgadmin4:9.8
41+
ports:
42+
- 5050:80
43+
environment:
44+
# Required by pgAdmin
45+
PGADMIN_DEFAULT_EMAIL: [email protected]
46+
PGADMIN_DEFAULT_PASSWORD: secret
47+
48+
# Don't require the user to login
49+
PGADMIN_CONFIG_SERVER_MODE: 'False'
50+
51+
# Don't require a "master" password after logging in
52+
PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: 'False'
53+
```
54+
55+
2. Start the Compose stack with the following command:
56+
57+
```console
58+
$ docker compose up
59+
```
60+
61+
After the image is downloaded the container starts, you will see output that looks similar to the following indicating pgAdmin is ready:
62+
63+
```console
64+
pgadmin-1 | [2025-09-22 15:52:47 +0000] [1] [INFO] Starting gunicorn 23.0.0
65+
pgadmin-1 | [2025-09-22 15:52:47 +0000] [1] [INFO] Listening at: http://[::]:80 (1)
66+
pgadmin-1 | [2025-09-22 15:52:47 +0000] [1] [INFO] Using worker: gthread
67+
pgadmin-1 | [2025-09-22 15:52:47 +0000] [119] [INFO] Booting worker with pid: 119
68+
```
69+
70+
3. Open pgAdmin by going to http://localhost:5050.
71+
72+
4. Once in the admin panel, select the **Add New Server** link to define a new server. Enter the following details:
73+
74+
- **General** tab:
75+
- **Name**: `postgres`
76+
- **Connection** tab:
77+
- **Host name/address**: `postgres`
78+
- **Username**: `postgres`
79+
- **Password**: `secret`
80+
- Enable the **Save password?** field
81+
82+
> [!IMPORTANT]
83+
>
84+
> These connection details assume you are using the previous Compose file snippet. If you are using an existing Compose file,
85+
> adjust the connection details as required. The **Host name/address** field should match the name of your postgres service.
86+
87+
5. Select the **Save** button to create the new database.
88+
89+
You now have pgAdmin setup and connected to your containerized database. Feel free to navigate around, view the tables, and explore your database.
90+
91+
92+
93+
## Configuring pgAdmin to auto-connect to the database
94+
95+
Although you have pgAdmin running, it would be nice if you could simply open the app without needing to configure the database connection. Reducing the setup steps would be a great way to make it easier for teammates to get value from this tool.
96+
97+
Fortunately, there is an ability to auto-connect to the database.
98+
99+
> [!WARNING]
100+
>
101+
> In order to auto-connect, the database credentials are shared using plaintext files. During local development, this is often acceptable as local data is not real customer data.
102+
> However, if you are using production or sensitive data, this practice is strongly discouraged.
103+
104+
1. First, you need to define the server itself, which pgAdmin does using a `servers.json` file.
105+
106+
Add the following to your `compose.yaml` file to define a config file for the `servers.json` file:
107+
108+
```yaml
109+
configs:
110+
pgadmin-servers:
111+
content: |
112+
{
113+
"Servers": {
114+
"1": {
115+
"Name": "Local Postgres",
116+
"Group": "Servers",
117+
"Host": "postgres",
118+
"Port": 5432,
119+
"MaintenanceDB": "postgres",
120+
"Username": "postgres",
121+
"PassFile": "/config/pgpass"
122+
}
123+
}
124+
}
125+
```
126+
127+
2. The `servers.json` file defines a `PassFile` field, which is a reference to a [postgreSQL password files](https://www.postgresql.org/docs/current/libpq-pgpass.html). These are often referred to as a pgpass file.
128+
129+
Add the following config to your `compose.yaml` file to define a pgpass file:
130+
131+
```yaml
132+
config:
133+
pgadmin-pgpass:
134+
content: |
135+
postgres:5432:*:postgres:secret
136+
```
137+
138+
This will indicate any connection requests to `postgres:5432` using the username `postgres` should provide a password of `secret`.
139+
140+
3. In your `compose.yaml`, update the `pgadmin` service to inject the config files:
141+
142+
```yaml
143+
services:
144+
pgadmin:
145+
...
146+
configs:
147+
- source: pgadmin-pgpass
148+
target: /config/pgpass
149+
uid: "5050"
150+
gid: "5050"
151+
mode: 0400
152+
- source: pgadmin-servers
153+
target: /pgadmin4/servers.json
154+
mode: 0444
155+
```
156+
157+
4. Update the application stack by running `docker compose up` again:
158+
159+
```console
160+
$ docker compose up
161+
```
162+
163+
5. Once the application is restarted, open your browser to http://localhost:5050. You should be able to access the database without any logging in or configuration.
164+
165+
166+
## Conclusion
167+
168+
Using containers makes it easy to not only run your application's dependencies, but also additional tools to help with troubleshooting and debugging.
169+
170+
When you add tools, think about the experience and possible friction your teammates might experience and how you might be able to remove it. In this case, you were able to take an extra step to add configuration to automatically configure and connect the databases, saving your teammates valuable time.

0 commit comments

Comments
 (0)