Gå til hovedinnhold

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)​

Hva KREG publiserer (publikasjon opptak_vitnemaal)
TabellKolonner
personperson_id, nasjonal_id
kompetanseoppnaelsekompetanseoppnaelse_id, person_id, status, sist_endret
dokument_kompetanseoppnaelsedokument_id, kompetanseoppnaelse_id
dokumentdokument_id, dato_utstedt
vg_dokumentdokument_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:

Viewet kreg_dokumenter_endringsdata
KolonneInnhold
fødselsnrFødselsnummer
dokument_idUnik
sist_endretTimestamp med tidssone. Nyeste endring blant alle tilknyttede kompetanseoppnåelser
innholder_annulleringBoolean. Sier om minst én kompetanseoppnåelse i dokumentet er annullert
vgdoktypekodeVM 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 INSERT vil 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 UPDATE vil 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.

Filtrering i opptak
TriggerNårHva
person_bare_sokere_trgBEFORE INSERT på personSlipper bare inn søkere. Fødselsnummeret til en som ikke har søkt, skrives aldri.
*_bare_sokere_trgAFTER INSERT, utsatt til commit, på de fire andreSletter rader som ikke kan knyttes til en søker gjennom person. Rekkefølgen radene kommer i, spiller ingen rolle.
kjent_rad_trgBEFORE 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 henterNårHvem hentes
SoknadshendelseJobbNår en sak opprettes, i samme transaksjon som sakenSøkeren. Feiler KREG, rulles saken tilbake og hendelsen prøves igjen.
KregReplikaSynkJobbHver natt kl. 00, opptil 4 forsøkSø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.
KregImportJobbDaglig (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​

0. Komponentene
KomponentHvaLokalt
KREG-db (publisher)Postgres med kompetanse.*. Migreringen V1_081__opptak_replikering.sql lager publikasjonen opptak_vitnemaal og rollen rds_replicationContaineren kreg-postgres (mise run db i kreg/), localhost:5432, db nvb, admin/test123
ReplikeringsbrukerInnlogging hos KREG med replication og bypassrls, medlem av rds_replicationkreg_opptak_replication/repl
Opptak-db (abonnent)Postgres med replika-tabellene kompetanse.person, dokument, vg_dokument, kompetanseoppnaelse og dokument_kompetanseoppnaelse fra V544__kreg_replika_vitnemaal.sqlContaineren opptak-opptak-postgresql-1 (opptak/compose.yml), localhost:5433, db admissio
Abonnementetopptak_kreg_admissio, med copy_data = false. Apply-workeren i opptak-db leser endringer fra en slot med samme navn hos KREGOpprettes 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 selvFølger med migreringen
Opptak-appenKregReplikaService legger søkerens vitnemål inn i replika-tabellene når de hentes fra KREGValgfri 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:

  • nc får Connection refused, og docker port opptak-opptak-postgresql-1 er 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-state sier 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_id er et fødselsnummer eller D-nummer i tilgangskontroll.personidentifikasjon med en søknad (soknad_v2.soker → soknad_v2.soknad), direkte eller via kompetanseoppnaelse/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 kompetanseoppnaelse har ingen endringsdato. dato_tildelt er alltid lik dokument.dato_utstedt, og tid_opprettet er når KREG laget raden fra nvb2. Trengs tidspunktet, må opptak selv stemple når endringen kommer: en nullbar, upublisert kolonne satt av en ENABLE ALWAYS-trigger.
  • Feilsøking: pg_stat_subscription og pg_stat_subscription_stats i opptak-db, og loggen med docker logs opptak-opptak-postgresql-1. Hos KREG: pg_replication_slots.

3. Riv ned​

warning

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å​