14.1 Installing Docker and Running PostgreSQL in Docker

NicePython

— 4 min read

Docker is a powerful platform that allows you to develop, deploy, and run applications inside containers. Containers are lightweight, portable, and consistent environments that make it easy to run software across different platforms. Docker is often used to simplify the process of setting up and running databases like PostgreSQL in isolated environments, without worrying about the complexities of managing dependencies, configurations, or installing software directly on your system.

In this section, we will walk through the steps to install Docker, set up a PostgreSQL database inside a Docker container, and connect to it using Python or database clients.

14.1.1 Installing Docker

1. Install Docker on Your System

Docker can be installed on most operating systems, including Linux, macOS, and Windows. Follow the steps below based on your operating system:

For Linux (Ubuntu/Debian)

Start and enable Docker:

sudo systemctl start docker
sudo systemctl enable docker

Install Docker:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

Set up the Docker repository:

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Add Docker’s official GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Install required packages:

sudo apt install apt-transport-https ca-certificates curl software-properties-common

Update the package list:

sudo apt update
For macOS
  1. Download Docker Desktop from the Docker website.
  2. Install Docker Desktop by following the installation steps.
  3. Launch Docker Desktop, and ensure Docker is running.
For Windows
  1. Download Docker Desktop from the Docker website.
  2. Install Docker Desktop and follow the setup instructions.
  3. Launch Docker Desktop, and ensure Docker is running.
Verify Docker Installation

After installing Docker, verify that it is installed and running correctly:

docker --version

You should see output showing the Docker version.

14.1.2 Running PostgreSQL in a Docker Container

Once Docker is installed, you can quickly set up PostgreSQL in a Docker container. Docker containers allow you to isolate the PostgreSQL instance from your system, making it easy to manage and remove when not needed.

2. Pull the PostgreSQL Docker Image

Docker uses images to create containers. You can pull the official PostgreSQL image from Docker Hub using the following command:

docker pull postgres

This command downloads the latest PostgreSQL image from the Docker Hub registry.

3. Running PostgreSQL in a Docker Container

To run PostgreSQL inside a Docker container, you can use the docker run command. This command will create a new PostgreSQL container, set up the database, and expose the PostgreSQL service to your local machine.

docker run --name my_postgres -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 postgres

In this command:

  • --name my_postgres: Names the container "my_postgres".
  • -e POSTGRES_PASSWORD=mysecretpassword: Sets the PostgreSQL superuser password to mysecretpassword.
  • -d: Runs the container in detached mode (in the background).
  • -p 5432:5432: Maps the container’s PostgreSQL port (5432) to your machine’s port (5432), allowing you to connect to PostgreSQL from your local system.
  • postgres: The name of the PostgreSQL image.

This will start the PostgreSQL server inside the Docker container and expose it on port 5432.

4. Verifying the PostgreSQL Container

After the PostgreSQL container is running, you can verify that it is active using the following command:

docker ps

This will list all running containers, including the PostgreSQL container, which should look something like this:

CONTAINER ID   IMAGE      COMMAND                  CREATED         STATUS         PORTS                    NAMES
c9f9a7e7c9a2   postgres   "docker-entrypoint.s…"   2 minutes ago   Up 2 minutes   0.0.0.0:5432->5432/tcp   my_postgres

14.1.3 Connecting to PostgreSQL in Docker

Now that PostgreSQL is running in a Docker container, you can connect to it using the psql command-line tool, a GUI client, or Python.

1. Connecting with psql

To connect to the PostgreSQL instance running in the Docker container, you can use psql, the PostgreSQL command-line client. If psql is installed on your local machine, you can run the following command:

psql -h localhost -p 5432 -U postgres -W

In this command:

  • -h localhost: Specifies the host as localhost (your machine).
  • -p 5432: Specifies the port (mapped to the Docker container’s port).
  • -U postgres: Specifies the username as postgres (the default superuser).
  • -W: Prompts you to enter the password (mysecretpassword).

2. Connecting with a Database GUI Client

You can also use GUI tools such as pgAdmin, DBeaver, or TablePlus to connect to PostgreSQL running in Docker. Simply use the following connection parameters:

  • Host: localhost
  • Port: 5432
  • Username: postgres
  • Password: mysecretpassword

3. Connecting with Python (psycopg2)

You can connect to PostgreSQL in Docker from Python using the psycopg2 library. Here's an example:

pip install psycopg2

import psycopg2

# Connect to the PostgreSQL instance running in Docker
conn = psycopg2.connect(
    host="localhost",
    port="5432",
    user="postgres",
    password="mysecretpassword",
    database="postgres"
)

# Create a cursor to interact with the database
cursor = conn.cursor()

# Execute a simple query
cursor.execute("SELECT version();")

# Fetch and print the result
result = cursor.fetchone()
print(result)

# Close the connection
cursor.close()
conn.close()

In this example:

  • We connect to the PostgreSQL database running in the Docker container.
  • The PostgreSQL version is retrieved and printed.

14.1.4 Managing PostgreSQL Containers

Docker makes it easy to manage PostgreSQL containers. Here are a few essential commands:

1. Stopping the PostgreSQL Container

To stop the PostgreSQL container, use the following command:

docker stop my_postgres

This stops the running PostgreSQL container.

2. Starting the PostgreSQL Container

To start a previously stopped PostgreSQL container:

docker start my_postgres

3. Removing the PostgreSQL Container

If you no longer need the PostgreSQL container, you can remove it using:

docker rm -f my_postgres

The -f flag forces the removal, even if the container is running.

14.1.5 Persisting PostgreSQL Data with Docker Volumes

By default, when you remove a Docker container, its data is also removed. To persist PostgreSQL data between container runs, you can use Docker volumes.

1. Running PostgreSQL with a Volume

To persist data in a Docker volume, you can use the -v option when starting the PostgreSQL container:

docker run --name my_postgres -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 -v pgdata:/var/lib/postgresql/data postgres

In this command:

  • -v pgdata:/var/lib/postgresql/data: Creates a Docker volume named pgdata to persist the PostgreSQL data in /var/lib/postgresql/data (the default PostgreSQL data directory).

Now, even if you stop or remove the container, the data will remain in the pgdata volume, and it will be available the next time you run the container.

2. Inspecting Volumes

To view all Docker volumes, use:

docker volume ls

This will show the list of volumes, including pgdata.

14.1.6 Summary

In this section, we covered how to:

Install Docker on different operating systems.

  • Run PostgreSQL in a Docker container, isolating your database instance for development or testing purposes.
  • Connect to PostgreSQL from the command-line client, GUI tools, and Python.
  • Manage PostgreSQL containers using Docker commands.
  • Persist PostgreSQL data using Docker volumes.

Using Docker to run PostgreSQL allows you to quickly set up and tear down database instances without modifying your local environment, making it ideal for development and testing. With Docker, you can maintain consistency and simplify database management across different environments.

Read more