Replikerings-klient

Referenceklient til replikerings-API'et

Introduktion

DAWA tilbyder en implementation af en referenceklient til replikerings-API'et. Klienten understøtter p.t. kun PostgreSQL som database, og kan ikke indlæse data i andre databaser.

Forudsætninger

For at indlæse data skal følgende være på plads:

  • Der skal installeres en Postgres-database. Hvis der skal indlæses geometriske felter, så skal PostGIS udvidelsen være installeret.
  • NodeJS skal installeres, da replikerings-klienten benytter NodeJS som runtime.
  • Replikeringsklienten skal installeres.
  • Der skal laves en konfigurations-fil, som beskriver hvilke data der skal replikeres.
  • Der skal oprettes de nødvendige tabeller i databasen.

Replikerings-processen

Se replikerings-guiden for en overordnet beskrivelse af hvordan replikerings-API'et fungerer. Herunder beskrives nogle forhold, som er specifikke for klient-implementationen.

Replikerings-klienten indlæser nye data i transaktioner. Der startes en transaktion, hvori alle lokale tabeller opdateres til en bestemt transaktions-ID. Replikerings-klienten tildeler også en lokal transaktions-ID til hver lokal transaktion. Der er således to transaktions-sekvenser i spil: En remote sekvens (dem som udstilles af DAWA) og en lokal sekvens (dem som dannes af replikerings-klienten).

Installation af postgres

Installation af Postgres og oprettelse af databasebruger med adgang til databasen er udenfor scope af denne guide. Vi henviser til postgresql.org. Mac-brugere kommer nemmest igang med Postgres.app.

Installation af NodeJS og replikerings-klient

NodeJS kan installeres fra nodejs.org. Herefter kan replikerings-klienten installeres ved hjælp af NPM:

npm install -g @dawadk/replication-client

Det kan verificeres, at replikerings-klienten er installeret korrekt ved at prøve at køre den fra en terminal:

dawa-replication-client --help

Konfiguration af klient

Klienten skal have en konfiguration for at replikere data. Konfigurationen indeholder oplysninger om hvilke entiteter og attributter der skal replikeres. Derudover indeholder konfigurationen information om hvilke tabeller data skal gemmes i.

Den nemmeste metode er at lade klienten danne en konfiguration, der så efterfølgende tilpasses efter behov. Følgende kommando genererer en konfigurationsfil og gemmer den i my-config.json:

dawa-replication-client gen-config --file my-config.json

Konfigurationen dannes ud fra den datamodel, som udstilles på replikerings-API'et. Konfigurationen er i JSON-format, og består af et JSON-objekt med følgende felter:

  • replication_url: API URL til replikerings-API'et, dvs. https://api.dataforsyningen.dk/replikering.
  • replication_schema: Database-schema, som replikerings-klienten kan gemme metadata i. Default dawa_replication
  • entities: En liste af de entiteter, som skal replikeres, samt hvilke attributter.
  • bindings: Information om hvordan entiteterne skal gemmes i databasen. P.t. understøttes kun tabelnavne.

Et minimalt eksempel på en konfiguration, som replikerer navngivne vejes status, vejnavn og vejadresseringsnavn fra DAR kunne se således ud:

{
  "replication_url": "https://api.dataforsyningen.dk/replikering",
  "replication_schema": "dawa_replication",
  "entities": [
    {
      "name": "dar_navngivenvej_aktuel",
      "attributes": [
        "id",
        "status",
        "vejadresseringsnavn",
        "vejnavn"
      ]
    }
  ],
  "bindings": {
    "dar_navngivenvej_aktuel": {
      "table": "dar_navngivenvej_aktuel"
    }
  }
}

Den nemmeste metode til at lave en konfiguration er at tage udgangspunkt i den automatisk generede konfiguration, og så slette de entiteter og attributter, som der ikke er brug for.

Indlæsning af database-schema

Klienten kan generere et database-schema ud fra en konfigurations-fil. Følgende kommando genererer et database-schema ud fra konfiguraitonsfilen my-config.json og gemmer schemaet i filen schema.dll:

dawa-replication-client gen-schema --replication-config my-config.json --file schema.sql

Schemaet består af to tabeller som replikerings-klienten gemmer metadata i, samt tabeller til de entiter, som replikeres.

Tabellen transactions indeholder en række for hver lokal transaktion. Hver række indeholder et txid og et tidsstempel.

Tabellen source_transactions registrerer hvilke remote txid der er indlæst i den lokale database.

Tabellerne med entiteter indeholder en kolonne for hver attribut. Som udgangspukt er kolonnens navn det samme som attributtens navn.

Replikering af data

Når konfigurationsfil og database-schema er på plads kan data indlæses med replicate kommandoen. En af parametrene er en URI der beskriver hvordan applikationen forbinder til databasen. URI'en har følgende form:

postgresql://<user>:<password>@<hostname>:<port>/<database>

Database-URI og konfigurationsfil skal angives ved initialisering af databasen:

dawa-replication-client replicate --database=<database-URI> --replication-config <config-file>

Programmet vil gå i gang med at downloade de entiteter der er angivet i konfigurations-filen og gemme den i den lokale database.

Er der allerede data i tabellerne vil replicate kommandoen i stedet foretage en inkrementiel opdatering baseret på hændelser. I denne situation hentes kun de ændringer, som er sket siden replicate kommandoen sidst blev udført:

dawa-replication-client replicate --database=<database-URI> --replication-config <config-file>

Replikerings-klienten afgør for hver enkelt entitet om der skal indlæses et fuldt udtræk eller om der skal foretages en inkrementiel opdatering. Hvis der tilføjes en ny entitet til konfigurationen og køres replicate, vil klienten indlæse et udtræk af den nye entitet og foretage en inkrementiel opdatering af de andre entiteter.

I særlige tilfælde kan det være ønskværdigt at lave et fuldt udtræk, selvom der allerede er hentet data tidligere. Det kan f.eks. være hvis der er tilføjet nye attributter eller hvis der er mistanke om datainkonsistenser. Hvis --force-download parameteren angives vil klienten benytte et nyt, fuldt udtræk til at opdatere den lokale kopi:

dawa-replication-client replicate --database=<database-URI> --replication-config <config-file> --force-download

Ændringstabeller

Replikeringsklienten understøtter mulighed for, at hændelser kan gemmes i en lokal ændringstabel. Det sker automatisk, hvis disse tabeller er oprettet. Navnet på hændelsestabellen skal være navnet på primærtabellen efterfulgt af "_changes", f.eks. adgangsadresse_changes.

Ændringstabellen indeholder de samme kolonner som primærtabellen. Herudover indeholder ændringstabellen kolonnen txid, som er den lokale transaktions-id, og kolonnen operation, som har værdierne 'insert', 'update' eller 'delete'.

Formålet med ændringstabellerne kan eksempelvis være at vedligeholde afledte tabeller, hvori der indgår data fra DAWA.

Replikerings-klienten kan selv generere ændringstabellerne. Dette gøres ved at køre gen-schema kommandoen med parameteren --with-change-tables.