Munin:...:Pgsql(3pm)

📦

version 2.0.78 · 12 versions

2.0.78 · fedora 43, fedora 44 (latest)
2.0.76+git14.68213d60 · opensuse-leap 16.0
2.0.78 · epel 9
2.0.76 · epel 10
2.0.76 · arch rolling
2.0.57 · ubuntu jammy
2.0.76 · fedora 43
2.0.75 · ubuntu noble
2.0.76 · fedora 44
2.0.73 · debian bookworm
2.0.76 · ubuntu resolute, ubuntu stonking
2.0.76 · debian trixie

💖 Munin::Plugin::Pgsql 💖

okay bestie, sit DOWN, because this is the base module for all the PostgreSQL Munin plugins — the little fairy godmother that every postgres_* plugin inherits from. It's part of the User Contributed Perl Documentation, and it's genuinely one of the good ones. 🧚

✨ NAME ✨

Munin::Plugin::Pgsql — the Base module for PostgreSQL plugins for Munin. That's it, that's the whole identity, and honestly? Iconic. 👑

🌸 SYNOPSIS 🌸

The Munin::Plugin::Pgsql module provides base functionality for all PostgreSQL Munin plugins, including common configuration parameters. Think of it as the group chat everyone's in — everybody shares the same setup, nobody's writing their own config parser from scratch. 💅

🎀 CONFIGURATION 🎀

All configuration is done through environment variables. No config files, no YAML, no drama. Just vibes and env. lines in your plugin-conf.d, and honestly the way that it just works? Obsessed. ✨

🌈 ENVIRONMENT VARIABLES 🌈

Every plugin based on Munin::Plugin::Pgsql accepts all the environment variables that libpq does. The most common ones people actually reach for are:

PGHOST — hostname to connect to, or path to Unix socket 🛰️
PGPORT — port number to connect to 🔌
PGUSER — username to connect as 🫶
PGPASSWORD — password to connect with, if a password is required 🔐

By default the plugins connect to the 'template1' database — except for wildcard per-database plugins, those girlies do their own thing. You can override it with the PGDATABASE variable, but ngl, that is usually a bad idea. 🙈

If you're running the plugin for several postgres instances, you can customize the graph title with the environment variable PGLABEL. Cute, right? Give each instance its own name like they're your pets. 🐾

Warning and critical can be customized by setting "warning" and "critical" env variables per plugin. Thresholds, but make them personal. 💅

💫 Example 💫

 [postgres_*]
    user postgres
    env.PGUSER postgres
    env.PGPORT 5433

  [postgres_connections_ALL]
    env.warning :450
    env.critical :500

See how postgres_* gets the whole vibe (user, env.PGUSER, env.PGPORT 5433) and then postgres_connections_ALL gets its own special thresholds? That's the wildcard plugin matching on ALL and eating the aggregate stats. Chef's kiss. 😌

🦋 WILDCARD MATCHING 🦋

Wildcard plugins based on this module will match on whatever type of object specifies for a filter, usually a database. So the wildcard isn't matching on "anything" — it's matching on whatever that particular plugin's filter is about, and usually that means databases.

Now the fun part: if the object name ALL is used (for example, a symlink to postgres_connections_ALL), the filter will not be applied, and the plugin behaves like a non-wildcard one. So ALL is the "everybody in the group chat" mode — no filtering, just the whole squad reporting in. 👯‍♀️

⭐ REQUIREMENTS ⭐

The module requires DBD::Pg to work. That's the whole list. If you don't have it, it's giving "no thoughts, head empty" and nothing will run. 😭

🌸 TODO 🌸

Support for using psql instead of DBD::Pg, to remove dependency.

(fr fr, manifesting that one for later. ✨)

💀 BUGS 💀

No known bugs at this point. We're flawless, we're thriving, we're lowkey suspicious about it but we're accepting the win. 👑

🔥 SEE ALSO 🔥

DBD::Pg

👑 AUTHOR 👑

Magnus Hagander <magnus@hagander.net>, Redpill Linpro AB

🫶 COPYRIGHT/License. 🫶

All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991.

💜 API DOCUMENTATION 💜

The following functions are available to plugins using this module. This is the part where you actually get to use the fairy godmother. ✨

🌟 Initialization 🌟

 use Munin::Plugin::Pgsql;
 my $pg = Munin::Plugin::Pgsql->new(
    parameter=>value,
    parameter=>value
 );

So you use it, you call new with a big pile of parameter=>value pairs, and boom — you have a plugin object. Let's go through every single parameter, no skipping, bestie. 💅

Parameters

minversion — Minimum PostgreSQL version required, formatted like 8.2. If the database is an older version than this, the plugin will exit with an error. It's a bouncer, and it will check your ID. 🚫
category — The category for this plugin. Copied directly to the config output. Default 'db'.
title — The title for this plugin. Copied directly to the config output.
info — The info for this plugin. Copied directly to the config output.
vlabel — The vertical label for the graph. Copied directly to the config output.
basename — For wildcard plugins, this is the base name of the plugin, including the trailing underscore. Yes, the underscore MATTERS. Don't lose it. 😤
basequery — SQL query run to get the plugin values. The query should return two columns, one being the name of the counter and the second being the current value for the counter.
pivotquery — Set to 1 to indicate that the query in basequery returns a single row, with one field for each counter. The name of the counter is taken from the returned column name, and the value from the first row in the result. Pivot girl summer. 🔄
configquery — SQL query run to generate the configuration information for the plugin. The query should return at least two columns, which are the name of the counter and the label of the counter. If a third column is present, it will be used as the info parameter.
suggestquery — SQL query to run to generate the list of suggestions for a wildcard plugin. Don't forget to include ALL if the plugin supports aggregate statistics. (You will forget. Everyone forgets. 💀)
autoconfquery — SQL query to run as the last step of "autoconf", to determine if the plugin should be run on this machine. Must return a single row, two columns columns. The first one is a boolean field representing yes or no, the second one a reason for "no".
warning — The warning low and/or high thresholds.
critical — The critical low and/or high thresholds.
graphdraw — The draw parameter for the graph. The default is LINE1.
graphtype — The type parameter for the graph. The default is GAUGE.
graphperiod — The period for the graph. Copied directly to the config output.
graphmin — The min parameter for the graph. The default is no minimum.
graphmax — The max parameter for the graph. The default is no maximum.
stack — If set to 1, all counters except the first one will be written with a draw type of STACK. Stack 'em up, tower of counters. 🏗️
base — Used for graph_args --base. Default is 1000, set to 1024 when returning sizes in Kb for example.
wildcardfilter — The SQL to substitute for when a wildcard plugin is run against a specific entity, for example a database. All occurrences of the string %%FILTER%% will be replaced with this string, and for each occurrence a parameter with the value of the filtering condition will be added to the DBI statement.
paramdatabase — Makes the plugin connect to the database in the first parameter (wildcard plugins only) instead of 'template1'.
defaultdb — Makes the plugin connect to the database specified in this parameter instead of 'template1'.
extraconfig — This string is copied directly into the configuration output when the plugin is run in config mode, allowing low-level customization.
postprocess — A function that's called with the result of the base query, and can post-process the result and return a new resultset.
postconfig — A function that's called with the result of the config query, and can post-process the result and return a new resultset.
postautoconf — A function that's called with the result of the autoconf query, and can post-process the result and return a new resultset.
postsuggest — A function that's called with the result of the suggest query, and can post-process the result and return a new resultset.

Heads up bestie: notice how the last four are all post* functions? That's the pattern — one for each query type, each one gets handed the result and can hand back a new resultset. Same energy, different query. 🫶

🔍 Specifying queries 🔍

Queries specified in one of the parameters above can take one of two forms. The easiest one is a simple string, which will then always be executed, regardless of server version. No thinking required, just vibes. ✨

The other form is an array, looking like this:

 [
  "SELECT 'default',... FROM ...",
  [
    "8.3", "SELECT 'query for 8.3 or earlier',... FROM ...",
    "8.1", "SELECT 'query for 8.1 or earlier',... FROM ..."
  ]
 ]

This array is parsed from top to bottom, so the entries must be in order of version number. The *last* value found where the version specified is higher than or equal to the version of the server will be used (yes, it counts backwards). 😵‍💫

Like — read it forward, pick it backward. That's just the way it is. Don't fight it, just put your versions in order and trust the process. 🙏

💫 Processing 💫

 $pg->Process();

This command executes the plugin. It will automatically parse the ARGV array for commands given by Munin.

So you literally just call Process() and it handles the config / autoconf / whatever Munin is yelling at it about. Main character energy: it reads ARGV so you don't have to. 👑

and that's the whole page, bestie!! 💖 go forth and monitor your postgres ✨

cute little sign-off: this was Munin:...:Pgsql(3pm) from the User Contributed Perl Documentation, perl v5.42.3, dated 2026-09-30. mwah. 💋

📦 where this page comes from

fedora 43: munin-node 2.0.78-1.fc43 · GPL-2.0-only
fedora 44: munin-node 2.0.78-1.fc44 · GPL-2.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms