RAGcore-Public/docs/03_DATA/DATABASE_SCHEMA.md

Database Schema

Schema's

• identity: users, service_accounts, credentials, sessions.
• control: workspaces, applications, spaces, grants, policies, profiles.
• content: sources, documents, versions, blobs, artifacts, chunks, citations.
• jobs: jobs, attempts, events, schedules.
• query: retrieval_runs, candidates, answers, feedback.
• evaluation: suites, cases, runs, results.
• audit: append-only audit_events.

Belangrijke constraints

• Unieke actieve documentversion per document via partial unique index.
• Unieke (workspace_id, slug) voor applications en spaces.
• Tokenhash uniek; plaintext token nooit opgeslagen.
• Chunk uniqueness op (document_version_id, structure_path, content_hash, chunk_profile_version).
• Foreign keys gebruiken restrict/cascade bewust; contentaudit wordt niet stil verwijderd.
• Alle timestamps timestamptz in UTC.
• jobs.jobs.workspace_id is de ownership-kolom waarop iedere operator-query filtert, met indexen (workspace_id, updated_at) en --- sinds migratie 0019, voor het gefilterde operatoroverzicht --- (workspace_id, status, updated_at). operation staat er bewust niet in: die kolom heeft twee waarden in deze runtime en versmalt niets wat de eerste twee kolommen niet al versmallen. Nullable uitsluitend voor legacy rijen van vóór migratie 0018; nieuwe jobs worden door de repository geweigerd zonder eigenaar. NULL betekent "geen eigenaar vast te stellen" en faalt gesloten voor workspace-scoped principals --- nooit "van iedereen".
• content.source_items.last_failure_job_id bewaart de child ingest job die als laatste faalde. Een terminaal gefaald item met ongewijzigde fingerprint wordt bewust niet opnieuw ge-enqueued; herstel loopt via retry van díe job.

Transaction boundaries

• Nieuwe versie en jobregistratie in één transaction.
• Publication update vergrendelt document en valideert indexbuildstatus.
• Jobclaim gebruikt FOR UPDATE SKIP LOCKED met lease expiry.
• Qdrant is geen distributed transaction participant; outbox/reconciliation herstelt divergentie.

Migrations

Alle wijzigingen via Alembic, met upgrade, waar realistisch downgrade, data-backfillplan en migratietest tegen lege én representatieve database.