Hetzner-Backup/v2_adminpanel/docs/PARTITION_MANAGEMENT.md

License Heartbeats Partition Management

Overview

The license_heartbeats table uses PostgreSQL partitioning to efficiently store and query time-series data. Each partition contains data for one month.

Problem

The monitoring dashboard may fail with "relation does not exist" errors when:

1. The current month's partition hasn't been created
2. The license_heartbeats table hasn't been properly initialized

Solution

Automatic Partition Creation

The monitoring routes now automatically:

1. Check if the license_heartbeats table exists
2. Create missing partitions for the current month
3. Handle missing table/partition gracefully by returning empty data

Manual Partition Creation

If needed, you can manually create partitions:

1. Using the migration script:

   docker exec -it v2_adminpanel python apply_partition_migration.py
   

2. Using SQL directly:

   -- Create June 2025 partition
   CREATE TABLE IF NOT EXISTS license_heartbeats_2025_06 PARTITION OF license_heartbeats
       FOR VALUES FROM ('2025-06-01') TO ('2025-07-01');
   

Partition Naming Convention

Partitions follow the naming pattern: license_heartbeats_YYYY_MM

Examples:

• license_heartbeats_2025_01 - January 2025
• license_heartbeats_2025_06 - June 2025
• license_heartbeats_2025_12 - December 2025

Best Practices

1. Pre-create partitions: Create partitions for the next 6 months to avoid runtime issues
2. Monitor partition usage: Check which partitions exist regularly
3. Archive old data: Consider dropping very old partitions to save space

Troubleshooting

If you see "relation does not exist" errors:

1. Check if the base table exists:

   SELECT EXISTS (
       SELECT 1 FROM information_schema.tables 
       WHERE table_name = 'license_heartbeats'
   );
   

2. List existing partitions:

   SELECT tablename FROM pg_tables 
   WHERE tablename LIKE 'license_heartbeats_%'
   ORDER BY tablename;
   

3. Create missing partition for current month:

   -- Replace YYYY_MM with current year and month
   CREATE TABLE IF NOT EXISTS license_heartbeats_YYYY_MM PARTITION OF license_heartbeats
       FOR VALUES FROM ('YYYY-MM-01') TO ('YYYY-MM-01'::date + interval '1 month');