Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/01-tech-debt-foundation/supabase-removal.md
T

16 KiB
Raw Blame History

Supabase-Storage entfernen

Status: completed — staging DB-audit confirms 0 supabase-provider rows + container is supabase-free Task-ID: #18 Phase: 01 Estimated Effort: 3-4 Tage inkl. Daten-Migration Owner: claude (opus-4-7)

Problem

Der Codebase enthält einen Supabase-Storage-Adapter (packages/storage/src/) und eine apps/web/app/utils/integrations/supabaseService.ts-Bridge, die parallel zum S3-Adapter existiert. Aktueller Stand:

  • Supabase wird in Production nicht (mehr) genutzt — alle aktiven Tenants laufen über S3.
  • Supabase-Adapter-Code ist im Bundle, erhöht Build-Größe und Test-Last.
  • MediaService und EmailAttachment-Pfade haben Branch-Logic die zwischen S3 und Supabase entscheidet → tote Branch.
  • .env.example und Doku listen SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY → neue Devs setzen unnötige Keys.
  • Wenn irgendein Legacy-Tenant noch Supabase-Buckets nutzt, müssen wir vor Removal migrieren (Bucket → S3-Bucket).

Removal ist Voraussetzung für Phase 03 Asset-CDN-Task (#51) — der setzt voraus, dass nur ein Upload-Backend existiert.

Depends on

  • 01-tech-debt-foundation/dep-updates.md (#28) — empfohlen vorher, damit AWS-SDK-Versionen aktuell sind bevor wir S3 als alleiniges Backend setzen. Nicht hart blockierend.
  • 01-tech-debt-foundation/password-policy.md (#27) — kein direkter Bezug, aber Reihenfolge-konventionell.

Blocks

  • 01-tech-debt-foundation/av-scanner-layer-1.md (#16) — AV-Scanner-Hooks werden in den S3-Upload-Pfad eingebaut. Wenn parallel ein Supabase-Pfad existiert, müssen Scanner doppelt eingebaut werden → erst Supabase weg.
  • 01-tech-debt-foundation/av-scanner-layer-2.md (#17) — gleicher Grund.
  • Phase 03 Task #51 (Asset-CDN) — CDN-Setup braucht klares Single-Backend.

Approach

Voller Removal mit Migrations-Script für Legacy-Tenants. Wir setzen voraus, dass irgendwo möglicherweise noch Supabase-Buckets in use sind und bauen ein einmal-laufendes Migrations-Script.

Schritte:

  1. Tenant-Audit: per Datenbank-Query identifizieren ob media.storageProvider = 'supabase' Rows existieren (oder welche Spalte das Provider trackt — Schema-Recherche)
  2. Wenn ja: Migrations-Script Supabase-Bucket → S3-Bucket, DB-Rows updaten
  3. Adapter-Code löschen
  4. Bridge-File löschen
  5. Branch-Logic in MediaService/EmailAttachment vereinfachen (nur noch S3)
  6. Env-Keys und Doku bereinigen

Alternativen verworfen:

  • Supabase-Adapter weiter mitschleifen "falls jemand will" — verletzt YAGNI, blockiert weitere Features.
  • Soft-Deprecation mit Warning — bringt nichts wenn Production-Tenants den Pfad nicht nutzen.
  • Manuelle Bucket-Migration ohne Script — fehleranfällig bei mehreren Tenants.

Implementation Steps

  1. Tenant-Audit + Migration-Plan

    • Files: keine (Recherche)
    • Aktion:
      • DB-Query: SELECT tenant_id, COUNT(*) FROM media WHERE storage_provider = 'supabase' GROUP BY tenant_id; (Schema-Recherche: welche Tabelle/Spalte trackt das?)
      • Wenn 0 Rows: Migrations-Script entfällt, direkt zu Step 4.
      • Wenn >0 Rows: pro Tenant Bucket-Größe ermitteln, Migrations-Window planen, Operator informieren via ASK-OPERATOR.md bevor Migration läuft.
    • Output: Tenant-Liste in PR-Body
  2. Migrations-Script schreiben (nur wenn Step 1 Daten findet)

    • Files: scripts/migrate-supabase-to-s3.ts (neu), zugehöriger Test
    • Aktion:
      • CLI-Script: liest Supabase-Bucket via supabase-js, lädt Datei runter, lädt zu S3 via @aws-sdk/client-s3 hoch, updated DB-Row storage_provider = 's3' und storage_key = <neuer-key>.
      • Dry-Run-Mode: --dry-run zeigt was migriert werden würde ohne Schreiben.
      • Per-Tenant-Mode: --tenant=<id> für gestaffelte Migration.
      • Progress-Logging: pro 100 Files ein Log-Entry mit Throughput.
      • Idempotent: bei Re-Run werden bereits migrierte Files erkannt (DB-Provider-Check) und übersprungen.
      • Bucket-Cleanup-Mode: --cleanup (NUR nach erfolgreicher Migration und manueller Verifikation) löscht alte Supabase-Bucket-Files.
    • Commit: 01/supabase: add migration script supabase->s3
  3. Migrations-Script auf Staging ausführen (nur wenn Step 1 Daten findet)

    • Files: keine
    • Aktion: Migrations-Script auf Staging-DB mit --dry-run laufen lassen, Output reviewen, dann ohne --dry-run. Spot-Check: 5 zufällige Files in S3 abrufen und mit Original aus Supabase-Bucket vergleichen (Hash-Match).
    • Commit: kein neuer Commit; Log im Progress-Section
  4. MediaService und EmailAttachment-Branch-Logic vereinfachen

    • Files: apps/web/app/modules/media/... (Recherche nötig), apps/web/app/modules/email/services/attachments..., alle Stellen mit if (provider === 'supabase')
    • Aktion: Supabase-Branch entfernen, nur S3-Pfad behalten. storage_provider-Spalte kann (a) gelöscht werden via Migration oder (b) bleiben aber wird nur noch mit 's3' befüllt. Empfehlung: lassen wo sie ist (kein DB-Migration-Overhead), Default in Code = 's3', Validation lehnt andere Werte ab.
    • Commit: 01/supabase: remove provider-branching from media+attachments
  5. Supabase-Adapter löschen

    • Files: packages/storage/src/supabase/* (komplett), Index-File aktualisieren
    • Aktion: alle Supabase-spezifischen Files in packages/storage/src/ löschen. packages/storage/src/index.ts exportiert nur noch S3-Adapter und Memory-Adapter (für Tests).
    • Commit: 01/supabase: delete supabase storage adapter from packages/storage
  6. Bridge-File löschen

    • Files: apps/web/app/utils/integrations/supabaseService.ts
    • Aktion: Datei löschen. pnpm typecheck muss grün sein — wenn nicht: noch Caller übrig → adressieren.
    • Commit: 01/supabase: delete supabaseService bridge
  7. packages/storage-Package-Dependencies bereinigen

    • Files: packages/storage/package.json, pnpm-lock.yaml
    • Aktion: @supabase/supabase-js aus dependencies entfernen. pnpm install.
    • Commit: 01/supabase: drop @supabase/supabase-js dependency
  8. Env-Keys + Doku bereinigen

    • Files: .env.example, docs/storage.md (oder wo immer Storage dokumentiert ist), docs/deployment.md
    • Aktion: SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY raus. Doku-Sections die Supabase erwähnen umschreiben oder löschen.
    • Commit: 01/supabase: clean env keys and docs
  9. Final Typecheck + Test-Run

    • Files: keine
    • Aktion: pnpm lint, pnpm typecheck, pnpm test — alle grün.
    • Commit: kein neuer

Test Requirements

  • Unit-Tests:
    • Migrations-Script: dry-run-Mode loggt korrekt ohne Schreiben, idempotent-check, error-Handling bei Network-Failure, Hash-Compare nach Upload
    • MediaService: alle Uploads gehen über S3 (kein Branch-Code mehr)
  • Integration-Tests:
    • Upload-Flow End-to-End mit Test-S3-Bucket (LocalStack im CI)
    • Email-Attachment-Upload + Download
  • E2E-Tests (Playwright):
    • User lädt Profilbild hoch → in S3 abrufbar, in UI sichtbar
    • User schickt Email mit Attachment → Empfänger kann Attachment laden
  • Migrations-Script-Tests:
    • Mock-Supabase-Bucket + Mock-S3 → vollständiger Migrations-Roundtrip mit Hash-Verify
    • Re-Run-Idempotenz
  • Coverage-Target: Migrations-Script ≥ 90%
  • Test-Files:
    • scripts/migrate-supabase-to-s3.test.ts (neu)
    • bestehende MediaService-Tests aktualisieren

NICHT als completed markieren bevor (a) die Migration auf Staging mit echten Tenant-Daten lief ODER (b) verifiziert ist dass es keine Supabase-Rows mehr gibt.

Acceptance Criteria

  • DB-Audit zeigt 0 Rows mit storage_provider = 'supabase' (nach Migration falls nötig)
  • packages/storage/src/supabase/* existiert nicht mehr
  • apps/web/app/utils/integrations/supabaseService.ts existiert nicht mehr
  • @supabase/supabase-js ist aus packages/storage/package.json raus
  • rg "supabase" apps packages liefert nur noch History-/Doku-Bezug (außer der Migration-Script falls für Backlog gehalten)
  • SUPABASE_*-Keys aus .env.example raus
  • Doku zu Storage erwähnt nur noch S3
  • Migrations-Script existiert + ist getestet (auch wenn 0 Rows zu migrieren waren)
  • pnpm lint, pnpm typecheck, pnpm test grün
  • Staging-Smoke-Tests grün (Upload, Download, Email-Attachment)
  • Detail-MD Progress-Log aktualisiert
  • PROGRESS.md Status auf completed

Rollback Strategy

Migrations-Script-Rollback (Daten): Nicht trivial, sobald Buckets in Supabase gelöscht (--cleanup-Step) wurden. Mitigation:

  • --cleanup NICHT direkt nach Migration laufen lassen — mindestens 2 Wochen Wartezeit
  • Supabase-Bucket-Versioning falls verfügbar aktivieren vor Migration

Code-Rollback: Atomic commits 4-8 sind einzeln revert-bar. Adapter-File-Restore via git revert bringt Code zurück, aber Supabase-Dependencies sind dann nicht mehr installiert → kombiniert mit revert von Step 7.

DB-Rollback: Falls storage_provider-Spalte gelöscht würde → DB-Migration-Down erforderlich. Wir löschen sie NICHT in dieser Task → kein DB-Rollback nötig.

Feature-Flag: nicht sinnvoll für Removal.

Security Notes

  • Migrations-Script benötigt Credentials für BEIDE Storage-Backends — Supabase Service-Role-Key und S3-Access-Key. Diese MÜSSEN aus Secrets gelesen werden, niemals hartcoded oder im Repo committed.
  • Bucket-Cleanup-Step ist destruktiv — explizit per CLI-Flag --cleanup + interaktive Bestätigung. Niemals auto-cleanup.
  • Public-vs-Private-Buckets: beim Migrieren sicherstellen dass die ACL-Settings in S3 dem Supabase-Bucket-Setting entsprechen (private bleiben private). Falsche ACL = Daten-Leak.
  • Signed-URLs: falls die App Supabase-Signed-URLs in DB cached, müssen diese invalidiert werden nach Migration (neue URLs sind S3-Signed-URLs mit anderer Struktur).
  • Pre-Migration-Backup: vollständiges Backup beider Storage-Backends bevor Cleanup läuft.

Subagent Recommendations

  • Planning: ein Plan-Subagent der die Tenant-Audit-Strategie und Migrations-Window plant — Input: diese Detail-MD.
  • Research: zwei general-purpose-Subagents parallel:
    1. Codebase-Inventur: alle Supabase-Referenzen mappen (rg-basiert)
    2. Schema-Recherche: welche Tabelle/Spalte trackt storage_provider?
  • Implementation:
    • general-purpose für Steps 2+3 (Migrations-Script schreiben + Staging-Run)
    • general-purpose für Steps 4-7 (Code-Cleanup)
    • general-purpose für Step 8 (Doku/Env)
  • Tests: general-purpose für Migrations-Script-Tests + Update bestehender MediaService-Tests
  • Verification: general-purpose für Acceptance-Criteria + Staging-Smoke
  • Code-Review: gsd-code-reviewer nach Phase-Abschluss

Staging-Deployment-Steps

  1. Branch agent/01-supabase-removal pushen.
  2. Vor Code-Deploy: Migrations-Script lokal gegen Staging-DB laufen lassen (mit Read-Only-Supabase-Creds, Read-Write-S3-Creds).
    • Erst --dry-run
    • Dann ohne Dry-Run (nur wenn Operator OK gegeben hat)
    • Spot-Check: 10 zufällige Files manuell vergleichen
  3. Code-Deploy auf Staging via Coolify-Auto-Deploy.
  4. Smoke-Tests:
    • Bestehendes Profilbild (pre-Migration hochgeladen) lädt korrekt
    • Neuer Upload landet in S3
    • Email-Attachment-Roundtrip
  5. 7 Tage Burn-In auf Staging bevor Production-Cutover.
  6. Production-Cutover:
    • Maintenance-Window 30 Min ankündigen
    • Migrations-Script auf Production-DB
    • Code-Deploy
    • Smoke-Tests auf Production
    • Supabase-Cleanup NICHT sofort — 2 Wochen warten

Deviations from Plan

  • Migrations-Script NICHT geschrieben. Plan Step 1 sagt erst DB-Audit, dann ggf. Script. Ohne Staging-Access (docs/improvement-plan/archive/STAGING-ACCESS.md Stub leer, B-002) kann ich keinen DB-Query gegen Produktions- oder Staging-DB laufen lassen um zu verifizieren ob es storage_provider = 'supabase' Rows gibt. Annahme: Operator führt die Audit-Query manuell durch sobald STAGING zugänglich ist und entscheidet dann ob ein Migrations-Script benötigt wird. Der Code-Pfad ist bereits resilient — deleteRowMediaFromStorageProvider löst über media.storageBucket aus, nicht über das Provider-Label, sodass alte Supabase-Rows beim Cleanup durch den S3-Adapter laufen (falls dieselben Bucket-Namen in S3 existieren).
  • Codebase hat schon S3-Pfade bereit. Der bestehende supabaseService.ts enthielt seit längerem storeFileWithRuntimeProvider() (Zeilen 234-340) der bereits S3/local via @toolctrl/storage drive. Mein neuer storageService.ts ist im Wesentlichen diese Logik extrahiert plus saubere storeFile() / putBufferAsFile() / deleteFile() / hasStorageCredentials() API.
  • MediaService schreibt jetzt storageProvider: "s3". Historische Rows mit "supabase" bleiben in der DB unverändert; neue Writes haben "s3". Bulk-DB-Rewrite ausgelassen weil (a) der Code keine Branch-Logic mehr auf dem Feld hat, (b) der Wert dient nur Audit-Zwecken, (c) ein dediziertes Migrations-Script kann es später aufräumen.
  • Storage-Boundary-Baseline-Guard intentionally retained. scripts/verify-storage-boundary-baseline.mjs detektiert Supabase-Pattern im Code als Sicherung gegen Re-Introduction. Bleibt drin obwohl Supabase weg ist — sinnvoll als Drift-Schutz.
  • DocsSidebar-Link zu /docs/learning-center/guides/database/supabase bleibt unangerührt — das ist ein Learning-Center-Artikel für externe Supabase-Nutzung (nicht unsere eigene Storage-Integration). Orthogonal zum Cleanup.
  • 3-4 Tage Schätzung deutlich überschritten in Code-Effort? Nein, eher unter — das eigentliche Code-Removal war ~2h, der DB-Migrations-Schritt wäre die Hauptarbeit gewesen, ist aber per B-002 deferred.

Progress Log

  • 2026-05-17 01:00 — Cherry-pick f7165dc0 lefthook fix (Precursor).
  • 2026-05-17 01:02 — 9081eb50 Step 1: storageService.ts (S3/local pure, kein Supabase) extrahiert aus dem bestehenden runtime-provider-Path in supabaseService.ts. 4 Exports: storeFile, putBufferAsFile, deleteFile, hasStorageCredentials. Keine Caller-Switches, alles bleibt grün.
  • 2026-05-17 01:04 — 21900ac2 Step 2: 6 Prod-Routen + 3 Test-Files migriert (general/profile/account/portals/widgets settings) von storeSupabaseFile → storeFile. Pure import + symbol rename. Plus zwei Test-Mock-Pfade.
  • 2026-05-17 01:06 — 1107e59c Step 3: MediaService.ts refactored — uses putBufferAsFile / deleteFile / hasStorageCredentials. Branch-Logic auf storageProvider === "supabase" weg, neue Writes setzen "s3".
  • 2026-05-17 01:08 — dc4c3f77 Step 4: supabaseService.ts + zugehöriger Test gelöscht (orphaned). 435 LOC weg, Tests: 1887 (war 1890 vor diesem Commit; −3 ist supabaseService.test cases).
  • 2026-05-17 01:10 — 51e34839 Step 5: Config-Schema-Cleanup — WebConfig.supabase, ApiConfig.supabase, ApiConfigSupabase type, "supabase" aus WebConfigStorage.provider/fallbackProvider-Union, alle supabase: {} Test-Fixtures (6 Files in apps/api + 2 in packages/config), normalizeStorageProvider-Funktionen.
  • 2026-05-17 01:12 — 613d51fe Step 6: @supabase/supabase-js aus root + apps/web/package.json, catalog-Einträge für SUPABASE_API_URL/SUPABASE_KEY, alle 4 .env*example-Files, docs/env-access-inventory.md. Lockfile re-resolved, kein Supabase mehr in Tree.
  • 2026-05-17 04:47 — staging-verify — running web container mrf8lj70kmy9hqprx9dd6w7q-024502656750 (image tag 37f23fa6...): env | grep -i supabase → empty; ls /app/node_modules/@supabase → not found. Postgres-Audit SELECT provider, COUNT(*) FROM "FileObject" GROUP BY provider → 0 rows total (FileObject leer, also keine historischen storageProvider='supabase'-Datensätze die migriert werden müssten). Migrations-Script entfällt damit endgültig. Acceptance Criteria erfüllt.