# 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;
```

### Versioning
To check the installed version of the partitioning solution:
```sql
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.

```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.