1. Introduction
In this tutorial, we’ll learn how to run PostgreSQL in a Docker container. This technique eases the setup of the postgres. Therefore, it is an ideal solution for development and testing environments.
Let’s begin.
2. Prerequisites
First, ensure that Docker is installed and running on your machine. If not, follow the official Docker installation guide to set it up.
Next, pull the PostgreSQL Docker image from Docker Hub:
docker pull postgres:latest
This command fetches the latest version of the PostgreSQL image. Alternatively, you can specify a specific version by replacing latest with the desired tag (e.g., 13.2). Find all available tags on the PostgreSQL Docker Hub page.
3. Starting a PostgreSQL Container
To start a PostgreSQL container, run the following command:
docker run --name my-postgres -e POSTGRES_PASSWORD=mysecretpassword -d postgres
Let’s break down this command:
- –name my-postgres: Assigns a name to the container.
- -e POSTGRES_PASSWORD=mysecretpassword: Sets the password for the default postgres user.
- -d: Runs the container in detached mode. Which means the container starts in the background.
- postgres: Specifies the Docker image to use. In this case, we’ll use the latest version.
4. Accessing the PostgreSQL Instance
Now, we should have an instance of PostgreSQL inside a container named my-postgres. Therefore, we can’t use the psql command directly from our terminal as this won’t be available. Instead, we can use the docker exec command to access the PostgreSQL instance within the container:
docker exec -it my-postgres psql -U postgres
Now, we should have a shell we can use to interact with the database. We usually don’t access the database directly. But, right now, it is the only way to access the database.
Let’s configure the container so it exposes the database to the host.
5. Configuring PostgreSQL Container
To connect from the host machine, we need to configure the container so it exposes the database port. To do this, we can use the –publish or -p option to map the container’s port to a host port:
docker run --name my-postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d postgres
Now, we’ll have access to the database from the host machine if we connect to localhost:5432. Additionally, we set the password for the postgres user so we can use a database client, such as DBeaver, to connect to the database.
Trying to remember these commands can be difficult. Instead, we could use a docker-compose.yml file to define our container. Doing so, we can also share the configuration with our team.
Let’s stop and delete the current container:
docker stop my-postgres
docker rm my-postgres
Now, we can create our docker-compose.yml file.
6. Using Docker Compose
A docker-compose is just a file description of the containers we want to run in the YAML format. Let’s create a docker-compose.yml file for the Postgresql container:
version: '3.1'
services:
db:
image: postgres
restart: always
environment:
POSTGRES_PASSWORD: mysecretpassword
ports:
- 5432:5432
Above, we are defining a service named db with similar configurations as before. The only thing new here is the restart option. In short, we tell Docker always to restart the container if it stops, for example, due to an error or system reboot.
Let’s run the container using the docker-compose command from the same directory where we saved this file:
docker-compose up -d
Again, we use the -d option to run the container in detached mode.
To stop and remove the container, we can use the docker-compose down command:
docker-compose down
Now, we know how to create a local database easily using Docker. But remember, this is not suitable for production. We need to consider other things for our production environment.
If we have the opportunity, we should opt for a managed database service—for example, Amazon RDS, Google Cloud SQL, or Azure Database for PostgreSQL.
7. Persisting the PostgreSQL Container Data
With the current setup, if we remove the PostgreSQL container, we also lose the data contained within it. To persist data, we can mount a local folder to the container using the –volume or -v option. For example:
docker run --name my-postgres -e POSTGRES_PASSWORD=mysecretpassword -v /path/to/local/folder:/var/lib/postgresql/data -d postgres
In short, PostgreSQL data will use the folder path/to/local/folder for its contents. So, if we remove the container and recreate it with the same volume, the data will still be there.
8. Conclusion
In this tutorial, we learned how to run and configure PostgreSQL in a Docker container. We showed first a quick command to have a running instance of the database. Then, we used a docker-compose.yml file to define the container. Finally, we discussed persisting the data by mounting a local folder to the container.