Les 2 - ADR en ORM (EF core)

In deze les twee drieletterige afkortingen ADR en ORM, die niet per se heel veel met elkaar te maken hebben, maar wel allebei over documentatie/single source of truth gaan, en beide in je repository terecht komen (ORM Code first als code die het data model vastlegt, ADR als markdown bestanden die bij elkaar je software architectuur beschrijven). Beide horen wel bij DevOps en dragen dan ook bij CDMM Checkpoints; zie hiervoor de week opdracht.

"CDMM Beginner level Design & Architecture: At this level the importance of applying version control to database changes will also reveal itself." - https://www.infoq.com/articles/Continuous-Delivery-Maturity-Model/

1. ORM - Object Relation Mapper

In de workshop zijn kort 'volumes' behandeld in Docker, die nodig zijn voor persistent opslag. Althans als je data langer moet bestaan dat de container, wat op productie het geval is, als je een database gebruikt.

Neem de Docker documentatie `Volumes' (negeer de oude constructie 'mounts' e.d. dit is alleen voor oudere containers die dit gebruikten).

Lees het artikel DevOps for databases van Christian Melendez (z.d.). Als oefening kun je evt. de Contonso voorbeeld code downloaden, de dotnet ef tools installeren zoals het artikel aangeeft en de besproken oefening meedoen.

“Database refactorings […] involve three different changes that have to be done together

  • Changing the database schema
  • Migrating the data in the database
  • Changing the database access code”

Quote 1: (Fowler, 2016)

Van de 3 wijzigingen uit quote 1 mist in simpele applicaties vaak het echte migreren van bestaande data. Dit vereist ook vaak het nadenken over hoe deze data te migreren en het handmatig schrijven/uitbreiden van de migratie code (de Up() en Down() methode in EF core.

1.1 Voorbeeld casus ORM: Data model van hypothetische CDMM applicatie

Het CDMM die wekelijks terugkomt, en je als student kan/moet gebruiken om je DevOps maturity te bepalen heeft ook een datamodel die wellicht nuttig is om expliciet te maken. In een les tekende ik dit grove data model (UML ERM diagram):

Klassendiagram CDMM checkbox self assessment

Figuur 1: ORM oefening. Het in een les besproken mogelijke klassendiagram voor de database in weekopdracht.

UML is prima om als 'schets' te gebruiken. Start on a whiteboard. Maar voor naslag is het wel nuttig een wat netter diagram te maken. Bijvoorbeeld met PlantuML of Mermaid zoals je al deed in weekopdracht 1: Documentation as code.

1.2 Upgraden naar diagrams as code

In bovenstaand diagram missen nog de categorie en het niveau van een 'CDMM checkpoint'. Oftewel hoe we het checkpoint in de tabel plaatsen qua kolom respectevelijk rij waar deze komt. In OO speak zijn dit CDMMCheckpointNiveau en CDMMCheckpointCategorie. Als we bovenstaande schets uitwerken tot een ERM diagram krijg je figuur 3. Dit ERD diagram geeft het gewenste datamodel van een CDMM Checkpoint.






CDMMCategorie

CDMMCategorie

Id

Beschrijving



CDMMNiveau

CDMMNiveau

Id

Beschrijving



Student

Student

Naam

Student nummer



CDMMSelfAssessment

CDMMSelfAssessment

Datum

Student

CDMMCheckpoint



Student--CDMMSelfAssessment

0..N
1



CDMMEvaluation

CDMMEvaluation

CDMMCheckpoint

IsChecked

Argumentatie



CDMMSelfAssessment--CDMMEvaluation

0..N
1



CDMMCheckpoint

CDMMCheckpoint

CDMMCategorie

CDMMNiveau

Code

Titel

Beschrijving



CDMMEvaluation--CDMMCheckpoint

1
1



CDMMCheckpoint--CDMMCategorie

0..N
1



CDMMCheckpoint--CDMMNiveau

0..N
1

Figuur 2: ORM oefening. Het in de les besproken mogelijke klassendiagram voor de database in weekopdracht.

Op deze manier is het mogelijk voor een student om zelf een self assessment te doen door het CDMM in te vullen voor een bepaalde beroepsproduct en -project.

1.3 CDMM Applicatie -> User stories

Je zou zelfs een applicatie kunnen maken om CDMM beoordelingen te doen, waar dit nu nog een exercitie op papier is, of in markdown, om bij elke wekelijkse DevOps opdracht dit in te vullen, inclusief argumentatie voor het tonen van begrip cq. het verdiepen in CDMM.

Voor zo'n applicatie zijn hier enkele mogelijke user stories vanuit 'docent' en 'student' oogpunt.

  • Als docent wil ik dat studenten een self assessment aan de hand van het Continuous Delivery Maturity Model (CDMM) kunnen maken en deze beargumenteren, zodat zij kunnen zien waar zij staan qua DevOps volwassenheid, en zich in DevOps best practices moeten verdiepen. - MUST
  • Als student wil ik makkelijk een CDMM beoordeling kunnen invullen en hierbij achtergrond informatie krijgen over de verschillende CDMM checkpoints zodat ik informatie over bijbehorende punten kan krijgen, minder snel verkeerd interpreteer, en ook niet helemaal op de website te moeten opzoeken - SHOULD
  • Als student wil ik makkelijk een ingevuld CDMM assessment kunnen exporteren, zodat ik deze — zowel als PDF en als markdown tekst — kan inleveren als bewijslast voor school en als markdown/documentation as code op kan nemen in mijn huiswerkopdrachten of beroepsproduct (DevOps BP) - COULD
  • Als student wil ik iteratief een assessment invullen op verschillende momenten in een project en de ook zo kunnen terugzien, zodat ik vooruitgang zie en kan demonstreren in mijn project. - WANNAHAVE/WONTHAVE

Dit is een goede video om in de les samen te kijken ter relativering/van ORM's:

  • Gorman, Christin (2011) (Vimeo). Zie bronnen.

Bekijk de Vimeo‑video (Gorman, 2011).

Screenshot uit de Gorman‑video

Ook 'Continuous Delivery' frontman Dave Farley haalt de video van Gorman aan in zijn boek Modern Software Engineering (tip!). Martin Fowler's artikel 'ORM hate' is een meer genuanceerde kijk op deze kwestie (Fowler, z.d.). Dat je geen SQL kennis zou hoeven te te hebben bij gebruik ORM is een drogreden, vanwege de ca. 10% gevallen die overblijft (en idd soms slechte performance). Hoewel de hoeveelheid SQL achtige annotaties in Gorman's wel wat hooggekozen is. Maar voor de resterende 10% moet je namelijk inzicht hebben in performance gevolgen. Voor SQL Server bv. van impact van bepaalde join volgorde en handmatige optimalisaties via keys toevoegen of verwijderen met hierachter technische concepten als 'table scan' vs 'index scan', etc. (Anvesh, 2023). En daarbij vergeleken is SQL syntax a walk in the park. Maar het 'single point of truth' of 'single point of definition' dat een goed ORM framework met ook 'migrations' mogelijkheden je kan geven. Al kom je als student niet snel in aanraking met een situatie waarbij je productie data hebt, die ook gemigreerd moet naast DB schema en applicatiecode, zoals Fowler in zijn artikel/blog 'Evolutionary database design' de big 3 aangeeft (Fowler, 2016).

Architecture Decision Records

In moderne software development projecten wordt vaak te weinig gedocumenteerd. Nieuwe developers kunnen nergens overzicht krijgen over een project. En ook bestaande developers in een project vergeten soms waarom bepaalde keuzes zijn gemaakt en het blijft dan bij 'het is nou eenmaal'.

Een lichtgewicht manier om software architectuur te beschrijven zijn Architecture Decision records. Er bestaan ook tools om ADR records aan te maken, maar de meerwaarde hiervan is beperkt. De tool kan slechts een template neerzetten, de echte waarde (en tijdsbesteding) zit in het goed invullen, en ook per keer nadenken welke van de kopjes relevant is en hoe in te vullen. In plaats van als een robot templates invullen, die vervolgens niemand wil lezen, omdat het toch niet zoveel zegt.

"Software architecture is those decisions which are both important and hard to change. This means it includes things like the choice of programming language, something architects sometimes gloss over or dismiss. ... Said another way, software architecture is those decisions which, if made poorly, will make a project either succeed or fail, in a needlessly expensive way." - https://kylecordes.com/2015/fowler-software-architecture

In plaats van eenmalig de hele software architectuur op te stellen sluiten ADR's aan bij de Agile aanpak, met het idee van een ADR is ook om telkens als er een beslissing is genomen, of voorstel is gedaan een ADR aan te maken. Dit zo ergens op schrift (e.g. in een repo) vastleggen is ook een manier om telkens terugkomende discussies te voorkomen volgense deze Reddit post.

ADR's zijn dus ook 'text records' die direct bij de code zitten; in versiebeheer. Typisch in de vorm van markdown .md bestand. De naam van het bestand geeft kort de beslissing weer, of het gebied waar deze zich bevind. Verder geef je de ADR's vaak ook een datum mee, en ook een status, van 'Proposed' tot 'Accepted' (of 'Rejected') en later mogelijk zelfs nog 'Deprecated'. Bekijk wat voorbeelden in de PriemChecker repo.

ADR vorbeeld casus: Web applicatie server

In de weekopdracht van deze week moet je de vorige week gemaakte applicatie uitbreiden naar een WEB API en ook hosten met een webapplicatieserver. Een veelgebruikte is nginx (spreek uit: 'Engine X'). Hiervoor maak je ook kennis met ADR's: Architecture Decision Records.

"What are alternatives to nginx when you want a webapplication server for a .NET application that you also want to containerize?"

Nginx alternatives according to Chat GPT

Leerdoelen

Check met onderstaande leerdoelen of je de behandelde stof begrepen hebt en toetsvragen kunt beantwoorden.

  • Je kunt toelichten wat een ADR is, en waarom het documenteren van architectuurbeslissingen belangrijk is voor traceerbaarheid en langlopende projecten/lang draaiende software.
  • Je kunt uitleggen wat een ORM is en hoe het het programmeren tegen relationele databases vereenvoudigt.
  • Je kent het verschil tussen Code First, Model First en Database First aanpakken van ORMs als Entity Framework of Hibernate.
  • Je kunt beschrijven wat de rol is van de Up() en Down() methodes bij Entity Framework
  • Je begrijpt hoe migratietools zoals Entity Framework en Flyway bijdragen aan een DevOps-werkwijze door schemawijzigingen versieerbaar en reproduceerbaar te maken.
  • Je kunt uitleggen wat Martin Fowler bedoelt met een evolutionary databases

Quiz

Test je kennis met deze korte multiple choice quiz.

Bronnen

Last change: 2025-09-11