Pinba Engine

Pinba Engine is a MySQL/MariaDB storage engine that collects and analyzes PHP runtime statistics sent over UDP by the Pinba PHP extension.

This is an actively maintained fork of tony2001/pinba_engine with full support for MySQL 8.0 and MySQL 8.4 LTS, and for MariaDB 10.11 and 11.8 LTS from the same source tree. Pre-built packages are available for both databases: Docker images, an Ubuntu PPA (MySQL and MariaDB), and Fedora/Enterprise-Linux RPMs via Copr (MariaDB, plus MySQL on Fedora).

Install

Docker

Pre-built images are published to Docker Hub for both databases — MySQL 8.0 / 8.4 LTS and MariaDB 10.11 / 11.8 LTS:

Database	Tag
MySQL 8.0	xolegator/pinba-engine:8.0
MySQL 8.4 LTS	xolegator/pinba-engine:8.4 (also latest)
MariaDB 10.11 LTS	xolegator/pinba-engine:mariadb-10.11
MariaDB 11.8 LTS	xolegator/pinba-engine:mariadb-11.8

All images are multi-arch (linux/amd64 + linux/arm64) except MySQL 8.0, whose upstream Debian base image is amd64-only.

# MySQL 8.4 LTS
docker run -d \
  --name pinba \
  -e MYSQL_ROOT_PASSWORD=secret \
  -e MYSQL_DATABASE=pinba \
  -p 3306:3306 \
  -p 30002:30002/udp \
  -v pinba-data:/var/lib/mysql \
  xolegator/pinba-engine:8.4

# MariaDB 11.8 LTS
docker run -d \
  --name pinba \
  -e MARIADB_ROOT_PASSWORD=secret \
  -e MARIADB_DATABASE=pinba \
  -p 3306:3306 \
  -p 30002:30002/udp \
  -v pinba-data:/var/lib/mysql \
  xolegator/pinba-engine:mariadb-11.8

The named volume keeps user accounts, plugin registration, and your own tables across container recreations (Pinba's stats tables themselves are in-memory by design).

Validate that the plugin is active:

# MySQL
docker exec pinba mysql -uroot -psecret -e "SHOW PLUGINS LIKE 'pinba';"
# MariaDB
docker exec pinba mariadb -uroot -psecret -e "SHOW PLUGINS LIKE 'pinba';"

See docs/docker.md for full Docker usage including production deployment (Compose, healthchecks), tag stability and digest pinning, validation, and troubleshooting.

Ubuntu / Debian package (PPA)

Packages are available via Launchpad PPA. Each Ubuntu release ships a plugin built for its native MySQL and MariaDB servers — install the one matching your database (the plugin is ABI-bound to the server's major.minor series):

Ubuntu release	MySQL	MariaDB
24.04 Noble	pinba-engine-mysql-8.0	pinba-engine-mariadb-10.11
26.04 Resolute	pinba-engine-mysql-8.4	pinba-engine-mariadb-11.8

sudo add-apt-repository ppa:xolegator/packages
sudo apt-get update
# MySQL (pick your release's series):
sudo apt-get install pinba-engine-mysql-8.0     # 24.04 Noble
# MariaDB (pick your release's series):
sudo apt-get install pinba-engine-mariadb-10.11 # 24.04 Noble

After install, load the plugin and initialize the schema:

mysql -u root -p -e "INSTALL PLUGIN pinba SONAME 'ha_pinba.so';"
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS pinba;"
mysql -u root -p pinba < /usr/share/pinba_engine/default_tables.sql

On package upgrades, the Debian/RPM post-install flow attempts to apply this upgrade automatically when it can reach an active server. If that automatic step is skipped, run the upgrade script manually after deploying the new plugin binary:

mysql -u root -p pinba < /usr/share/pinba_engine/upgrade_hostname_64.sql

Fedora / Enterprise Linux package (Copr RPM)

RPM packages are published to the xolegator/pinba Copr repository, in two mutually-exclusive flavors — install the one matching your database server (x86_64):

Distribution	Database	Package
Fedora 43 / 44	MariaDB	pinba-engine-mariadb
Fedora 43 / 44	MySQL	pinba-engine-mysql
AlmaLinux / Rocky / RHEL 9 / 10	MariaDB	pinba-engine-mariadb

sudo dnf install dnf-plugins-core
sudo dnf copr enable xolegator/pinba
sudo dnf install pinba-engine-mariadb   # or pinba-engine-mysql (Fedora only)

The plugin (ha_pinba.so) and the shared schema (pinba-engine-common) are installed into the server's plugin and data dirs. After install, load the plugin and initialize the schema — use the mariadb client (or mysql for the MySQL flavor):

sudo mariadb -e "INSTALL PLUGIN pinba SONAME 'ha_pinba.so';"
sudo mariadb -e "CREATE DATABASE IF NOT EXISTS pinba;"
sudo mariadb pinba < /usr/share/pinba_engine/default_tables.sql

On package upgrades, the Debian/RPM post-install flow attempts to apply this upgrade automatically when it can reach an active server. If that automatic step is skipped, apply the accompanying upgrade script after the package update:

sudo mariadb pinba < /usr/share/pinba_engine/upgrade_hostname_64.sql

On Enterprise Linux the native database is MariaDB, so only the MariaDB flavor is published there; the MySQL flavor is built for Fedora. The plugin is ABI-matched to each distribution's server version.

Build from source

See docs/build.md for full requirements and options.

Quick start with CMake presets:

cmake --preset release
cmake --build --preset release
# result: build/ha_pinba.so

Documentation

• docs/build.md — build requirements, CMake presets, local plugin install
• docs/docker.md — Docker images: build, run, publish
• docs/tables.md — all table types: core, report1–18, tag_report, tagN_info, rtag_* with COMMENT syntax
• docs/releasing.md — release flow and commit message rules
• API reference — generated Doxygen documentation

License

This project is licensed under the GNU General Public License v2.0 (GPL-2.0-only), inheriting the license of the original Pinba Engine by Antony Dovgal.

Copyright (c) 2007–2009 Antony Dovgal
Copyright (c) 2025–2026 Oleg Ekhlakov

Third-party components bundled in this repository:

Component	Files	License
xxHash	src/xxhash.[ch]	BSD-2-Clause