partitioning/postgresql/procedures/MANUAL.md

# Zabbix Partitioning Deployment Manual

This guide provides a step-by-step process for deploying the PostgreSQL partitioning solution for Zabbix.

**🚨 DANGER: CRITICAL WARNING 🚨**
**BEFORE YOU PROCEED, YOU ABSOLUTELY MUST TAKE A FULL BACKUP OF YOUR ZABBIX DATABASE.**
**DO NOT SKIP THIS STEP. Schema modifications are dangerous. If something goes wrong and you do not have a backup, your historical data will be lost permanently, and we take ZERO responsibility.**

---

## Step 1: Preparation & Safety

Because database migrations can take time (especially on large tables), **never** run these scripts directly in a standard SSH session that might disconnect.

1. Open a safe terminal session using `tmux` or `screen`:
   ```bash
   tmux new -s zabbix_partitioning
   # OR
   screen -S zabbix_partitioning
   ```
2. Disable the Zabbix Housekeeper for History and Trends:
   - Go to your Zabbix Web UI -> **Administration** -> **Housekeeping**.
   - **Uncheck** "Enable internal housekeeping" for **History and Trends**.
   - Click **Update**.
3. Stop your Zabbix Server to ensure no new data is being written during the schema migration:
   ```bash
   sudo systemctl stop zabbix-server
   ```

---

## Step 2: Database Connection & Schema Selection

Connect to your PostgreSQL server as an administrator (e.g., `postgres` or the database owner).

```bash
psql -U postgres -h localhost
```

Once inside `psql`, connect to your Zabbix database (usually named `zabbix`):

```sql
\c zabbix
```

> [!IMPORTANT]
> **Custom Schemas:** By default, Zabbix installs into the `public` schema. If you installed Zabbix into a custom schema (e.g., `zabbix_schema`), you **must** set your `search_path` now before running the scripts, otherwise they will fail to find your tables:
> ```sql
> SET search_path TO zabbix_schema, public;
> ```

---

## Step 3: Execute Installation Scripts

Run the scripts in the following exact order. You can use the `\i` command in `psql` if you are in the `procedures` directory, or specify the full path.

**1. Create the partitioning schema and config tables:**
> [!NOTE]
> **Zabbix 8.0+ Users:** Zabbix 8.0 introduced a new `history_json` table. Before running the script below, open `00_schema_create.sql` in a text editor and uncomment the lines specifically marked for Zabbix 8.0 at the end of the history tables block.

```sql
\i 00_schema_create.sql
```

**2. Install the maintenance logic and functions:**
```sql
\i 01_maintenance.sql
```

**3. Enable Partitioning (MIGRATION STEP):**
*This step renames your existing large tables to `_old` and instantly creates new partitioned tables. This might take a few moments.*
```sql
\i 02_enable_partitioning.sql
```

**4. Create the Monitoring View:**
```sql
\i 03_monitoring_view.sql
```

---

## Step 4: Schedule Automated Maintenance

Partitioning requires a daily job to create new partitions for tomorrow and drop old partitions from last month.

If you are using **AWS RDS** or a managed database with `pg_cron` enabled, run this inside `psql`:

```sql
CREATE EXTENSION IF NOT EXISTS pg_cron;
SELECT cron.schedule('zabbix_partition_maintenance', '30 5,23 * * *', 'CALL partitions.run_maintenance();');
```

*(If you are self-hosting and don't have `pg_cron`, please refer to the `README.md` for instructions on setting up standard OS `cron` or systemd timers.)*

---

## Step 5: Start Zabbix Server

Now that the database is fully partitioned, you can safely start Zabbix Server again:

```bash
sudo systemctl start zabbix-server
```

*(Note: Your old history data remains in tables like `history_old`. It is no longer visible in the UI. If you need it, you must manually insert it into the new tables. See `README.md` for more details.)*

---

## Step 6: Configure Zabbix Agent Monitoring

To ensure your partitions don't run out, you must monitor them. We use Zabbix Agent 2 for this.

1. On your database server (where Zabbix Agent 2 is installed), create the SQL query file using this simple one-liner. Copy and paste the entire block below into your terminal:

```bash
cat << 'EOF' | sudo tee /etc/zabbix/zabbix_agent2.d/partitions.get_all.sql > /dev/null
SELECT 
    table_name,
    period,
    keep_history::text AS keep_history,
    configured_future_partitions,
    actual_future_partitions,
    total_size_bytes,
    EXTRACT(EPOCH FROM (now() - last_updated)) AS age_seconds
FROM partitions.monitoring;
EOF
```

2. Configure the PostgreSQL Plugin by editing `/etc/zabbix/zabbix_agent2.d/plugins.d/postgresql.conf`. Ensure you have defined a session (e.g., `MY_DB`) and enabled custom queries:

```ini
Plugins.PostgreSQL.CustomQueriesPath=/etc/zabbix/zabbix_agent2.d/
Plugins.PostgreSQL.CustomQueriesEnabled=true

# Example Session (replace with your actual credentials)
Plugins.PostgreSQL.Sessions.MY_DB.Uri=tcp://localhost:5432
Plugins.PostgreSQL.Sessions.MY_DB.User=zbx_monitor
Plugins.PostgreSQL.Sessions.MY_DB.Password=your_password
```

3. Restart the Zabbix Agent 2:
```bash
sudo systemctl restart zabbix-agent2
```

---

## Step 7: Import Template in Zabbix

1. Log into your Zabbix Web UI.
2. Go to **Data collection** -> **Templates** and click **Import**.
3. Upload the `template/zbx_pg_partitions_monitor_agent2.yaml` file from this repository.
4. Go to your Database Host in Zabbix, and link the newly imported template: `PostgreSQL Partitioning by Zabbix Agent 2`.
5. On the Host configuration, go to the **Macros** tab. 
6. You will see a macro named `{$PG.CONNSTRING.AGENT2}` with the value `<replace_me>`. 
7. Change `<replace_me>` to the name of the session you configured in Step 6 (e.g., `MY_DB`).
8. Click **Update**.

**Congratulations!** Your Zabbix database is now fully partitioned, optimized, and monitored.