change: Initial version of procedures based partitioning.

PARTITIONING.md

@@ -0,0 +1,90 @@
+# 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:
+
+```sql
+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).
+
+```sql
+CALL partitions.run_maintenance();
+```
+
+## Monitoring & Permissions
+
+System state can be monitored via the `partitions.monitoring` view.
+
+```sql
+SELECT * FROM partitions.monitoring;
+```
+
+### Least Privilege Access (`zbx_monitor`)
+For monitoring purposes, it is recommended to create a dedicated user with read-only access to the monitoring view.
+
+```sql
+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.