This blog was originally published in Sept 2021 and was updated in November 2023.
Following the series of blogs started by Peter Zaitsev in Installing MySQL with Docker, on deploying Docker containers running open source databases, in this article, I’ll demonstrate how to install and run PostgreSQL using Docker.
Before proceeding, it is important to remind you of Peter’s warning from his article, which applies here as well:
“The following instructions are designed to get a test instance running quickly and easily; you do not want to use these for production deployments.”
We intend to show how to bring up PostgreSQL instance(s) into Docker containers. Moreover, you will find some basic Docker management operations and some snippets containing examples, always based on the Docker Hub PostgreSQL official image.
What is a PostgreSQL Docker Container?
A PostgreSQL Docker container is a lightweight, standalone, and executable software package that includes all the necessary components to operate a PostgreSQL database server. It encompasses the PostgreSQL server software, along with an execution environment, essential system tools, libraries, and configurations. These Docker containers provide an isolated environment for the database, guaranteeing uniformity across various stages such as development, testing, and production, independent of the base infrastructure.
The Benefits of Using Docker for PostgreSQL
Docker offers a range of advantages for managing PostgreSQL, including the enhancement of development flexibility, deployment streamlining, and consistent environments across different stages of the application lifecycle. Here, we’ll look at a few of these benefits in detail, exploring how Docker’s containerization can significantly boost the efficiency, reliability, and scalability of PostgreSQL deployments.
Provides an isolated environment
Docker containers offer a high level of isolation for PostgreSQL environments, acting like self-contained units to prevent conflicts between different PostgreSQL instances or between PostgreSQL and other applications. Modifications or updates applied to a single Docker container are restricted to that specific container, safeguarding the integrity of others. This characteristic is particularly useful in complex environments where multiple versions or configurations of PostgreSQL need to coexist without interference.
Easy to use
The process of installing PostgreSQL in a Docker container is easy and fast, often accomplished with just a few commands. This is a significant advantage for developers and DBAs, as it reduces the time and effort required for setup and configuration. Additionally, Docker’s portable nature means these PostgreSQL containers can be easily replicated and deployed across different environments, further streamlining the development and deployment process.
Can Run Multiple Versions of PostgreSQL Using Docker
Docker containers enable the simultaneous running of multiple PostgreSQL versions in separate containers, which is beneficial for users who need to test or work with different database versions at the same time. For example, a developer can run legacy and latest versions of PostgreSQL in different containers on the same host, allowing for efficient testing and compatibility checks. Because Docker isolates these environments, every version runs independently, making it a dependable and flexible testing ground.
Enhanced Scalability
Docker containers provide a scalable solution for PostgreSQL, facilitating easy expansion or contraction of database resources as needed. By leveraging tools like Docker Compose, users can quickly orchestrate multiple containers, making it simpler to manage complex PostgreSQL deployments. When integrated with advanced orchestration platforms like Kubernetes, Docker enables the creation of highly available and load-balanced PostgreSQL clusters. This approach allows for seamless scaling, where additional PostgreSQL instances can be deployed effortlessly to handle the increased load and scaled down when demand subsides. Such flexibility is invaluable for maintaining high availability and reliability in varying workload conditions.
Run PostgreSQL in your production and mission-critical environments with certified and tested open source software and tools. Plus, easily deploy and orchestrate reliable PostgreSQL in Kubernetes with Percona for PostgreSQL.
Helps ensure resource efficiency
Unlike traditional virtual machines, Docker containers share the host’s operating system kernel and consume fewer resources, allowing for a higher density of containers on a single machine. This efficient utilization of resources means users can operate several PostgreSQL containers at once without a substantial impact on performance. This method allows users to maintain multiple, separate PostgreSQL environments where resource optimization is crucial.
Better data persistence
Docker containers for PostgreSQL offer robust solutions for data persistence, ensuring that database information remains secure and intact. Through the use of data volumes, Docker allows PostgreSQL data to be stored in a way that is separate from the container’s lifecycle, meaning that the data is not lost when the container is terminated or updated.
Enables rapid deployment
Docker containers are highly valuable for continuous integration/continuous deployment (CI/CD) pipelines and DevOps practices. The containerization of PostgreSQL allows for quick setup and configuration, and this rapid deployment capability is integral to CI/CD workflows, where the ability to consistently and quickly test changes in a database environment is crucial. Docker’s compatibility with various automation tools further enhances this process, allowing for seamless integration into existing DevOps practices.
Installing PostgreSQL using Docker
Starting with the installation, the following example shows how to bring up a Docker container within the latest PostgreSQL release from Docker Hub. It is required to provide the password of the Postgres user at the moment you are launching the container; otherwise, the container will not be created:
1 2 3 | $ docker run --name dockerPostgreSQL -e POSTGRES_PASSWORD=secret -d postgres:latest |
Once you start the container, you can check if it successfully started with docker inspect:
1 2 | $ docker inspect -f '{{.State.Running}}' dockerPostgreSQL true |
If not, you can try starting it manually (you will see how to do it on the Managing the PostgreSQL Containers section).
Getting Connected to the Containerized Instance
The snippet below will show you how to connect to your PostgreSQL containerized instance.
- Directly from docker:
1 2 3 4 | $ docker exec -it dockerPostgreSQL psql --user postgres postgres=# conninfo You are connected to database "postgres" as user "postgres" via socket in "/var/run/postgresql" at port "5432". |
- Or from a PostgreSQL client connecting to its IP address, which you can obtain with the command docker inspect:
1 2 3 4 5 6 | $ docker inspect -f '{{.NetworkSettings.IPAddress}}' dockerPostgreSQL 172.16.0.12 $ psql --user postgres --port 5432 --host 172.16.0.12 postgres=# conninfo You are connected to database "postgres" as user "postgres" on host "172.16.0.12" at port "50432". |
Managing the PostgreSQL Containers
The command below will show you how to list all active containers and their respective statuses:
1 2 3 4 5 | $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7f88656c4864 postgres:11 "docker-entrypoint..." 4 minutes ago Up 4 minutes 0.0.0.0:50432->5432/tcp dockerPostgreSQL11 8aba8609dabc postgres:11.5 "docker-entrypoint..." 21 minutes ago Up 21 minutes 5432/tcp dockerPostgreSQL115 15b9e0b789dd postgres:latest "docker-entrypoint..." 32 minutes ago Up 32 minutes 5432/tcp dockerPostgreSQL |
To stop one of the containers, do:
1 | $ docker stop dockerPostgreSQL |
To start a container:
1 | $ docker start dockerPostgreSQL |
Finally, to remove a container, first stop it and then:
1 | $ docker rm dockerPostgreSQL |
Customizing PostgreSQL Settings in the Container
Let’s say you want to define different parameters for the PostgreSQL server running on Docker. You can create a custom postgresql.conf configuration file to replace the default one used with Docker:
1 | $ docker run --name dockerPostgreSQL11 -p 50433:5432 -v "$PWD/my-postgres.conf":/etc/postgresql/postgresql.conf -e POSTGRES_PASSWORD=scret -d postgres:11 |
Another example of how to pass startup arguments is changing the directory which stores the wal files:
1 | $ docker run --name dockerPostgreSQL11 -p 50433:5432 -v "$PWD/my-postgres.conf":/etc/postgresql/postgresql.conf -e POSTGRES_PASSWORD=scret -e POSTGRES_INITDB_WALDIR=/backup/wal -d postgres:11 |
Running Different PostgreSQL Versions in Different Containers
You can launch multiple PostgreSQL containers, each running a different PostgreSQL version. In the example below, you will find how to start up a 10.5 PostgreSQL version:
1 2 | $ docker run --name dockerPostgreSQL105 -p 50433:5432 -e POSTGRES_PASSWORD=scret -d postgres:10.5 7f51187d32f339688c2f450ecfda6b7552e21a93c52f365e75d36238f5905017 |
Here is how you could launch a PostgreSQL 11 container:
1 2 | $ docker run --name dockerPostgreSQL11 -p 50432:5432 -e POSTGRES_PASSWORD=scret -d postgres:11 7f88656c4864864953a5491705ac7ca882882df618623b1e5664eabefb662733 |
After that, by reissuing the status command, you will see all of the already created ones:
1 2 3 4 5 | $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES e06e637ae090 postgres:10.5 "docker-entrypoint..." 4 seconds ago Up 4 seconds 0.0.0.0:50433->5432/tcp dockerPostgreSQL105 7f88656c4864 postgres:11 "docker-entrypoint..." About an hour ago Up About an hour 0.0.0.0:50432->5432/tcp dockerPostgreSQL11 15b9e0b789dd postgres:latest "docker-entrypoint..." 2 hours ago Up 2 hours 5432/tcp dockerPostgreSQL |
You will notice that both 10.5 and 11 were created with different port mappings. Locally into the container, both are listening on 5432 but are externally mapped to different ports. Therefore, you will be able to access all of them externally.
You will find even more details on the PostgreSQL Hub Docker site.
Percona for PostgreSQL
Percona for PostgreSQL software and services make running performant, highly available PostgreSQL in production and mission-critical environments virtually plug and play. Innovate freely with no need to sift through hundreds of extensions or settle for locked-in forks.
Learn more about Percona for PostgreSQL
FAQs
Can you use PostgreSQL with Docker?
Yes, you can use PostgreSQL with Docker. Docker provides a convenient and efficient way to deploy and manage PostgreSQL containers, allowing for easy setup, scalability, and isolation of database environments.
Should I run PostgreSQL in Docker?
Running PostgreSQL in Docker can be a good choice, especially for development, testing, and staging environments. It offers ease of deployment, consistency across different environments, and the ability to quickly spin up or tear down instances. However, for production environments, it’s important to consider factors like performance, data persistence, and security.
How do I connect a PostgreSQL database with Docker?
To connect to a PostgreSQL database in a Docker container, you first need to run a PostgreSQL container using Docker. After that, utilize typical PostgreSQL connection methods or libraries for the connection, specifying the IP address or hostname of the Docker container, the appropriate port number, and your database login details. Docker also allows port mapping to access the PostgreSQL server using the localhost address on your machine.
