tbh/breadcrumb-the-shire
1
0
Fork 0
forked from fa/breadcrumb-the-shire
Code Pull Requests Activity
Files
main
breadcrumb-the-shire/docs/howto-fehlerbehebung.md
fs 2e73cb98b4 feat(console): add db:migrate CLI for idempotent core schema updates 
Existing systems used to have no automatic mechanism for the
db/updates/*.sql idempotent updates after `git pull` — devs had to
remember which files were already applied and run new ones manually
with `mariadb < ...`. Mirror module:migrate to fix this:

- New `bin/console db:migrate` walks db/updates/*.sql in alphabetical
  order, skipping anything already recorded in the new core_migrations
  tracking table. Each file runs in its own transaction; failure
  rolls back so the file is retried on the next run.
- New `db:migrate --status` lists applied vs. pending files without
  running anything. Useful for ops debugging "schema seems stale"
  symptoms.
- module:sync now runs db:migrate as its first step, so the standard
  post-pull command stays a single invocation. README's 3-step setup
  is unchanged — module:sync now also covers core schema updates.

CoreMigrationRepository owns its own mysqli connection (using the
same DB credentials as MintyPHP\DB) and runs raw `$mysqli->query()`
instead of going through DB::query's prepared statement path —
MariaDB rejects some DDL (e.g. ALTER TABLE … ADD CONSTRAINT CHECK)
in the prepared protocol, which the existing 18 db/updates files
trip on. ModuleMigrationRepository is left untouched (no module
migration uses such DDL today and changing the vendor pattern is
out of scope).

End-to-end verified: against an existing DB the first run applies
all 19 idempotent files as no-ops and records them, second run
reports "all updates already applied". Against a freshly init'd
DB the same thing happens — no double work, no surprises. All
encrypted seed secrets keep decrypting because APP_CRYPTO_KEY
is unchanged.

Tests: tests/Console/CoreCommandsTest covers success/failure/status
output shapes against a FakeModuleRunner (mirror of the existing
ModuleCommandsTest pattern). 5 stale baseline entries in
phpstan-baseline removed (covered by the new @api annotation on
the test fixture class).

Docs: CLAUDE.md and docs/reference-cli-commands.md document the
new command + --status flag; docs/howto-fehlerbehebung.md gains
a "schema seems stale after git pull" section pointing at
db:migrate --status.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-29 08:59:57 +02:00

3.0 KiB
Raw Permalink Blame History

Fehlerbehebung

Letzte Aktualisierung: 2026-04-29

Schema scheint veraltet nach git pull

Symptom

Nach einem Pull schlagen Queries fehl, weil eine Spalte/Tabelle fehlt — oder der Doctor meldet inkonsistentes Schema.

Lösung

docker compose exec php php bin/console db:migrate --status   # zeigt was fehlt
docker compose exec php php bin/console module:sync           # wendet alles an (db:migrate + module:migrate + ...)

db:migrate wendet idempotente Updates aus db/updates/*.sql an und trackt sie in core_migrations. Auch nach manuellem mariadb < db/updates/...sql sicher: jeder Lauf ist idempotent.

App reagiert nicht wie erwartet

Symptom

UI zeigt alte Daten/Assets oder Verhalten wirkt stale.

Lösung

docker compose restart php nginx

Erstdiagnose mit Doctor

Symptom

Unklar, ob das Problem aus ENV, DB, Storage, RBAC oder Scheduler kommt.

Lösung

docker compose exec php php bin/console doctor

Bei FAIL zuerst diese Punkte beheben, danach erneut ausführen.

Login/API verhalten sich unerwartet

Symptom

401/403 bei API trotz gültigem Token.

Checks

  1. Für geschützte Endpunkte Authorization Header korrekt gesetzt (Bearer <selector:secret>)
  2. Ausnahme: /api/v1/auth/login ist public und benötigt keinen Bearer-Header
  3. Token nicht revoked/abgelaufen
  4. Token hat erforderliche Permission
  5. Bei tenant-scoped Token: Zugriff nur auf passende Tenant-Ressourcen

Migration oder Schema-Probleme

Symptom

Neue Felder/Features fehlen lokal.

Lösung

  1. Aktuelles Schema in db/init/init.sql prüfen
  2. Für Bestandsumgebung idempotentes SQL-Update ausführen
  3. Danach Container neu starten:
docker compose restart php

Hinweis (Hard Cut 2026-03-14)

Das Update db/updates/2026-03-14-user-bookmarks.sql entfernt user_saved_filters bewusst ohne Migration nach user_bookmarks. Zusätzlich wurde der alte Bookmark-Icon-Ansatz pro Eintrag entfernt: Icons gelten nur noch auf Gruppenebene (user_bookmark_groups.icon), bestehende Bookmark-Icons werden nicht übernommen. Wenn gespeicherte Filter noch benötigt werden, vor dem Update ein DB-Backup erstellen.

i18n Fehler

Symptom

Fehlende Translation-Keys oder Mixed-Language UI.

Lösung

docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php tests/I18n/TranslationKeysTest.php

PHPStan/Tests schlagen plötzlich fehl

Symptom

Fehler nach Refactor, obwohl Seite lädt.

Lösung

docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php

Dann gezielt betroffene Datei/Service prüfen.

Swagger UI lädt ungestylt oder inkonsistent

Symptom

API docs sehen nicht nach App-Theme aus.

Lösung

  1. Prüfen, dass Buffer::set('style_groups', json_encode(['api-docs'])) gesetzt ist
  2. Prüfen, dass css/vendor-overrides/swagger-ui.css über config/assets.php eingebunden ist
  3. Hard-Reload im Browser
View Git Blame Copy Permalink