How to use PGAdmin with a Dockerized Postgres Database

In this guide, I’ll explain how you can use PGAdmin to connect to a PostgreSQL database running in Docker.

This tutorial uses an example project setup with Django. However, it would be applicable to any service that uses PostgreSQL running with Docker Compose.

Prerequisites

You’ll need the following:

The example code (a Dockerized Django and React Project)
Docker Desktop
PGAdmin downloaded and installed

Run Existing Project

Start by cloning the existing project to your local machine:

git clone https://github.com/LondonAppDeveloper/yt-db-django-pg-docker.git

This project contains the following components, all configured to run using Docker / Compose.

Django
React (Frontend)
PostgreSQL Database

Test the project by running the following:

docker compose up

Then, navigate to http://127.0.0.1:8000/admin to view the admin login.

You can create an account to login by running the following:

docker compose run --rm app sh -c "python manage.py createsuperuser"

(then follow the in-terminal steps)

Port Forwarding

The PostgreSQL server we need to connect to is running inside Docker.

Because of this, we need to ensure port forwarding is setup so we can access it via our local network.

This is already done for this project with the following block under out db service in docker-compose.yml:

    ports:
      - 5432:5432

Important: On a live machine, you should generally not allow port 5432 to be accessible by the public internet, as this makes your database vulnerable to attackers. Instead, use an SSH tunnel or at least configure your firewall to limit access to your specific IP address.

Register Server in PGAdmin

Load up PGAdmin which you should already have installed (if not, download it here).

Once loaded, right click Servers (top left) and select Register > Server.

In the General tab, give your server a name (e.g. local-dev-database)

Then, select the Connection tab and configure the following:

Host name/address: 127.0.0.1 – this would be the IP or hostname of the server running PostgreSQL if you are connecting to a remote server
Port: 5432
Username: user – this is the username configured here
Password: localdbpw – this matches the password configured here
Save password? – Select this to avoid entering the password every time you connect, however don’t set it on a shared machine

Once done, click Save.

You should be connected to the database right away…

On the “Dashboard” you can see some basic stats about sessions, transactions, etc.

On the left, you can expand the tree view to see a list of tables in your database schema.

Using PGAdmin

PGAdmin is an advanced tool.

We could build an entire course on how to use some of the features.

However, it’s also easy to use for basic things like running simple queries.

Listing Rows in a Table

You can view the contents of a table by right clicking it in the “tables” view and selecting View/Edit Data > All Rows.

This will return all rows in the selected table:

You can make changes and commit them directly to the database using this button:

Note: Be careful when making changes directly, as it will skip any validation checks configured in your Django models.

Running Custom Queries

You can run custom queries on your database by right clicking a table, and selecting Query Tool.

Enter a query, and hit the Run button to execute it.

Summary

That’s how you connect PGAdmin with Django.

This tool is often used for advanced database administration. For example, if you want to run custom queries or reports without writing custom Python code.

I hope you found this useful!