CheatSheet: Run a PostgreSQL container with Podman and podman-compose

This brief blog post is a short cheat sheet that provides a step-by-step guide for setting up and running a PostgreSQL database container locally using Podman Desktop and podman-compose. It covers installation, configuration, and execution, along with additional notes on maintenance and troubleshooting.

• 1. Install the container runtime Podman Desktop
• 2. Install podman-compose
• 3. Configure podman-compose
• 4. Run podman-compose
• 5. Install the psql application and access the database.
• 6. Show all tables of the postgres database
• 7. Summary and some additional notes

1. Install the container runtime Podman Desktop

Install Podman Desktop as container runtime. Here is an example installation command for brew on macOS.

brew install --cask podman-desktop

The image below shows the running Podman Desktop UI on a local machine.

2. Install podman-compose

The podman-compose installation runs with Python.

• Installation of Python

brew install python
python --version

• Installation of podman-compose

python3 -m pip install --upgrade pip
python3 -m pip install podman-compose

Because the new Python 12 version can cause a problem like error: externally-managed-environment, it may be useful to take a look into How to set up a virtual environment for Python.

python3 -m venv --upgrade-deps ./.venv
source ./.venv/bin/activate

Verify the installation by the invocation of the help with the following command:

podman-compose --help

3. Configure podman-compose

The following code shows a content of a compose.yaml file to run a PostgreSQL database container locally. It maps to two volumes of Podman in the local machine.

version: "3"
volumes:
  data:
  export:
services:
  postgres-sql-eval:
    image: docker.io/postgres:14-alpine
    container_name: postgres-sql-eval
    ports:
      - 5432:5432
    environment:
      - POSTGRES_PASSWORD=postgres
    volumes:
      - data:/var/lib/postgresql/data 
      - export:/export

• Define the volumes in Podman Desktop

Press “Create” and enter volume names for data and export. The image below shop the UI for inserting the name.

• Command line

podman volume create data
podman volume create export

The image below shows the created volumes.

• Command line

podman volume ls

4. Run podman-compose

Start podman-compose with following command:

podman-compose -f ./podman_compose.yaml up

Example output:

podman-compose version: 1.0.6
['podman', '--version', '']
using podman version: 4.8.3
** excluding:  set()
['podman', 'ps', '--filter', 'label=io.podman.compose.project=containers', '-a', '--format', '{{ index .Labels "io.podman.compose.config-hash"}}']
podman volume inspect containers_data || podman volume create containers_data
['podman', 'volume', 'inspect', 'containers_data']
podman volume inspect containers_export || podman volume create containers_export
['podman', 'volume', 'inspect', 'containers_export']
['podman', 'network', 'exists', 'containers_default']

The image below shows running container in compose:

5. Install the psql application and access the database.

The psql application “is a terminal-based front-end to PostgreSQL. It enables you to type in queries interactively, issue them to PostgreSQL, and see the query results.“

• Install the psql application.

brew doctor
brew update
brew install libpq
brew link --force libpq
psql --version

• Example output:

psql (PostgreSQL) 16.1

• Access the database.

export POSTGRES_USERNAME=postgres
export POSTGRES_PASSWORD=postgres
export HOSTNAME=localhost
export PORT=5432
export DATABASENAME=postgres
psql postgres://${POSTGRES_USERNAME}:${POSTGRES_PASSWORD}@${HOSTNAME}:${PORT}/${DATABASENAME}

• Python installation

pip install psycopg2
# or
pip install psycopg2-binary

6. Show all tables of the postgres database

Insert the \dt *.* command to show the tables of the current database.

postgres-# \dt *.*
                           List of relations
       Schema       |          Name           |    Type     |  Owner   
--------------------+-------------------------+-------------+----------
 information_schema | sql_features            | table       | postgres
 information_schema | sql_implementation_info | table       | postgres
 information_schema | sql_parts               | table       | postgres
 information_schema | sql_sizing              | table       | postgres
 pg_catalog         | pg_aggregate            | table       | postgres
 pg_catalog         | pg_am                   | table       | postgres
 pg_catalog         | pg_amop                 | table       | postgres

7. Summary and some additional notes

Podman has become a powerful container runtime over the last few years, and with Podman Desktop and podman-compose, it works well on macOS. It now has a user-friendly and easy-to-consume user interface. But I noticed that you need to delete the default podman machine from time to time.

podman machine rm -f default
podman machine init

You can restart your macOS if you can’t connect to Podman, but Podman is running. If the Podman connection doesn’t work, you can notice the option Kubernetes is not available. Normally, all should work when all options are available, as shown in the image below.

Note: “Podman on MacOS and Windows requires a virtual machine. This is because containers are Linux – containers do not run on any other OS because containers’ core functionality are tied to the Linux kernel.” Podman documentation. (Podman machine on Apple Silicon)

I hope this was useful to you and let’s see what’s next?

Greetings,

Thomas

#python, #podman, #podmancompose, #postgres, #psql, #container, #docker