Logisk replikering av vitnemålsmetadata fra KREG til opptak
Løsningen dekker to sentrale behov for opptak:
- Opptak skal bare ha data om sine søkere, og bør derfor ikke sitte på en full kopi av alle resultater i KREG.
- Opptak må kunne vite hva som er endret for å kunne ha oppdatert data.
Data som gjøres tilgjengelig
Hva KREG publiserer (publikasjon opptak_vitnemaal)
| Tabell | Kolonner |
|---|---|
person | person_id, nasjonal_id |
kompetanseoppnaelse | kompetanseoppnaelse_id, person_id, status, sist_endret |
dokument_kompetanseoppnaelse | dokument_id, kompetanseoppnaelse_id |
dokument | dokument_id, dato_utstedt |
vg_dokument | dokument_id, vgdoktypekode |
Annullering er en endring av kompetanseoppnaelse.status. sist_endret settes av KREG ved insert og ved
enhver reell endring. KREG sletter aldri kompetanseoppnåelser.
Viewet kreg_dokumenter_endringsdata
Opptak får viewet kreg_dokumenter_endringsdata for å enklere vise disse dataene. Det har én rad per dokument:
| Kolonne | Innhold |
|---|---|
fødselsnr | Fødselsnummer |
dokument_id | Unik |
sist_endret | Timestamp med tidssone. Nyeste endring blant alle tilknyttede kompetanseoppnåelser |
innholder_annullering | Boolean. Sier om minst én kompetanseoppnåelse i dokumentet er annullert |
vgdoktypekode | VM for vitnemål, KB for kompetansebevis |
Dataflyt
Data kommer inn i replikaen på tre ulike måter: Fra endringer i Kreg, på grunn av hendelser i opptak, eller til sist via en nattlig synk-jobb som tar eventuelle feil grunnet race conditions o.l.
I alle tilfeller er det viktig å få frem at dette er metadata. Hvilke vitnemålsdata finnes, og når er de sist endret. Dette kan senere brukes til å velge hvilke data opptak må laste inn eller oppdatere.
Abonnementet kopierer ikke KREGs tabeller (copy_data = false). Replikaen starter tom og fylles bare av
replikering for søkere og av opptaks egen henting.
Ny vitnemålsdata (Endringer i KREG)
Ny data i KREG fører til at replikert data skrives videre til Opptak. Dette skjer hovedsakelig enten ved at nye vitnemål lastes opp, eller at vitnemål annuleres.
- Nytt vitnemål: en
INSERTvil forsøke å skrive dataen til Opptak. En trigger hos opptak vil se om dataen er relevant før den enten lagres eller forkastes. - Annullert (endring): en
UPDATEvil endre dataen dersom den finnes, men vil hoppe over rader den eventuelt ikke finner. Så dersom vitnemålsdataen ble forkastes ved insert, vil ingenting skje ved update (på ikke-eksisterende data)
En våken leser vil nå tenke på hva som skjer om en søknad kommer etter vitnemålsdataen. Dette er beskrevet under Søknad mottas.
Søker: Defineres i triggeren som en person med fødselsnummer eller D-nummer i tilgangskontroll.personidentifikasjon og en
søknad (soknad_v2.soker → soknad_v2.soknad).
Søknad mottas
Når saken opprettes, hentes metadataen som trengs for å fylle tabellene som ellers ville vært fylt av Kreg. Altså laster vi inn dataen triggeren nevnt over tidligere forkastet.
En svært våken leser vil likevel undres: Hva som et vitnemål annuleres akkuratt når opptak laster inn metadata på nytt? Dette er igjen beskrevet i Ny data hentes.
Ny data hentes
Hver natt henter synken vitnemålene på nytt mens abonnementet står i pause, og retter opp det som gikk tapt. Dette er kun en støttemekanisme for å stryke ut eventuelle feil fra race conditions o.l.
Filtrering og dataminimering
Juss, bakgrunn og begrunnelse
KREG har DPIA og derfor grunnlag og hjemmel til å lagre og forvalte vitnemålsdata. Opptak har ikke det, men er derimot en databehandler som har lov til å behandle vitnemålsdata i sammenheng med opptak.
Derfor har også opptak ikke lov til å forvalte/behandle vitnemålsdata som ikke er relevant for opptaket.
Filtrering i opptak
Apply-workeren skriver med session_replication_role = replica, så filtertriggerne er ENABLE ALWAYS.
| Trigger | Når | Hva |
|---|---|---|
person_bare_sokere_trg | BEFORE INSERT på person | Slipper bare inn søkere. Fødselsnummeret til en som ikke har søkt, skrives aldri. |
*_bare_sokere_trg | AFTER INSERT, utsatt til commit, på de fire andre | Sletter rader som ikke kan knyttes til en søker gjennom person. Rekkefølgen radene kommer i, spiller ingen rolle. |
kjent_rad_trg | BEFORE INSERT, bare for apply-workeren (ENABLE REPLICA) | Hopper over rader opptak allerede har lagt inn selv, så en nøkkelkonflikt ikke stanser replikeringen. |
UPDATE og DELETE filtreres ikke. De treffer bare rader opptak har, og endringer i andre rader hopper apply-workeren over uten feil.
Henting fra KREG-grafen
KregKlient henter vitnemålene (Utdanningsprogram) per fødselsnummer. Barna (programområder og fag)
følger med som innhold, men uten ID. KREGs nøkler leses fra node-ID-ene til Utdanningsprogram og eier.
KregReplikaService legger søkerens rader i replikaen: personen, kompetanseoppnåelsen på toppnivå med
status, dokumentet, vg_dokument og lenken mellom dem. Det fulle vitnemålet lagres i vgs_dokument*.
| Hvem henter | Når | Hvem hentes |
|---|---|---|
SoknadshendelseJobb | Når en sak opprettes, i samme transaksjon som saken | Søkeren. Feiler KREG, rulles saken tilbake og hendelsen prøves igjen. |
KregReplikaSynkJobb | Hver natt kl. 00, opptil 4 forsøk | Søkere som har fått sak de siste 52 timene. Alle søkere med sak netter til og med opptak.kreg-rebuild-on-or-before. |
KregImportJobb | Daglig (bare i test) | Alle aktive søkere. Skal fjernes. |
Kjente begrensninger
- Dør poden mens abonnementet er pauset, står replikeringen stille til neste vellykkede synk, og KREG holder igjen WAL. Bør sikres ved oppstart og varsles.
- Barn av et vitnemål kommer inn via replikeringen, men ikke via hentingen. Det påvirker ikke annullering, som står på toppnivå.
- Er KREG nede, opprettes ingen saker (30 s timeout per søknad) til KREG svarer igjen.
Lokal utvikling
Guiden setter opp opptaks Postgres i Docker med et abonnement på KREGs publikasjon opptak_vitnemaal, mot en
lokal KREG-database. Bakgrunn og regler står i Dataflyt over.
Stiene i guiden er relative til roten av fs-plattform.
0. Komponentene
| Komponent | Hva | Lokalt |
|---|---|---|
| KREG-db (publisher) | Postgres med kompetanse.*. Migreringen V1_081__opptak_replikering.sql lager publikasjonen opptak_vitnemaal og rollen rds_replication | Containeren kreg-postgres (mise run db i kreg/), localhost:5432, db nvb, admin/test123 |
| Replikeringsbruker | Innlogging hos KREG med replication og bypassrls, medlem av rds_replication | kreg_opptak_replication/repl |
| Opptak-db (abonnent) | Postgres med replika-tabellene kompetanse.person, dokument, vg_dokument, kompetanseoppnaelse og dokument_kompetanseoppnaelse fra V544__kreg_replika_vitnemaal.sql | Containeren opptak-opptak-postgresql-1 (opptak/compose.yml), localhost:5433, db admissio |
| Abonnementet | opptak_kreg_admissio, med copy_data = false. Apply-workeren i opptak-db leser endringer fra en slot med samme navn hos KREG | Opprettes for hånd. db subscribe-env treffer bare RDS-vertene |
| Triggerne i opptak | *_bare_sokere_trg (ENABLE ALWAYS) slipper bare inn rader for personer med søknad. kjent_rad_trg (ENABLE REPLICA) hopper over rader opptak har lagt inn selv | Følger med migreringen |
| Opptak-appen | KregReplikaService legger søkerens vitnemål inn i replika-tabellene når de hentes fra KREG | Valgfri for selve replikeringen |
Dataflyt: en endring i KREG (kompetanse.*) går via WAL og slot-en til apply-workeren i opptak, så gjennom
triggerne og inn i replika-tabellene. KREG endrer et vitnemål bare ved annullering, ved å sette
kompetanseoppnaelse.status = 'ANNULLERT'.
1. Sett opp
Forutsetning: kreg-postgres kjører og er migrert til minst V1_081 (mise run db og mise run db:migrate i kreg/).
1.1 Slå på logisk replikering i KREG
startDB.sh starter KREG med wal_level=replica, og da kan KREG ikke publisere.
docker exec kreg-postgres psql -U admin -d nvb -c "alter system set wal_level = logical"
docker restart kreg-postgres
docker exec kreg-postgres psql -U admin -d nvb -Atc "show wal_level" # logical
mise run db lager containeren på nytt, og da forsvinner innstillingen. Kjør 1.1 igjen etterpå.
1.2 Opprett replikeringsbrukeren i KREG
docker exec kreg-postgres psql -U admin -d nvb -c \
"create role kreg_opptak_replication login replication bypassrls password 'repl' in role rds_replication"
1.3 Start opptak-db på port 5433
KREG har allerede tatt 5432, så en overstyringsfil flytter porten.
cd opptak
OV=/tmp/opptak-kreg.compose.yml
cat > $OV <<'EOF'
services:
opptak-postgresql:
ports: !override [ "5433:5432" ]
EOF
eval "$(studieadm-cli gitlab auth --username --format shell)"; export GITLAB_USERNAME GITLAB_PASSWORD
docker compose -f compose.yml -f $OV up --wait
nc -zv localhost 5433
Feilretting:
ncfårConnection refused, ogdocker port opptak-opptak-postgresql-1er tom: containeren mangler nettverk. Lag den på nytt, så blir dataene liggende i volumet:docker compose -f compose.yml -f $OV up -d --wait --force-recreate --no-deps opptak-postgresql- Gamle eksempeldata: restore hoppes over så lenge volumet
opptak_opptak-restore-statesier at basen er gjenopprettet. Se 1.4.
1.4 Migrer opptak fra arbeidstreet
Compose-tjenesten opptak-migrations bruker registry-imaget, som kan mangle de nyeste migreringene.
mvn -pl opptak-migrations -am install -DskipTests -Dmigrate.skip=false \
-DbuildDatabase.jdbcUrl=jdbc:postgresql://localhost:5433/admissio
Feilretting: V453__fjern_sak_bruker_id feiler med «saksbehandling.sak har fortsatt saker med bruker_id satt»
når eksempeldataene er en gammel restore. Hent en ny restore. Det sletter den lokale opptak-basen:
docker compose -f compose.yml -f $OV down -v
docker compose -f compose.yml -f $OV up --wait
Kjør så 1.4 på nytt. Feiler V453 fortsatt, er også den siste eksempeldumpen eldre enn BAT-283. Nullstill da
kolonnen:
docker exec opptak-opptak-postgresql-1 psql -U postgres -d admissio -c "update saksbehandling.sak set bruker_id = null"
1.5 Koble KREG til opptaks nettverk
Slik når opptak-db KREG som kreg-postgres. Kjør igjen hvis kreg-postgres er laget på nytt.
docker network connect opptak_opptak kreg-postgres
1.6 Opprett abonnementet
Replika-tabellene må finnes først, fra 1.4. Med copy_data = false kopieres
ingen eksisterende KREG-rader, bare endringer fra nå av.
docker compose -f compose.yml -f $OV exec opptak-postgresql psql -U admissio-migrations -d admissio -c \
"create subscription opptak_kreg_admissio
connection 'host=kreg-postgres port=5432 dbname=nvb user=kreg_opptak_replication password=repl'
publication opptak_vitnemaal with (copy_data = false)"
1.7 Sjekk at replikeringen går
docker exec opptak-opptak-postgresql-1 psql -U admissio-migrations -d admissio -c \
"select subname, pid, received_lsn, last_msg_receipt_time from pg_stat_subscription" # pid er satt
docker exec kreg-postgres psql -U admin -d nvb -c \
"select slot_name, active, wal_status from pg_replication_slots" # active = t
IntelliJ (opptak-db): jdbc:postgresql://localhost:5433/admissio, bruker og passord admissio-migrations.
Bruk denne superbrukeren: replika-tabellene har RLS uten policyer, så admissio-graphql ser ingen rader.
2. Bruk replikeringen
- Bare søkere kommer inn. En rad slipper gjennom triggerne bare når personens
nasjonal_ider et fødselsnummer eller D-nummer itilgangskontroll.personidentifikasjonmed en søknad (soknad_v2.soker→soknad_v2.soknad), direkte eller viakompetanseoppnaelse/dokument_kompetanseoppnaelse. - Eksisterende vitnemål kommer ikke av seg selv (
copy_data = false). Opptak legger dem inn når de hentes fra KREG (KregReplikaService): når en sak opprettes, og i den daglige importen. Først da kan senere endringer for raden replikeres. Endringer i rader opptak ikke har, hoppes over uten feil.
Søkere i opptak (kryss mot kompetanse.person.nasjonal_id i KREG):
-- opptak-db
select distinct pi.identifikator
from tilgangskontroll.personidentifikasjon pi
join soknad_v2.soker s on s.person_id = pi.person_id
join soknad_v2.soknad so on so.soker_id = s.soker_id
where pi.personidentifikasjon_type_kode in ('FØDSELSNUMMER', 'D-NUMMER');
Annullering for test, i KREG. Triggeren vgdok_annullert_update_trg setter ANNULLERT på KO-ene:
-- kreg-db
update nvb2.vgdok set vgdokstatuskode = 'A' where vgdoknr = '<vgdoknr>';
-- opptak-db: synlig innen sekunder hvis opptak har raden
select ko.kompetanseoppnaelse_id, ko.status
from kompetanse.dokument_kompetanseoppnaelse dk
join kompetanse.kompetanseoppnaelse ko using (kompetanseoppnaelse_id)
where dk.dokument_id = '<vgdoknr>';
Verdt å vite:
- Ingen tidsstempel for annullering. KREG lagrer ikke når et vitnemål ble annullert, og
kompetanseoppnaelsehar ingen endringsdato.dato_tildelter alltid likdokument.dato_utstedt, ogtid_oppretteter når KREG laget raden fra nvb2. Trengs tidspunktet, må opptak selv stemple når endringen kommer: en nullbar, upublisert kolonne satt av enENABLE ALWAYS-trigger. - Feilsøking:
pg_stat_subscriptionogpg_stat_subscription_statsi opptak-db, og loggen meddocker logs opptak-opptak-postgresql-1. Hos KREG:pg_replication_slots.
3. Riv ned
Fjern abonnementet før opptak-db eller KREG fjernes. Ellers blir slot-en liggende hos KREG og holder tilbake WAL.
cd opptak
OV=/tmp/opptak-kreg.compose.yml
# 1. Abonnementet. Fjerner også slot-en hos KREG.
docker exec opptak-opptak-postgresql-1 psql -U admissio-migrations -d admissio -c "drop subscription opptak_kreg_admissio"
# 2. Opptak-db. Med -v slettes også dataene og restore-tilstanden.
docker compose -f compose.yml -f $OV down # eller: down -v
# 3. KREG
docker network disconnect opptak_opptak kreg-postgres
docker exec kreg-postgres psql -U admin -d nvb -c "drop role kreg_opptak_replication"
docker exec kreg-postgres psql -U admin -d nvb -c "alter system reset wal_level" # valgfritt
docker restart kreg-postgres
Når KREG allerede er borte, feiler drop subscription fordi den ikke når slot-en. Koble abonnementet fra
slot-en først:
-- opptak-db
alter subscription opptak_kreg_admissio disable;
alter subscription opptak_kreg_admissio set (slot_name = none);
drop subscription opptak_kreg_admissio;
Rydd en gjenglemt slot hos KREG:
docker exec kreg-postgres psql -U admin -d nvb -c "select pg_drop_replication_slot('opptak_kreg_admissio')"
Se også
- Kom i gang med logisk replikering i Postgres – praktisk innføring i mekanismen
- Replikering fra utdanningsregisteret til opptak – samme mønster for referansedata