Dataplatform Twente

Dataplatform Twente haalt gemeentelijke databronnen op, bewaart de ruwe bestanden en modelleert ze met DLT en SQLMesh. Generieke verwerking staat in Python en SQL; bron- en deploymentinstellingen staan in TOML en YAML.

Pipeline

bron -> lake -> staging -> PSA -> GGM -> datamart

Stap	Implementatie	Resultaat	Status
lake	DLT filesystem	Ruwe bronbestanden in lokale of S3-opslag	Werkend
staging	DLT met bronreader	Technische brontabellen in DuckDB, Postgres of MSSQL	Werkend
psa	SQLMesh	Opgeschoonde, persistente brontabellen	Werkend
ggm	SQLMesh	Bronoverstijgende GGM-modellen	Runner aanwezig, geen modellen meegeleverd
datamart	SQLMesh	Tabellen voor rapportage en analyse	Runner aanwezig, geen modellen meegeleverd

Een volledige run stopt per dataset zodra een stap mislukt. Omdat deze repo geen GGM- en datamartmodellen bevat, zijn lake, staging en psa de direct uitvoerbare lagen. De commando's ggm, datamart en all vereisen modellen in de bijbehorende SQLMesh-map.

Snel starten

Vereisten: Python 3.12 of hoger, uv en optioneel Docker voor de lokale Postgres- en S3-services.

Zie docs/INSTALLATIE.md voor installatie van de vereisten, repositorytoegang, lokale configuratie en de Docker-route.

uv sync
uv run main.py init --dataset cbs_gebiedsindelingen
uv run main.py lake --dataset cbs_gebiedsindelingen
uv run main.py staging --dataset cbs_gebiedsindelingen
uv run main.py psa --dataset cbs_gebiedsindelingen

init kopieert datasetconfiguratie en PSA-modellen uit templates/ zonder bestaande bestanden te overschrijven. Gebruik --overwrite alleen wanneer de actieve bestanden door de templates vervangen mogen worden.

Configuratie

config.toml bevat alleen de gedeelde bestemmingen:

[lake]
destination = "local" # local of s3

[staging]
destination = "duckdb" # duckdb, postgres of mssql

De bestemming kan per commando worden overschreven met --destination.

Elke dataset heeft een centrale configuratie en een bestand per entity:

config/<dataset>/
|-- _<dataset>.yml
|-- <entity>.yml
`-- ...

De datasetconfiguratie bevat run_this, source, dataset, load_lake en load_staging. source beschrijft de aanbieder; dataset is de expliciete, unieke datasetidentiteit. Een standaardrun verwerkt datasets waarvan run_this niet false is. Entityconfiguraties worden recursief over de datasetconfiguratie gelegd; null erft de datasetwaarde en run_this: false schakelt de entity uit. --dataset beperkt een commando expliciet tot de genoemde dataset.

Zie config/README.md voor het mergecontract en de ondersteunde readerinstellingen.

Naamgeving en opslag

Begrip	Conventie	Voorbeeld
source	Aanbieder of bronsysteem	pdok
dataset	Expliciete datasetidentiteit	pdok_bag
Entity	Bestandsnaam zonder .yml; onderdeel van de stagingtabelnaam	adres
PSA-bestand	sqlmesh/models/psa/<dataset>/<entity>.sql	sqlmesh/models/psa/pdok_bag/adres.sql
PSA-model	psa.<dataset>__<entity>	psa.pdok_bag__adres
Stagingtabel	staging.<dataset>__<entity>	staging.pdok_bag__adres

De logische PSA-modelnaam blijft altijd psa.<dataset>__<entity>. Voor Postgres gebruikt SQLMesh HASH_MD5 voor de fysieke tabelnaam, zodat ook lange dataset- en entitynamen binnen de identifierlimiet passen. De bestands- en entitynaam veranderen daarbij niet.

Bij DuckDB gebruiken alle pipeline-lagen één gedeeld bestand:

data/lake/<dataset>/raw/*.jsonl.gz
data/dataplatform.duckdb         # schema's: staging, psa

Bij Postgres delen staging en SQLMesh een database. Staging schrijft naar het schema staging, met tabellen <dataset>__<entity>, en PSA naar schema psa.

Bij MSSQL delen staging en SQLMesh eveneens een database. Staging schrijft naar schema <dataset> en PSA naar psa. Configureer de verbinding in .dlt/secrets.toml onder [destination.mssql.credentials]. Gebruik driver voor de ODBC-drivernaam en [destination.mssql.credentials.query] voor opties zoals Encrypt en TrustServerCertificate.

CLI

uv run main.py lake [--dataset DATASET] [--destination local|s3] [--force]
uv run main.py staging [--dataset DATASET] [--destination duckdb|postgres|mssql] [--force]
uv run main.py psa [--dataset DATASET] [--force]
uv run main.py ggm [--dataset DATASET] [--force]
uv run main.py datamart [--dataset DATASET] [--force]
uv run main.py all [--dataset DATASET] [--force]

PSA-templates worden opgebouwd door staging te introspecteren:

uv run main.py psa --scaffold --dataset SOURCE_ID
uv run main.py psa --scaffold --check --dataset SOURCE_ID
uv run main.py psa --scaffold --overwrite --dataset SOURCE_ID

--scaffold schrijft naar templates/sqlmesh/models/psa/. Voer daarna init uit om ontbrekende modellen naar sqlmesh/models/psa/ te kopieren.

Repository

Pad	Verantwoordelijkheid
main.py	CLI en opeenvolgende uitvoering van de vijf stappen
config.toml	Gedeelde lake- en databasebestemmingen
config/	Dataset- en entityconfiguratie, inclusief run_this
data/	Lokale lake-, staging- en PSA-data
tools/	Configloaders, storage, readers, runners en scaffolding
sqlmesh/	SQLMesh-configuratie, macro's en actieve modellen
templates/	Herbruikbare bronconfiguratie en PSA-modellen voor init
tests/	Unit- en integratietests voor de pipeline
deploy/local/	Lokale Docker-services

Meer detail staat in:

• docs/INSTALLATIE.md: installatie en eerste werkende lake-, staging- en PSA-run;
• docs/ARCHITECTURE.md: datastroom, laaggrenzen en uitvoeringscontracten;
• docs/CONTRIBUTING.md: afspraken voor wijzigingen;
• tools/README.md: verantwoordelijkheden van runners en loaders;
• sqlmesh/README.md: SQLMesh-opbouw en modelconventies;
• templates/README.md: lifecycle van templates.

Deployment

Elke organisatie draait een eigen deployment. Secrets, credentials en productiedata worden niet in de repository vastgelegd. Voor S3, Postgres en MSSQL leest DLT de credentials uit .dlt/secrets.toml; het invulbestand staat in templates/.dlt/secrets.toml.

Container

De productie-image wordt gebouwd met de root-Dockerfile. De dependencies worden tijdens de build exact uit uv.lock geïnstalleerd. De image bevat geen lokale configuratie, secrets of data; mount die bij het uitvoeren van de container:

docker build -t dataplatform-twente:local .
docker run --rm \
  -v "$PWD/config.toml:/app/config.toml:ro" \
  -v "$PWD/config:/app/config:ro" \
  -v "$PWD/.dlt:/app/.dlt" \
  -v "$PWD/data:/app/data" \
  dataplatform-twente:local all

De Forgejo-workflow container-build.yml is handmatig te starten. Met publish=false wordt alleen de registry-login getest; met publish=true wordt de image gebouwd en de commit-tag naar de Forgejo Container Registry gepusht. Bij een build vanaf main wordt ook de tag latest bijgewerkt. Configureer hiervoor een repository-secret PACKAGE_TOKEN met de scope write:package. Configureer eventueel ook FORGEJO_PACKAGE_USER wanneer de token bij een andere gebruiker hoort dan de workflow-trigger.

De runner moet daarvoor een Docker CLI en toegang tot een geïsoleerde Docker-daemon hebben; configureer dit op runner-niveau, bijvoorbeeld met Docker-in-Docker. Alleen Docker in de applicatie-image installeren is niet voldoende.

Licentie

GNU AGPLv3