153 lines
3.5 KiB
Markdown
153 lines
3.5 KiB
Markdown
---
|
|
id: TASK-database-maintenance-docs
|
|
title: Document database maintenance operations
|
|
status: pending
|
|
type: documentation
|
|
team: PM
|
|
supporting_teams: [Backend Senior, Arquitecto de Base de Datos]
|
|
roadmap_item: historical-data-maintenance
|
|
priority: medium
|
|
---
|
|
|
|
# TASK-database-maintenance-docs - Document database maintenance operations
|
|
|
|
## Goal
|
|
|
|
Document how database maintenance works, how to audit database growth, and how to run dry-run/apply safely.
|
|
|
|
## Context
|
|
|
|
Database cleanup will be implemented as application-level maintenance and scheduled inside historical-runner.
|
|
|
|
Operators must understand:
|
|
|
|
- what data is deleted;
|
|
- what data is protected;
|
|
- how to preview deletes;
|
|
- how to enable/disable scheduled cleanup;
|
|
- how to verify table sizes;
|
|
- what not to do in Docker/Portainer.
|
|
|
|
## Steps
|
|
|
|
1. Inspect the listed files first.
|
|
2. Add or update operational documentation.
|
|
3. Include exact commands for PowerShell/Docker.
|
|
4. Include safety warnings.
|
|
5. Validate docs diff.
|
|
6. Commit and push the task branch.
|
|
|
|
## Files to Read First
|
|
|
|
- `README.md`
|
|
- `backend/README.md`
|
|
- `ai/README.md`
|
|
- `backend/app/database_maintenance.py`
|
|
- `backend/app/historical_runner.py`
|
|
- `docker-compose.yml`
|
|
|
|
## Expected Files to Modify
|
|
|
|
Preferred:
|
|
|
|
- `docs/database-maintenance.md`
|
|
|
|
Also update if relevant:
|
|
|
|
- `README.md`
|
|
- `backend/README.md`
|
|
|
|
Do not modify runtime code in this task.
|
|
|
|
## Required Documentation Content
|
|
|
|
Include sections:
|
|
|
|
- Overview
|
|
- Why cleanup is application-level and not `pg_cron`
|
|
- Scheduled cleanup inside `historical-runner`
|
|
- Environment variables
|
|
- Protected data
|
|
- Deleted data
|
|
- Dry-run command
|
|
- Apply command
|
|
- Table-size audit SQL
|
|
- Row-count/age audit SQL
|
|
- Logs to inspect
|
|
- Docker/Portainer warnings
|
|
- Rollback/restore considerations
|
|
|
|
Required environment variables:
|
|
|
|
- `HLL_DB_MAINTENANCE_ENABLED=false`
|
|
- `HLL_DB_MAINTENANCE_INTERVAL_SECONDS=43200`
|
|
- `HLL_RECENT_MATCHES_KEEP=100`
|
|
- `HLL_ADMIN_LOG_NONCRITICAL_RETENTION_DAYS=30`
|
|
- `HLL_ADMIN_LOG_CRITICAL_RETENTION_DAYS=90`
|
|
- `HLL_SERVER_SNAPSHOT_RETENTION_DAYS=14`
|
|
- `HLL_DB_MAINTENANCE_BATCH_SIZE=5000`
|
|
|
|
Required warnings:
|
|
|
|
- Never use `docker compose down -v` unless intentionally deleting volumes.
|
|
- Always review dry-run output before enabling apply in production.
|
|
- Do not manually delete protected match/stat rows from PostgreSQL.
|
|
- Keep backups before changing retention settings.
|
|
- Do not add Comunidad Hispana #03 back into RCON targets in this task.
|
|
|
|
Required SQL:
|
|
|
|
```sql
|
|
select
|
|
schemaname,
|
|
relname as table_name,
|
|
pg_size_pretty(pg_total_relation_size(relid)) as total_size,
|
|
pg_size_pretty(pg_relation_size(relid)) as table_size,
|
|
pg_size_pretty(pg_total_relation_size(relid) - pg_relation_size(relid)) as indexes_size,
|
|
n_live_tup as estimated_rows,
|
|
n_dead_tup as estimated_dead_rows
|
|
from pg_stat_user_tables
|
|
order by pg_total_relation_size(relid) desc;
|
|
```
|
|
|
|
Also include table-specific examples for:
|
|
|
|
- admin log events by type/date;
|
|
- materialized matches by server/date;
|
|
- server snapshots by date;
|
|
- displayed snapshots count.
|
|
|
|
## Validation
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
git diff --check
|
|
```
|
|
|
|
If README files are touched, ensure examples are consistent with the current Compose profiles.
|
|
|
|
## Outcome
|
|
|
|
Document:
|
|
|
|
- files changed;
|
|
- docs sections added;
|
|
- validation performed;
|
|
- any follow-up needed.
|
|
|
|
Codex CLI must commit and push the completed task branch.
|
|
|
|
Suggested implementation branch:
|
|
|
|
`task/database-maintenance-docs`
|
|
|
|
Suggested commit message:
|
|
|
|
`docs: document database maintenance operations`
|
|
|
|
## Change Budget
|
|
|
|
- Documentation only.
|
|
- Prefer fewer than 3 modified files.
|