feat: introduce universal database migration system

README.md

@@ -29,9 +29,33 @@ adapterem wybranym w korzeniu aplikacji. Baza działa jako usługa Compose, a je
 trwale przechowuje wolumen `postgres_data`. Przy pierwszym uruchomieniu
 bot importuje istniejące pliki JSON z `config/` do bazy, a pliki źródłowe zostają
 na miejscu jako kopia. Starsze wspólne dane są przypisywane do pierwszego serwera,
-do którego bot należy. Uploady pozostają w
+do którego bot należy. Historia jest zapisywana w kolumnach `id`, `title`, `url`,
+`duration` i `is_local`, wraz z `guild_id` oraz pozycją. Uploady pozostają w
 katalogach `uploads/<guild_id>/`.
 
+### Migracje bazy
+
+Przy uruchomieniu bot automatycznie stosuje oczekujące migracje PostgreSQL.
+Zastosowane wersje i ich nazwy są zapisywane w tabeli `schema_migrations`.
+Każda migracja jest osobną klasą z metodami `apply` i `rollback`, w osobnym
+pliku w `zyrarbot/storage/adapters/postgres/migrations/`. Pliki należy nazywać
+numerami z zerami wiodącymi, aby porządek leksykograficzny pokrywał się z kolejnością,
+na przykład `0001_initial_schema.py`, `0002_add_something.py`. Migrację trzeba
+dodać także do krotki `MIGRATIONS` w `migrations/__init__.py`. Obecna migracja
+`0001_initial_schema` tworzy początkowy schemat.
+
+Rollback wszystkich wersji wykonaj poleceniem:
+
+```bash
+docker compose exec discord-bot python -m zyrarbot.storage.adapters.postgres.migration_runner rollback
+```
+
+Aby cofnąć wersje nowsze niż wskazana, dodaj `--to N`, na przykład `--to 1`
+pozostawi migrację w wersji 1. Przed rollbackiem zatrzymaj bota poleceniem
+`docker compose stop discord-bot`. Rollback wykonuje migracje w odwrotnej kolejności,
+usuwa ich wpisy z `schema_migrations` i może trwale skasować dane z cofanych tabel.
+Po rollbacku uruchomienie bota ponownie zastosuje brakujące migracje.
+
 ## Komendy Discorda
 
 Wszystkie komendy działają w kontekście bieżącego serwera. Discord pokazuje wybór
@@ -86,8 +110,7 @@ zyrarbot/
 │   ├── ports/          GuildConfigRepository, HistoryRepository,
 │   │                   QueueRepository, UploadsRepository, Persistence
 │   ├── adapters/
-│   │   ├── postgres/   PostgresGuildConfig, PostgresHistory, PostgresQueue,
-│   │   │               PostgresPersistence, PostgresDatabase
+│   │   ├── postgres/   adaptery PostgreSQL oraz migrations/ z runnerem
 │   │   ├── filesystem/ Adapter plików uploadu
 │   │   └── json/       Adapter plikowego magazynu JSON
 │   └── upload_file_info.py UploadFileInfo