partitioning/PARTITIONING.md

PostgreSQL Partitioning for Zabbix

This document describes the declarative partitioning implementation for Zabbix history, trends, and auditlog tables on PostgreSQL. This solution replaces standard Zabbix housekeeping for the configured tables.

Architecture

The solution uses PostgreSQL native declarative partitioning (PARTITION BY RANGE). All procedures and configuration are stored in the partitions schema to maintain separation from Zabbix schema.

Components

1. Configuration Table: partitions.config defines retention policies.
2. Maintenance Procedure: partitions.run_maintenance() manages partition lifecycle.
3. Monitoring View: partitions.monitoring provides system state visibility.

Installation

The installation is performed by executing the SQL procedures in the following order:

1. Initialize schema (00_partitions_init.sql).
2. Prepare tables (e.g., auditlog PK adjustment) (01_auditlog_prep.sql).
3. Install maintenance procedures (02_maintenance.sql).
4. Enable partitioning on tables (03_enable_partitioning.sql).
5. Install monitoring views (04_monitoring_view.sql).

Configuration

Partitioning policies are defined in the partitions.config table.

Column	Type	Description
table_name	text	Name of the Zabbix table (e.g., history, trends).
period	text	Partition interval: day, week, or month.
keep_history	interval	Data retention period (e.g., 30 days, 12 months).
last_updated	timestamp	Timestamp of the last successful maintenance run.

Modifying Retention

To change the retention period for a table, update the configuration:

UPDATE partitions.config 
SET keep_history = '60 days' 
WHERE table_name = 'history';

Maintenance

The maintenance procedure partitions.run_maintenance() is responsible for:

1. Creating future partitions (current period + 3 future buffers).
2. Creating past partitions (backward coverage based on keep_history).
3. Dropping partitions older than keep_history.

This procedure should be scheduled to run periodically (e.g., daily via pg_cron or system cron).

CALL partitions.run_maintenance();

Monitoring & Permissions

System state can be monitored via the partitions.monitoring view.

SELECT * FROM partitions.monitoring;

Versioning

To check the installed version of the partitioning solution:

SELECT * FROM partitions.version ORDER BY installed_at DESC LIMIT 1;

Least Privilege Access (zbx_monitor)

For monitoring purposes, it is recommended to create a dedicated user with read-only access to the monitoring view.

CREATE USER zbx_monitor WITH PASSWORD 'secure_password';
GRANT USAGE ON SCHEMA partitions TO zbx_monitor;
GRANT SELECT ON partitions.monitoring TO zbx_monitor;

Implementation Details

auditlog Table

The standard auditlog table Primary Key is (auditid). Partitioning by clock requires the partition key to be part of the Primary Key. The initialization script modifies the PK to (auditid, clock).

Converting Existing Tables

The enablement script renames the existing table to table_name_old and creates a new partitioned table with the same structure.

• Note: Data from the old table is NOT automatically migrated to minimize downtime.
• New data flows into the new partitioned table immediately.
• Old data remains accessible in table_name_old for manual query or migration if required.

Upgrades

When upgrading Zabbix:

1. Backup: Ensure a full database backup exists.
2. Compatibility: Zabbix upgrade scripts may attempt to ALTER tables. PostgreSQL supports ALTER TABLE on partitioned tables for adding columns, which propagates to partitions.
3. Failure Scenarios: If an upgrade script fails due to partitioning, the table may need to be temporarily reverted or the partition structure manually adjusted.