Configuratiebestand voor OnsDB 5

Opbouw configuratiebestand

In het configuratiebestand wordt aangegeven welke gegevens gedownload worden en hoe de database opgeslagen moet worden. De opbouw van het bestand is als volgt:

• Instellingen zijn verdeeld in een aantal categorieën, een categorie wordt aangegeven als:

  [categorie]

• De instellingen zelf volgen het format:

  instelling = waarde

• Indien een regel begint met een #, wordt de betreffende regel genegeerd. Een voorbeeld is gebruik van de schema-version:

  #schema-version = 4195

  In dit geval wordt het versienummer genegeerd en treedt de default-waarde (de nieuwste schema-version) in werking.

Het configuratiebestand moet de extensie .cfg hebben en wordt meegegeven aan de client via --config {bestand_naam}.cfg. Indien er geen --config argument is opgegeven, wordt het configuratiebestand onsdb.cfg in de huidige directory gezocht.

Zet opmerkingen op een eigen regel. #, ; en een afsluitende backslash binnen een waarde worden letterlijk gebruikt. Omringende aanhalingstekens of backticks worden als INI-notatie verwijderd. Moeten die tekens zelf onderdeel van een waarde blijven, geef dan de exacte waarde via een omgevingsvariabele of --set mee.

Configuratie als CLI argument

Naast het configuratiebestand kun je instellingen met het --set argument meegeven. Het --set argument heeft voorrang op het configuratiebestand en omgevingsvariabelen. Het configuratiebestand moet nog wel bestaan, ook als je alle benodigde waarden met --set meegeeft.

Dit wordt gebruikt als --set categorie.instelling=waarde. --set kan meerdere keren herhaald worden. Het gebruik hiervan kan interessant zijn om bijvoorbeeld het wachtwoord van de database gebruiker mee te geven aan de OnsDB client, zodat deze niet in het configuratiebestand opgeslagen hoeft te worden.

Configuratie via omgevingsvariabelen

Elke instelling uit het configuratiebestand kan ook met een omgevingsvariabele worden overschreven. Gebruik ONSDB_, gevolgd door de sectienaam en instelling in hoofdletters; vervang . en - door _. Bijvoorbeeld:

ONSDB_ONSDB_CUSTOMER_CODE=AB1234
ONSDB_DATABASE_PASSWORD=geheim
ONSDB_ONSDB_DOWNLOAD_WORKERS=2

Omgevingsvariabelen hebben voorrang op het configuratiebestand. Dit is vooral geschikt voor geheimen in containers en taakplanners. Een omgevingsvariabele kan geen nieuwe [resource.<meervoudige-resource-naam>]-sectie maken, maar kan wel een instelling overschrijven van een resource-sectie die al in het configuratiebestand staat. Zo wordt pagesize in [resource.presence_logs] overschreven met ONSDB_RESOURCE_PRESENCE_LOGS_PAGESIZE.

Het --set argument heeft voorrang op zowel omgevingsvariabelen als het configuratiebestand.

Categorieën

[onsdb]

Deze categorie bevat instellingen gerelateerd aan de werking van OnsDB en kan ingericht worden met de volgende parameters:

• De Stage van de applicatie moet opgegeven worden. Geldige waarden zijn development, production. Voorbeeld:

  stage = production

• De customer code van de omgeving moet opgegeven worden. Voorbeeld:

  customer-code = TE1002

  Vraag de klantcode van je eigen omgeving op bij de applicatiebeheerder; dit is niet de URL van de Ons-applicatie. De code heeft de vorm XX0000 of XX0000_0. Koppelpartners kunnen TE1002 gebruiken om op development te testen.

  Medewerkers van een zorgorganisatie gebruiken een eigen test- of productieomgeving; zie Toegang configureren. De customer code kan in Ons Administratie gevonden worden bij de Zorginstellinggegevens.

• De connector moet opgegeven worden. Dit is de technische naam van de koppeling in het Ons API Dashboard. Meer informatie hierover is te vinden in OnsDB Toegang Configureren via Ons API Dashboard. Voorbeeld:

  connector=example_connector

  Gebruik de waarde Technical name uit het Dashboard, niet de zichtbare naam van de koppeling. Alleen kleine letters, cijfers en underscores zijn toegestaan.

• Start en end kunnen gebruikt worden om het begin en einde van een periode op te geven. Deze periode wordt gebruikt om de tabellen die dat ondersteunen, tijdsgebonden op te halen. Hiermee worden onnodig lange doorlooptijden voorkomen. De datums kunnen in het verleden en in de toekomst liggen. Een einddatum in de toekomst is bijvoorbeeld handig voor het ophalen van toekomstige roostertoewijzingen.

  • Een vaste datum geef je op als jjjj-mm-dd. De einddatum is tot-en-met. Datums moeten op of na 2000-01-01 liggen en start mag niet na end liggen. Voorbeeld:

    start = 2019-01-01
    end = 2019-05-01

  • Er zijn een aantal speciale waardes die ook gebruikt kunnen worden:

    today
    yesterday

  Deze berekenen de huidige dag of gisteren op basis van het moment van starten van OnsDB, in de tijdzone van de machine. Ook now betekent de huidige dag. Een ISO-tijdstempel, zoals 2026-01-15T18:30:00+01:00, wordt als kalenderdatum gebruikt.

  Globale start en end hebben dezelfde standaardwaarden als in OnsDB 4. Als start ontbreekt of is uitgecommentarieerd, wordt 1 januari van het vorige jaar gebruikt (now/y-1y). Als end ontbreekt of is uitgecommentarieerd, wordt gisteren gebruikt (now-1d). Deze datums worden bij iedere run opnieuw bepaald.

  Een expliciet lege waarde maakt alleen die grens onbegrensd. Met alleen start = wordt dus alle historie tot en met gisteren opgehaald; met alleen end = wordt vanaf 1 januari van het vorige jaar ook toekomstige data opgehaald. Om de volledige periode op te halen, maak je beide waarden leeg:

  [onsdb]
  start =
  end =

  Dit werkt ook met --set onsdb.start= en --set onsdb.end=, of expliciet lege omgevingsvariabelen ONSDB_ONSDB_START en ONSDB_ONSDB_END. Het weglaten van een instelling is dus iets anders dan een lege waarde opgeven.

  Relatieve start- en einddatums zijn handig voor bijvoorbeeld de huidige of vorige week, maand of jaar. De meeste relevante eenheden zijn d (dagen), w (weken), M (maanden) en y (jaren). Met + en - tel je een periode op of af. Met / rond je af naar het begin van een periode: /w naar maandag, /M naar de eerste dag van de maand en /y naar 1 januari. Bewerkingen worden van links naar rechts uitgevoerd. Voorbeelden:

  • now-30d: 30 dagen vóór de huidige datum.
  • now/M: de eerste dag van de huidige maand.
  • now/M-1M: de eerste dag van de vorige maand.

• Met include en exclude kan worden aangegeven welke tabellen juist wel of niet gedownload moeten worden. Beide parameters verwachten een komma-gescheiden lijst van tabelnamen.

  • Om bijvoorbeeld alleen de invoices en invoice_rows te downloaden:

    include = invoices, invoice_rows

  • Om bijvoorbeeld alle tabellen behalve de presence_logs te downloaden:

    exclude = presence_logs

• Met de optionele parameter timezone kun je OnsDB configureren om een consistente tijdzone te hanteren (zie https://en.wikipedia.org/wiki/List_of_tz_database_time_zones voor eventuele variabelen). Als deze instelling wordt gebruikt, dan worden alle datetime waardes omgezet naar deze tijdzone voordat ze worden weggeschreven naar de database. Dit is alleen van toepassing op datetime waardes. Waardes met het type date worden niet aangepast. Voorbeeld:

  timezone = Europe/Amsterdam

• De schema-version parameter biedt de mogelijkheid om op eigen gelegenheid te migreren naar een nieuwere versie van het datamodel. Als deze instelling niet wordt opgegeven, zal altijd de meest recente versie van het datamodel gedownload worden. Voorbeeld:

  schema-version = 4195

  Controleer met --list-versions welke datamodellen beschikbaar zijn; zie Beschikbare datamodellen. Raadpleeg Datamodellen in OnsDB voor de tabelbeschrijvingen en ondersteuning. Een versie die niet beschikbaar is laat de download stoppen; het vastzetten van een datamodel bewaart geen oude gegevens die in Ons zijn verwijderd.

• Met de download-workers instelling wordt aangegeven hoeveel workers gebruikt mogen worden tijdens het downloaden. De waarde van deze instelling kan invloed hebben op de doorlooptijd van OnsDB. De standaard en maximale waarde van deze instelling is 4.

• Met log-jobs bepaal je of OnsDB de start en afronding van iedere download- en verwerkingstaak logt. De standaardwaarde is true. Met log-jobs = false worden deze taakmeldingen weggelaten uit de uitvoer en het logbestand. De samenvatting per resource, waarschuwingen, foutmeldingen en de live voortgang blijven zichtbaar.

• Mocht er gebruik gemaakt worden van een proxy-server, dan kan de URL van de proxy server aangegeven worden in de proxy parameter.

• De report-file parameter kan eventueel gebruikt worden om een rapport te laten opslaan. Dit rapport bevat een overzicht van de doorlooptijd en eventuele fouten die zijn tegengekomen. In de bestandsnaam wordt {date} vervangen door de startdatum van de run in de notatie jjjj-mm-dd. Voorbeeld: report-file = onsdb-report-{date}.txt.

• OnsDB verdeelt downloads automatisch in pagina's voor tabellen die dit ondersteunen. Andere tabellen worden in één download opgehaald. Je hoeft zelf geen dagvensters of vervolgaanvragen te plannen.

  Voor tabellen die datumfilters ondersteunen blijft de ingestelde periode op iedere pagina gelden. Tabellen zonder datumfilters worden volledig opgehaald. Een expliciet lege grens blijft onbegrensd.

• Pagesize: standaard 200.000, maximaal 1.000.000. Dit is het streefaantal records per cursorpagina. Sommige resources maken complete groepen af en kunnen daardoor meer records teruggeven. Een grotere pagina kan efficiënter zijn doordat minder taken nodig zijn, maar vergroot ook het risico op een timeout wanneer het wachten op de eerste response of nieuwe gegevens te lang duurt. Een kleinere pagina resulteert doorgaans in meer taken. In principe hoeft de standaardwaarde niet te worden aangepast.

  De client wacht maximaal 2 minuten op de responseheaders en hanteert een verbindingstimeout van 10 minuten zonder activiteit. Dit is geen maximale totale downloadduur: een download die gegevens blijft ontvangen mag langer duren. De API-gateway kan daarnaast eigen timeouts hanteren.

• Met keep-existing-records bepaal je of bestaande gegevens in geselecteerde tabellen behouden blijven. De standaardwaarde is false: geselecteerde tabellen worden bij iedere run opnieuw aangemaakt. Met true blijft een compatibele tabel met primary key bestaan en worden gedownloade records ingevoegd of bijgewerkt. Een compatibele tabel zonder primary key wordt geleegd en volledig opnieuw gevuld. Een ontbrekende of niet-compatibele tabel wordt altijd opnieuw aangemaakt.

  Deze instelling geldt voor alle geselecteerde resources en kan per resource worden overschreven.

  Bestaande records die niet opnieuw worden gedownload blijven in een behouden tabel staan, ook als ze buiten de gekozen periode vallen of inmiddels uit Ons zijn verwijderd. Gebruik een volledige verversing wanneer de doel-database zulke records niet moet behouden. Zie ook de informatie onder het kopje Gegevens behouden en downloads herhalen in de handleiding Gebruiken van OnsDB 5.

• Met drop-unselected-tables bepaal je of OnsDB alle bestaande tabellen verwijdert die niet bij de geselecteerde resources van deze download horen. De standaardwaarde is true: na een run blijven alleen de tabellen van de geselecteerde resources over. Ook tabellen die niet door OnsDB zijn gemaakt worden verwijderd. Stel deze optie in op false als de database ook tabellen bevat die OnsDB moet behouden. De opschoning start op een aparte databaseverbinding, zodat database workers en downloads direct kunnen beginnen.

[resource.<meervoudige-resource-naam>]

Met een resource-sectie overschrijf je instellingen voor één resource. Gebruik exact de table-naam uit het schema, bijvoorbeeld [resource.presence_logs]. Een resource-sectie die niet overeenkomt met een tabel in het teruggegeven schema wordt genegeerd met een waarschuwing. Dit geldt ook voor tabellen die door include of exclude zijn uitgefilterd. De volgende instellingen kunnen per resource worden ingesteld: start, end, pagesize en keep-existing-records.

Een ontbrekende start of end erft de overeenkomstige globale grens. Een ingestelde datum vervangt die grens; een expliciet lege waarde (start = of end =) maakt die grens onbegrensd, ook als er een globale datum is ingesteld. Beide grenzen kunnen onafhankelijk worden aangepast. Niet-lege datumgrenzen kunnen alleen worden ingesteld voor tabellen die datumfilters ondersteunen. Een eigen pagesize kan alleen worden ingesteld voor tabellen die downloads in pagina's ondersteunen. OnsDB stopt met een fout als de tabel de ingestelde optie niet ondersteunt.

Ook een leeg CLI-argument, zoals --set resource.presence_logs.start=, of een expliciet lege resource-omgevingsvariabele, zoals ONSDB_RESOURCE_PRESENCE_LOGS_START, maakt die grens onbegrensd. Een niet-ingestelde omgevingsvariabele verandert de overerving niet. --set blijft voorrang houden op omgevingsvariabelen en het configuratiebestand.

Voorbeeld:

[resource.presence_logs]
start = now/M-1M
end = now/M-1d
keep-existing-records = true

Voorbeeld om voor één tabel beide globale datumgrenzen uit te zetten:

[onsdb]
start = 2026-01-01
end = 2026-01-31

[resource.presence_logs]
start =
end =

Andere tabellen die datumfilters ondersteunen blijven de globale periode gebruiken. Laat in de resource-sectie end weg als alleen start onbegrensd moet zijn, of andersom.

[database]

Deze categorie bevat de verbindingsinstellingen van de lokale database en kan ingericht worden met de volgende parameters:

• Het type van de lokale database moet opgegeven worden. Om verbinding te maken met een Microsoft SQL server via ODBC:

  type = mssql

  Om verbinding te maken met een MySQL server:

  type = mysql

  Vanaf OnsDB.exe versie 4.6.0 is het ook mogelijk om de waarde aan te passen naar databasetype sqlite3. Hiermee is het niet noodzakelijk dat er een verbinding is met een database server, maar wordt de download in plaats daarvan lokaal aangeleverd in een .db bestand. Met bijvoorbeeld de DB Browser for SQlite kun je vervolgens toegang tot de ruwe data krijgen door het bestand hiermee te openen. De volgende configuratie moet dan worden toegevoegd:

  type = sqlite3

• Om gebruik te maken van een Microsoft SQL Server database moet een ODBC koppeling gemaakt worden. De odbc instelling moet de naam van deze koppeling bevatten. Voorbeeld:

  odbc = onsdb4

• De parameters username en password kunnen gebruikt worden indien een gebruikersnaam en wachtwoord nodig zijn om verbinding te kunnen maken met de lokale database. Voorbeeld:

  username = onsdb
  password = 123

• Met de database instelling wordt de naam van de te gebruiken database opgegeven. Voorbeeld:

  database = onsdb

• Voor MySQL geef je met hostname en port de databaseserver op. Zonder deze instellingen gebruikt OnsDB localhost en poort 3306. Voorbeeld:

  host = 192.168.1.1
  port = 3308

Voor SQL Server stel je server, poort en doel-database in de ODBC-gegevensbron in. Als je de server met hostname overschrijft en een afwijkende poort nodig hebt, gebruik dan het SQL Server-formaat hostname = servernaam,1433; de afzonderlijke port-instelling vervangt dit niet. Zie Databaseconfiguratie.

• Eventuele extra verbindingsopties kunnen opgegeven worden met behulp van de parameter options. Voor MySQL gebruikt de volgende optie de lokale tijdzone van de machine; de waarde Local is hoofdlettergevoelig. Gebruik [onsdb] timezone = Europe/Amsterdam om expliciet de Nederlandse tijdzone te kiezen. Gebruik timezone en loc in options niet tegelijk: OnsDB voegt voor timezone zelf een loc toe, en een loc in options overschrijft die.

  options = loc=local

  Deze parameter kan ook gebruikt worden voor het tot stand brengen van een versleutelde verbinding tussen OnsDB en de geconfigureerde database (TLS). De optie heet 'tls' en kan de volgende waarden bevatten:

  • false: De standaardwaarde, waarbij de verbinding niet versleuteld is. Als de database een versleutelde verbinding verwacht, kan de verbinding hierdoor falen.
  • preferred: Als de database versleutelde verbinding ondersteunt, zal deze tot stand worden gebracht, maar de verbinding zal niet falen als geen versleutelde verbinding wordt ondersteund.
  • skip-verify: Bij deze optie wordt de client gedwongen om een versleutelde verbinding op te zetten, maar zal niet proberen het certificaat van de server te verifiëren. Dat betekent dat de verbinding ook tot stand komt bij een zelf ondertekend- of verlopen servercertificaat.
  • true: Bij deze optie wordt een versleutelde verbinding vereist. Als de server dat niet ondersteunt, of als het certificaat is verlopen of niet gevalideerd kan worden, dan zal de verbinding falen.

• Een combinatie van options kan ook worden opgegeven. Bijvoorbeeld:

  options = loc=local&tls=preferred

• Met de workers instelling kan het aantal workers dat naar de database schrijven worden ingesteld. Als de bottleneck van de Ons DB run vooral komt door het traag weg schrijven naar de database, kan het helpen om deze configuratie te verhogen.

• De batch-rows stelt het aantal rijen in dat per keer naar de database weggeschreven worden. De standaard waarde hiervoor zou al goed moeten zijn. Als de RTT (round-trip time) naar de database lang is, kan het helpen om dit te verhogen.

[queue]

In deze categorie kan de interne queue geconfigureerd worden die gebruikt wordt door de OnsDB client. Deze queue is er om het downloaden van de data en het wegschrijven naar de database te ontkoppelen.

De onsdb.download-workers zijn verantwoordelijk voor het downloaden van data en het plaatsen van items op de queue. De database.workers zijn verantwoordelijk voor lezen van items uit de queue en het weg te schrijven naar de database.

De queue bewaart downloadsegments in het geheugen. De standaardwaarden zijn voor de meeste situaties passend: een download-threshold van 1GB en segments van maximaal 64MB. Door deze instellingen af te stemmen op het beschikbare geheugen en de snelheid van de database kan de doorlooptijd soms worden verbeterd.

De volgende instellingen sturen de queuegrootte en de afzonderlijke segments in bytes.

Gebruik een positief geheel aantal bytes, of een waarde met KB, MB of GB, bijvoorbeeld 256MB. Deze eenheden zijn stappen van 1024 bytes; decimalen zoals 1.5GB zijn niet toegestaan.

Deze instellingen zijn nieuw in OnsDB 5. Gebruik voor de download-threshold de omgevingsvariabele ONSDB_QUEUE_DOWNLOAD_THRESHOLD_BYTES of bijvoorbeeld het CLI-argument --set queue.download-threshold-bytes=256MB.

Tijdens het downloaden wordt de data in kleinere stukken opgesplitst, die de database workers al kunnen verwerken. OnsDB hoeft dus niet eerst een volledige pagina te downloaden voordat het wegschrijven naar de database begint.

• max-bytes is een threshold voor het starten van downloads. Zodra de gecommitteerde queuedata deze waarde bereikt, wachten nieuwe download-workers voordat ze een nieuwe response openen. Downloads die al lopen mogen hun segments nog steeds schrijven, waardoor de queue tijdelijk groter kan worden. Dit is dus geen harde geheugengrens; kies een waarde waarbij ook ruimte overblijft voor de lopende downloads.

• segment-max-bytes geeft aan hoe groot één segment maximaal mag worden voordat het naar de queue wordt geschreven.

[certificate]

Deze categorie bevat de optionele identifier voor het TLS-certificaat. Deze waarde wordt als suffix in de Common Name gebruikt en mag alleen letters, cijfers en underscores bevatten. Als identifier niet is ingesteld, gebruikt OnsDB de hostname van de machine. Stel een vaste identifier in als de hostname kan veranderen. Voorbeeld:

identifier= example_identifier

Voorbeelden configuratiebestanden

In de voorbeelden hieronder zijn de verplichte instellingen actief. Vervang de voorbeeldwaarden door de gegevens van je eigen omgeving en database. De MySQL-gebruikersnaam en het wachtwoord zijn voorbeelden; pas ze aan aan de authenticatie van je databaseserver. Optionele instellingen beginnen met #; verwijder dit teken alleen als de instelling nodig is.

[onsdb]
stage = development
customer-code = TE1002
connector = example_connector
#keep-existing-records = false
#drop-unselected-tables = true
#start = now/y-1y
#end = now-1d
#include = presence_logs
#exclude =
#schema-version = 4223
#download-workers = 4
#log-jobs = true
#proxy = http://localhost:8080
#report-file = onsdb-report-{date}.txt
#pagesize = 200000
#timezone = Europe/Amsterdam

[database]
type = mssql
odbc = onsdb4
#username = onsdb
#password = vervang-dit-wachtwoord
#database = onsdb
#hostname = 192.168.1.1
#port = 3308
#workers = 4
#batch-rows = 1000

[queue]
#download-threshold-bytes = 1GB
#segment-max-bytes = 64MB

[certificate]
#identifier = example_identifier

[onsdb]
stage = development
customer-code = TE1002
connector = example_connector
#keep-existing-records = false
#drop-unselected-tables = true
#start = now/y-1y
#end = now-1d
#include = presence_logs
#exclude =
#schema-version = 4223
#download-workers = 4
#log-jobs = true
#proxy = http://localhost:8080
#report-file = onsdb-report-{date}.txt
#pagesize = 200000
#timezone = Europe/Amsterdam

[database]
type = mysql
username = onsdb
password = vervang-dit-wachtwoord
database = onsdb
#hostname = 192.168.1.1
#port = 3308
#options = loc=Local
#workers = 4
#batch-rows = 1000

[queue]
#download-threshold-bytes = 1GB
#segment-max-bytes = 64MB

[certificate]
#identifier = example_identifier

Controle op de clientversie

Vóór iedere download controleert OnsDB of er meldingen zijn voor de gebruikte clientversie. Een melding kan bijvoorbeeld een nieuwe versie aankondigen (INFO), waarschuwen voor een probleem of het einde van ondersteuning (WARN), of aangeven dat je de client moet bijwerken (ERROR). OnsDB installeert updates niet zelf.

Met version-check-stop-level in [onsdb] kies je bij welke meldingen OnsDB vóór de download stopt:

Een gestopte download geeft exitcode 1 en schrijft het ingestelde rapport waar mogelijk. Als de controle zelf niet uitgevoerd kan worden, meldt OnsDB dit en gaat de download door. NEVER schakelt alleen het stoppen voor deze versiemeldingen uit; gewone configuratie-, verbindings- en downloadfouten blijven fouten. --help en --list-versions voeren deze controle niet uit.