Docker – Running PostgreSQL as a container

This article shows how to use Docker to run PostgreSQL as a container.

Technologies used:

• Docker 24.0.5
• Official Docker postgres image (latest tag)

1. PostgreSQL as a container

The below command starts PostgreSQL as a container.

Terminal

docker run --name pg-container-name -p 8888:5432 -e POSTGRES_USER=favtuts -e POSTGRES_PASSWORD=password -e POSTGRES_DB=mytestingdb -d postgres

The command breakdown:

• docker run – Create and run the container.
• --name pg-container-name – Set the container’s name.
• -p 8888:5432 – Set the port mapping. PostgreSQL database defaults expose port 5432, and this command maps the local port 8888 to the container port 5432 (inside Docker).
• -e – Set the environment variables.
• -e POSTGRES_USER=favtuts – Set the username for the PostgreSQL superuser.
• -e POSTGRES_PASSWORD=password – Set the password for the PostgreSQL superuser.
• -e POSTGRES_DB=mytestingdb – Set the name of the database.
• -d – Run the container in a detached mode, which means it runs container in the background.
• postgres – This is the image name we want to pull from the Docker Hub (default). By default, the latest tag is used, which will get the latest version of PostgreSQL.

2. Specify the PostgreSQL version

We can use postgres:tag to specify the version of PostgreSQL that we want to run as a container. By default, the latest tag is used, which will get the latest version of PostgreSQL.

The image postgres:12 will run the PostgreSQL version 12.

Terminal

docker run --name pg-container-name -p 8888:5432 -e POSTGRES_USER=favtuts -e POSTGRES_PASSWORD=password -e POSTGRES_DB=mytestingdb -d postgres:12

The image postgres:14 will run the PostgreSQL version 14.

Terminal

docker run --name pg-container-name -p 8888:5432 -e POSTGRES_USER=favtuts -e POSTGRES_PASSWORD=password -e POSTGRES_DB=mytestingdb -d postgres:14

We can find a list of all available tags on the PostgreSQL Docker Hub page.

3. Access the PostgreSQL Container

Two ways to access the PostgreSQL container.

3.1 docker exec and psql

We can use docker exec to execute a command in a running container. The below command starts a PostgreSQL shell psql connected to the mytestingdb database as the favtuts user.

Terminal

docker exec -it pg-container-name psql -U favtuts -d mytestingdb

psql (15.4 (Debian 15.4-1.pgdg120+1))
Type "help" for help.

mytestingdb=#

3.1 pgAdmin for GUI access

Alternatively, we can use pgAdmin to access the PostgreSQL in the container.

If we use the below command to start the PostgreSQL as the container, the pgAdmin must connect to port 8888 with user favtuts, database name mytestingdb.

Terminal

docker run --name pg-container-name -p 8888:5432 -e POSTGRES_USER=favtuts -e POSTGRES_PASSWORD=password -e POSTGRES_DB=mytestingdb -d postgres

4. PostgreSQL Container and Volume

For databases like PostgreSQL, it is essential to ensure data isn’t lost when the container is stopped or removed. Using Docker volumes, we can store data outside the container, ensuring it persists even if the container is removed.

This example shows how to store the PostgreSQL data using a Docker volume.

4.1 Create a volume named postgres-volumn.

Terminal

docker volume create postgres-volumn

Display details for the volume.

Terminal

docker volume inspect postgres-volumn

[
    {
        "CreatedAt": "2023-09-06T02:27:59Z",
        "Driver": "local",
        "Labels": null,
        "Mountpoint": "/var/lib/docker/volumes/postgres-volumn/_data",
        "Name": "postgres-volumn",
        "Options": null,
        "Scope": "local"
    }
]

4.2 We can use -v to mount a volume to a directory inside the container.

Terminal

 docker run -v postgres-volumn:/path/in/container my-image

4.3 The below command mount the Docker volume postgres-volumn to the PostgreSQL data directory /var/lib/postgresql/data.

Terminal

docker run --name pg-container-name -e POSTGRES_USER=favtuts -e POSTGRES_PASSWORD=password -e POSTGRES_DB=mytestingdb -v postgres-volumn:/var/lib/postgresql/data -d postgres

Now, the system stores all the PostgreSQL data in the postgres-volumn volume. We will still find the data if we remove the container and start a new one using the same volume.

5. Access the PostgreSQL container log

Terminal

  docker logs pg-container-name

6. Stop the PostgreSQL Container

Terminal

  docker stop pg-container-name

7. Start the PostgreSQL Container again

Terminal

  docker start pg-container-name

8. Removing the PostgreSQL Container

Terminal

  docker rm pg-container-name

9. References

• How to Use the Postgres Docker Official Image
• PostgreSQL image in Docker Hub
• Docker – Running MariaDB as a container
• How to access the Docker container’s shell
• How to run an init script for Docker Postgres
• How to list containers in Docker
• How to access the Docker container’s shell
• How to stop and remove all docker containers