Upgrade Strategy

Applicatie

Build immutable image, run migrations/preflight, deploy, verify health and smoke tests. Database migrations are backward compatible for at least one application rollout whenever practical.

Embedding/index

Never in place. Register new profile, build shadow collection, evaluate, activate alias, retain old build for rollback.

PostgreSQL/Qdrant

Pin exact supported versions, read release notes, test backup restore and application suite in staging/temporary environment, then maintenance deployment. No automatic major upgrades.

Rollback

Application image rollback plus compatible migration strategy; index alias rollback for retrieval; config/profile activation history. Restore is last resort, not ordinary rollback.

Upgrade naar 1.2.1

Deze release bundelt drie rondes: SOURCE-CONVERGENCE (migratie 0017), OPERATIONS-ISOLATION (0018) en RELEASE-CLEANUP (0019). Eén alembic upgrade head voert ze in volgorde uit; de stappen hieronder beschrijven wat er per ronde verandert en wat je vóór de uitrol moet zetten.

SOURCE-CONVERGENCE (`0017`)

Eerst configureren, dan uitrollen. RAGCORE_SOURCE_ROOTS is een expliciete allowlist van server-side paden die een Folder- of Git-bron mag lezen, en is leeg by default -- fail closed. Zolang die leeg is kan geen enkele filesystem-bron worden aangemaakt of gesynchroniseerd, en falen bestaande folder/Git-syncs terminaal (source path is outside every allowed source root). Zet de waarde dus vóór de uitrol, met de paden zoals de worker ze ziet, en zorg dat elk pad ook read-only in de worker gemount is (RAGCORE_SOURCE_MOUNT in compose.yaml). Mount zonder allowlist leest niets; allowlist zonder mount resolvet niet. Er is bewust geen impliciete default, / al helemaal niet.
Migratie 0017_source_convergence (alembic upgrade head) voegt de convergentie-administratie toe aan content.source_items (applied_fingerprint, applied_at, pending_job_id, attempts, last_failure_code, last_failure_retryable), pending aan source_sync_runs, verbreedt sync_state/outcome naar 32 tekens, en vervangt de foreign key van content.documents door een samengestelde (source_id, workspace_id, space_id) met een bijbehorende unique key op content.sources.
Twee datawijzigingen in die migratie, geen schemawijzigingen: (a) bestaande onthouden items worden als applied gebackfilld -- ze zijn geïngest onder het oude model, waarin een afgeronde discovery het enige completion-signaal was; (b) een bron die door 0016 over meerdere knowledge spaces heen mocht liggen wordt gesplitst naar per-space zusterbronnen (deterministisch afgeleid id) en de documenten daarvan worden omgehangen.
Qdrant-punten van zulke gesplitste documenten dragen nog het oude source_id. Draai daarna een authoritative reconcile/rebuild van de actieve collectie, net als bij de 1.2.0-upgrade. Controleer vooraf of er iets te splitsen valt:
```
SELECT DISTINCT d.source_id, d.workspace_id, d.space_id
FROM content.documents AS d
JOIN content.sources AS s ON s.id = d.source_id
WHERE d.workspace_id <> s.workspace_id OR d.space_id <> s.space_id;
```
Geen rijen = geen split en geen rebuild nodig voor deze stap.
Downgrade is niet symmetrisch. De split wordt niet teruggedraaid (de zusterbronnen zijn echte bronnen geworden), en awaiting_ingest / completed_with_failures bestaan niet in het oude schema: die vallen bij een downgrade terug op applying respectievelijk failed, zodat een gedowngrade deployment "onaf of mislukt" leest in plaats van "geslaagd".
Verwachte gedragsverandering na de uitrol: een sync meldt awaiting_ingest tot zijn child-ingest_upload-jobs teruggerapporteerd hebben, en last_successful_sync_at schuift alleen op bij een volledig geconvergeerde run. Een bron die eerder direct "Last sync ok" toonde, toont nu eerst "Indexing" -- dat is de correctie, geen regressie.

OPERATIONS-ISOLATION (`0018`)

Migratie 0018_job_workspace_ownership maakt eigenaarschap van een job een echte kolom (jobs.jobs.workspace_id, geïndexeerd) en voegt content.source_items.last_failure_job_id toe. De backfill is bewust fail-closed: alleen een payload->>'workspace_id' die zowel een geldige UUID is als een bestaande workspace aanwijst wordt overgenomen. Al het andere blijft NULL = legacy, en dat betekent onzichtbaar en onwijzigbaar voor elke workspace-gebonden principal; alleen een Platform Admin ziet zulke jobs nog. Verwachte gedragsverandering: een operator die vóór deze upgrade jobs van andere tenants zag, ziet nu alleen de eigen workspace. Controleer hoeveel rijen legacy blijven:
```
SELECT count(*) FROM jobs.jobs WHERE workspace_id IS NULL;
```
Die jobs zijn niet stuk; ze zijn alleen niet toewijsbaar. Laat ze aflopen of ruim ze op als Platform Admin.
FILESYSTEM_SOURCE_MANAGE is nieuw en ligt uitsluitend bij PLATFORM_ADMIN. Een Folder- of Git-bron aanmaken of wijzigen vereist die permissie bovenop SOURCE_MANAGE. Workspace Admins en Space Managers die vóór deze upgrade filesystem-bronnen beheerden, kunnen dat niet meer; plan wie dat overneemt. De permissie en de RAGCORE_SOURCE_ROOTS-sandbox zijn onafhankelijke poorten: een pad buiten de allowlist wordt ook voor een Platform Admin geweigerd.

RELEASE-CLEANUP (`0019`)

Migratie 0019_job_listing_index voegt alleen een index toe (ix_jobs_workspace_status_recent op (workspace_id, status, updated_at)). Geen datawijziging, geen gedragsverandering buiten performance: het jobsoverzicht filtert vanaf deze release in SQL over de hele workspace in plaats van over een opgehaalde pagina, en dit is de index waarop die query draait. Op een grote jobs.jobs kost het aanmaken kort een write-lock; gebruik zo nodig CREATE INDEX CONCURRENTLY buiten Alembic om en markeer de migratie daarna als uitgevoerd.

Upgrade naar 1.2.0

Migratie 0016_sources_lifecycle (alembic upgrade head) maakt content.sources, source_sync_runs, source_items, voegt documents.source_id (NOT NULL, FK) toe en backfillt die uit source_key met dezelfde regel die de runtime gebruikt (UUID-vormige key = caller-bron; anders de ingebouwde Uploads-bron van de space). Voor iedere backfilled bron ontstaat een registry-record (kind upload).
Qdrant-punten die vóór 1.2.0 zijn geïndexeerd dragen nog het oude synthetische source_id (uuid5 per document). Draai na de migratie een authoritative reconcile/rebuild van de actieve collectie (IndexBuildService.reconcile/build, beide gebruiken nu de canonical IndexPoint-mapping) zodat source_ids-filters en provenance ook voor bestaande content kloppen; tot die tijd matchen filters op die oude punten niet.
Worker en app opnieuw uitrollen (nieuwe job-operation sync_source; nieuwe Control Plane-routes /admin/sources, /admin/documents, /admin/system).
SDK-consumers: de citation-schema's kregen additieve optionele velden (source_id, source_name, source_kind, locator, revision, display).

7.1 KiB Raw Blame History