Docker – Running PostgreSQL as a container

By mkyong | Updated: September 22, 2023

Viewed: 2,479 (+47 pv/w)

Tags: docker postgresql

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

Tables of contents:

• 1. PostgreSQL as a container
• 2. Specify the PostgreSQL version
• 3. Access the PostgreSQL Container
  • 3.1 docker exec and psql
  • 3.1 pgAdmin for GUI access
• 4. PostgreSQL Container and Volume
• 5. Access the PostgreSQL container log
• 6. Stop the PostgreSQL Container
• 7. Start the PostgreSQL Container again
• 8. Removing the PostgreSQL Container
• 9. References

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.

docker run --name pg-container-name -p 8888:5432 -e POSTGRES_USER=mkyong -e POSTGRES_PASSWORD=password -e POSTGRES_DB=mydb -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=mkyong – Set the username for the PostgreSQL superuser.
• -e POSTGRES_PASSWORD=password – Set the password for the PostgreSQL superuser.
• -e POSTGRES_DB=mydb – 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.

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

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

docker run --name pg-container-name -p 8888:5432 -e POSTGRES_USER=mkyong -e POSTGRES_PASSWORD=password -e POSTGRES_DB=mydb -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 mydb database as the mkyong user.

docker exec -it pg-container-name psql -U mkyong -d mydb

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

mydb=#

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 mkyong, database name mydb.

docker run --name pg-container-name -p 8888:5432 -e POSTGRES_USER=mkyong -e POSTGRES_PASSWORD=password -e POSTGRES_DB=mydb -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.

docker volume create postgres-volumn

Display details for the volume.

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.

 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.

docker run --name pg-container-name -e POSTGRES_USER=mkyong -e POSTGRES_PASSWORD=password -e POSTGRES_DB=mydb -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

  docker logs pg-container-name

6. Stop the PostgreSQL Container

  docker stop pg-container-name

7. Start the PostgreSQL Container again

  docker start pg-container-name

8. Removing the PostgreSQL Container

  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