/
Monitoring PostgreSQL in a Docker Container Using mk_postgres.py

Monitoring PostgreSQL in a Docker Container Using mk_postgres.py

Sept 24, 2025

This guide explains how to set up monitoring for a PostgreSQL database running in a Docker container using the mk_postgres.py plugin for the Checkmk agent.

LAST TESTED ON CHECKMK 2.4.0p CCE

Table of Contents

When using the Agent Bakery, Checkmk will deploy mk_postgres.py by default. If your system requires Python 2, you must manually install the mk_postgres_2.py plugin.


Overview

This guide explains how to monitor a PostgreSQL database running in a Docker container using the mk_postgres.py plugin for the Checkmk agent. It focuses on proper configuration through the Agent Bakery and outlines the necessary environment setup for reliable monitoring.

Plugin Compatibility

Checkmk provides two versions of the PostgreSQL agent plugin:

  • mk_postgres.py – for Python 3 environments.

  • mk_postgres_2.py – for Python 2 environments.



Step-by-step guide


Plugin Deployment via Agent Bakery


To configure the plugin in Checkmk:

  1. Navigate to Setup → Agents → Windows, Linux, Solaris, AIX → Agent rules → PostgreSQL database and sessions (Linux, Windows)




  2. Configure the following settings:

    Required Parameters

    Database username
    The PostgreSQL user used to connect (e.g., postgres)

    Environment file
    A file containing environment variables required by the plugin.

    Example path: /home/user/postgres.env

    Example postgres.env File
    user@postgretest:~$ cat postgres.env 
#export PGDATABASE="checkmk"
export PGPORT="5432"
export PGVERSION="15"

     

    • The PGDATABASE variable is optional.

    • The PGPORT and PGVERSION must reflect your container's PostgreSQL setup.


    Instance Name

    • Leave this blank to allow automatic detection.

    • If specified, it should match the environment file naming convention.

    Instance username
    Again, usually the PostgreSQL user, e.g., postgres

    Path to .pgpass file
    A hidden file on the monitored host’s filesystem, containing a plain-text password string for the instance username.




  3. Click Save and activate changes.



Example behavior:

If the environment file is /home/postgres/db.env, the default instance name becomes db.

Relying on this naming convention is not recommended and only preserved for backward compatibility.


Example of resulting services:


Notes for Dockerized PostgreSQL

Monitoring a PostgreSQL instance in a Docker container works seamlessly with the mk_postgres.py plugin, provided:

  • The environment file and .pgpass file are accessible on the host or via volume mounts.

  • Python 3 is available inside the container or on the host (depending on where the agent runs).

  • The container's PostgreSQL service is reachable by the agent (e.g., via localhost or Docker networking).

Related articles