Aveek Das
Running the PgAdmin4 web application

Getting started with PostgreSQL on Docker

August 12, 2022 by

In this article, we will learn how to get started using PostgreSQL on Docker. PostgreSQL is one of the most popular open-source databases that is being used by a lot of developers. It is highly stable and has a large community that maintains and supports the database development lifecycle. PostgreSQL can be installed on any operating system like Windows, macOS, and Linux. With the rise in containerization technologies, PostgreSQL can now also be installed using Docker.

Docker is a popular application that enables users to bundle applications into containers that help in the easy deployment of resources. This article will introduce you to the basic concepts of installing and using Docker on a Mac and then pulling a PostgreSQL Docker image from the Docker Hub repository. In addition to PostgreSQL, we will also install PgAmin4 using Docker, which can be used to administer the PostgreSQL instance with Docker.

What is Docker and why do we need it?

Docker is an open-source containerized application technology using which you can deploy your applications easily on-premises or on the cloud. You can bundle your applications into docker images that will already store the necessary configurations required to run the application. During deployment, you need to just run the docker image on the production environment, and all the configurations will be in from the image. In my previous article, How to set up and run SQL Server Docker image, I have talked about installing Docker on a local machine. Please refer to the installation procedure and follow along. Once Docker has been successfully installed, you can check it on the terminal by using the following command.

docker –version

Checking Docker Version - PostgreSQL Docker

Figure 1 – Checking Docker Version

You can check all the images that are installed on the Docker by using the following command.

docker image ls

List all installed Docker Images - PostgreSQL Docker

Figure 2 – List all installed Docker Images

It is important to note that there should be no active installation of the PostgreSQL Docker image or else you need to remove it before proceeding further. You can remove your existing images by using the following command on the terminal.

docker image rm <<IMAGE_NAME>>

Installing the PostgreSQL Docker image

Now, we are good to start pulling the PostgreSQL Docker image to our local machine. Docker images are hosted on a repository on the cloud known as the Docker hub. You can pull images from the Docker hub and can also publish your images to the Docker hub. The official PostgreSQL Docker image can be found on the Docker Hub. To pull the image to your local, you can run the following command on the terminal.

docker pull Postgres

Pulling the PostgreSQL Docker image on local

Figure 3 – Pulling the PostgreSQL Docker image on local

Once the docker image has been pulled to the local machine, you can check all installed images on your local by the following command.

docker image ls

Checking installed images on local

Figure 4 – Checking installed images on local

As you can see in the above figure, the PostgreSQL image has been installed on your machine. Now, that the image is installed, the next step would be to run this image. When we run a Docker image, a new container is created for that image. In other words, a container is a running instance of a Docker image.

Running the PostgreSQL image

To run the docker image for PostgreSQL, you can use the following command.

docker run –name pgsql-dev -e POSTGRES_PASSWORD=Welcome4$ -p 5432:5432 Postgres

In the above command, we call the run method on docker that will create a running instance of an existing docker image. Along with that we also need to pass a few parameters as follows.

  • Name – We need to provide a name for the container that is going to be created when docker will run the image.
  • Environment variables – When running the docker image for PostgreSQL, the only mandatory environment variable that we need to set is the password for the database. The default user is ‘Postgres’.
  • Port – We need to define on which port is the database going to run in the container and which port on the host can be used to access it. As you can see, there are two ports mentioned in the command which are in the form HOST_PORT:DOCKER_PORT.

Finally, we provide the name of the docker image from which the container is to be created.

Running the PostgreSQL docker image

Figure 5 – Running the PostgreSQL docker image

Once you run the command, you can see that the container starts up and is ready to accept database connections. An important point to note here is that we have not executed the command in detached mode, which means the database or the container will be running as long as the terminal is open.

Now to connect to the database, let us open a new terminal window and type the following command.

docker exec -it pgsql-dev bash

This command will start an interactive terminal inside the container. Next, you can start the PostgreSQL by running the following command on the same terminal.

psql -h localhost _U postgres

Interacting with the PSQL command line utility from terminal

Figure 6 – Interacting with the PSQL command-line utility from terminal

You can list all the running databases and execute other SQL statements once connected through the command line utility. If you prefer using the PostgreSQL environment through a GUI, then follow along. We will also install the PgAdmin4 utility and connect it to the PostgreSQL database from it.

Installing the PgAdmin4 docker image

You can follow similar steps while pulling the docker image for PgAdmin4. You can run the following command on a new terminal window.

docker pull dpage/pgadmin4

Installing Docker image for PgAdmin4

Figure 7 – Installing Docker image for PgAdmin4

To run the PgAdmin4 docker image, you need to run the following command.

docker run -e ‘PGADMIN_DEFAULT_EMAIL=test@domain.local’ -e ‘PGADMIN_DEFAULT_PASSWORD=test1234’ -p 8080:80 –name pgadmin4-dev dpage/pgadmin4

The PgAdmin4 image accepts two mandatory environment variables PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD that enable the web application to log in. Along with that, we also specify the port on which the PgAdmin4 will run. We have specified that port 80 of docker shall bind to port 8080 of the host machine. That means the web app will be available on port 8080 from the host machine.

Running the PgAdmin4 image on local

Figure 8 – Running the PgAdmin4 image on local

Once the docker container is up and running, you can head over to the web browser and connect to http://localhost:8080.

Running the PgAdmin4 web application

Figure 9 – Running the PgAdmin4 web application

As you can see, the PgAdmin4 web application is up and running and is available on port 8080. You can use the credentials to log in to the PgAdmin4 console.

Connecting to PostgreSQL database from PgAdmin4

Once you have logged in to the PgAdmin4 console, the final step is to create a server by connecting to the PostgreSQL docker instance that is already running on the machine. For that, we need to know the exact IP address of the PostgreSQL database. We can fetch that information by inspecting the container that is running. Open a new terminal window and type the following command.

docker inspect pgsql-dev

Inspecting PostgreSQL Docker container

Figure 10 – Inspecting PostgreSQL Docker container

Scroll down below until you find the section Networks. bridge.IPAddress. Copy the IPAddress and store it for later use.

Fetching the IPAddress of the PostgreSQL Docker container

Figure 11 – Fetching the IPAddress of the PostgreSQL Docker container

Now that we have the IP address of the PostgreSQL database, head over to the PgAdmin4 window and create a new server. Use the IP Address as copied in the previous step and the password you used while creating the container. Click on Save.

Connecting to the PostgreSQL database

Figure 12 – Connecting to the PostgreSQL database

Once the connection is successful, you will see the dashboard for the instance will open up with the default Postgres database.

Connected to PostgreSQL Docker container

Figure 13 – Connected to PostgreSQL Docker container

Conclusion

In this article, we have learned about installing PostgreSQL on Docker. We have understood how to pull the PostgreSQL Docker image from the repository and then create a container that will run and host the database application within it. We have used the command-line interface to interact with the PostgreSQL database. We have also installed PgAdmin4, a tool used to manage and administer the PostgreSQL instance. Both PostgreSQL and PgAdmin4 are available for standalone installations, however, using Docker enables it to be containerized and you can easily ship the bundle to other machines for deployment.

To learn more about Docker, you can refer to the documentation from Microsoft and Docker documentation.

Aveek Das
Docker, PostgreSQL

About Aveek Das

Aveek is an experienced Data and Analytics Engineer, currently working in Dublin, Ireland. His main areas of technical interest include SQL Server, SSIS/ETL, SSAS, Python, Big Data tools like Apache Spark, Kafka, and cloud technologies such as AWS/Amazon and Azure. He is a prolific author, with over 100 articles published on various technical blogs, including his own blog, and a frequent contributor to different technical forums. In his leisure time, he enjoys amateur photography mostly street imagery and still life. Some glimpses of his work can be found on Instagram. You can also find him on LinkedIn View all posts by Aveek Das

1,142 Views