18 dec 2025·7 min
Postgres-schemaplanning: stapsgewijze aanpak
Postgres-schemaplanning helpt entiteiten, constraints, indexen en migraties te definiëren vóór codegeneratie, zodat je later minder hoeft te herschrijven.
Postgres-schemaplanning helpt entiteiten, constraints, indexen en migraties te definiëren vóór codegeneratie, zodat je later minder hoeft te herschrijven.
Als je endpoints en modellen bouwt voordat de databasevorm duidelijk is, eindig je meestal met hetzelfde werk twee keer. De app werkt voor een demo, daarna komen echte data en randgevallen en wordt alles broos.
De meeste herschrijvingen komen door drie voorspelbare problemen:
Elk van deze dwingt wijzigingen af die doorwerken in code, tests en client-apps.
Schema-planning voor Postgres betekent eerst het datacontract vastleggen en daarna code genereren die daarbij past. In de praktijk ziet dat eruit als het opschrijven van entiteiten, relaties en de paar queries die er echt toe doen, en daarna constraints, indexen en een migratie-aanpak kiezen voordat een tool tabellen en CRUD scaffold.
Dit is extra belangrijk als je een vibe-coding platform gebruikt zoals Koder.ai, waar je veel code snel kunt genereren. Snelle generatie is fantastisch, maar veel betrouwbaarder als het schema vastligt. Je gegenereerde modellen en endpoints hebben later minder aanpassingen nodig.
Dit gaat vaak mis als je planning overslaat:
Een goed schema-plan is simpel: een beschrijving in gewone taal van je entiteiten, een concept van tabellen en kolommen, de belangrijkste constraints en indexen, en een migratiestrategie die je veilig laat veranderen naarmate het product groeit.
Schema-planning werkt het best wanneer je begint met wat de app moet onthouden en wat mensen met die data moeten kunnen doen. Schrijf het doel in 2–3 duidelijke zinnen. Als je het niet simpel kunt uitleggen, maak je waarschijnlijk extra tabellen die je niet nodig hebt.
Vervolgens focus je op de acties die data creëren of veranderen. Die acties zijn de echte bron van je rijen en tonen wat gevalideerd moet worden. Denk in werkwoorden, niet in zelfstandige naamwoorden.
Bijvoorbeeld: een boekingsapp moet mogelijk een booking aanmaken, verzetten, annuleren, terugbetalen en de klant berichten. Die werkwoorden suggereren snel wat opgeslagen moet worden (tijdsloten, statuswijzigingen, geldbedragen) voordat je een tabelnaam kiest.
Leg ook je leespaden vast, want lezen stuurt later de structuur en indexering. Maak een lijst van de schermen of rapporten die mensen echt gebruiken en hoe ze de data doorsnijden: “Mijn boekingen” gesorteerd op datum en gefilterd op status, admin-zoekopdracht op klantnaam of boekingsreferentie, dagelijkse omzet per locatie, en een auditweergave wie wat wanneer heeft aangepast.
Noteer ten slotte niet-functionele behoeften die schema-keuzes beïnvloeden, zoals auditgeschiedenis, soft deletes, multi-tenant scheiding of privacyregels (bijv. wie contactgegevens mag zien).
Als je van plan bent code te genereren na deze stap, worden deze aantekeningen sterke prompts. Ze beschrijven wat vereist is, wat kan veranderen en wat doorzoekbaar moet zijn. Als je Koder.ai gebruikt, maakt dit Planning Mode veel effectiever omdat het platform dan werkt vanuit echte requirements in plaats van gissingen.
Voordat je tabellen aanraakt, schrijf je in eenvoudige bewoordingen wat je app opslaat. Begin met het opsommen van de zelfstandige naamwoorden die je steeds herhaalt: user, project, message, invoice, subscription, file, comment. Elk woord is een potentiële entiteit.
Voeg bij elke entiteit één zin toe die antwoord geeft op: wat is het en waarom bestaat het? Bijvoorbeeld: “Een Project is een werkruimte die een gebruiker aanmaakt om werk te groeperen en anderen uit te nodigen.” Dit voorkomt vage tabellen zoals data, items of misc.
Eigendom is de volgende grote beslissing en beïnvloedt bijna elke query die je schrijft. Bepaal voor elke entiteit:
Bepaal vervolgens hoe je records identificeert. UUIDs zijn handig wanneer records vanaf veel plekken kunnen worden aangemaakt (web, mobiel, background jobs) of wanneer je geen voorspelbare IDs wilt. Bigint IDs zijn kleiner en sneller. Als je een mensvriendelijke identifier nodig hebt, houd die dan apart (bijv. een korte project_code die uniek is binnen een account) in plaats van die als primaire sleutel te forceren.
Schrijf tenslotte relaties in woorden voordat je iets gaat diagrammen: een user heeft veel projects, een project heeft veel messages, en users kunnen bij veel projecten horen. Markeer elke link als verplicht of optioneel, zoals “een message moet bij een project horen” versus “een invoice kan bij een project horen.” Deze zinnen worden later je bron van waarheid voor codegeneratie.
Zodra de entiteiten duidelijk in gewone taal lezen, zet je elk van hen om in een tabel met kolommen die overeenkomen met feiten die je echt moet opslaan.
Begin met namen en types waar je bij blijft. Kies consistente patronen: snake_case kolomnamen, hetzelfde type voor hetzelfde idee, en voorspelbare primaire sleutels. Voor timestamps geef de voorkeur aan timestamptz zodat tijdzones je niet verrassen. Voor geld gebruik numeric(12,2) (of sla centen op als integer) in plaats van floats.
Voor statusvelden gebruik je ofwel een Postgres-enum of een text-kolom met een CHECK constraint zodat toegestane waarden gecontroleerd zijn.
Bepaal wat verplicht versus optioneel is door regels te vertalen naar NOT NULL. Als een waarde moet bestaan om de rij logisch te maken, maak het verplicht. Als het echt onbekend of niet van toepassing is, staat een NULL toe.
Een praktisch setje standaardkolommen om voor te plannen:
id (uuid of bigint, kies één aanpak en blijf consistent)created_at en updated_atdeleted_at alleen als je echt soft deletes en herstel nodig hebtcreated_by wanneer je een duidelijke audittrail van wie wat deed nodig hebtMany-to-many relaties worden bijna altijd join-tabellen. Bijvoorbeeld, als meerdere gebruikers kunnen samenwerken in een app, maak app_members met app_id en user_id, en dwing uniekheid af op het paar zodat duplicaten niet kunnen ontstaan.
Denk vroeg na over historie. Als je weet dat je versiebeheer nodig zult hebben, plan dan een ongewijzigde (immutable) tabel zoals app_snapshots, waarbij elke rij een opgeslagen versie is gelinkt aan apps via app_id en gestempeld met created_at.
Constraints zijn de vangrails van je schema. Bepaal welke regels te allen tijde waar moeten zijn, ongeacht welke service, script of admin-tool de database aanraakt.
Begin met identiteit en relaties. Elke tabel heeft een primaire sleutel nodig, en elk “belongs to”-veld zou een echte foreign key moeten zijn, niet slechts een integer waarvan je hoopt dat die overeenkomt.
Voeg daarna uniekheid toe waar duplicaten echte schade veroorzaken, zoals twee accounts met hetzelfde e-mailadres of twee orderregels met hetzelfde (order_id, product_id).
Hoogwaardige constraints om vroeg te plannen:
amount >= 0, status IN ('draft','paid','canceled'), of rating BETWEEN 1 AND 5.Cascade-gedrag is waar plannen je later veel tijd bespaart. Vraag je af wat mensen echt verwachten. Als een klant verwijderd wordt, moeten hun orders meestal niet verdwijnen. Dat wijst op restrict deletes en het behouden van geschiedenis. Voor afhankelijke data zoals order line items kan cascading van order naar items logisch zijn omdat items zonder parent geen betekenis hebben.
Wanneer je later modellen en endpoints genereert, worden deze constraints concrete vereisten: welke fouten afgevangen moeten worden, welke velden verplicht zijn, en welke randgevallen door ontwerp onmogelijk zijn.
Indexen moeten één vraag beantwoorden: wat moet snel zijn voor echte gebruikers.
Begin bij de schermen en API-calls die je verwacht als eerste te leveren. Een lijstpagina die filtert op status en sorteert op nieuwste heeft andere behoeften dan een detailpagina die gerelateerde records laadt.
Schrijf 5–10 query-patronen in gewone taal voordat je een index kiest. Bijvoorbeeld: “Toon mijn facturen van de laatste 30 dagen, filter op betaald/onbetaald, sorteer op created_at,” of “Open een project en list zijn taken op due_date.” Dit houdt index-keuzes geworteld in echt gebruik.
Een goede eerste set indexen bevat vaak foreign key kolommen gebruikt in joins, veelgebruikte filterkolommen (zoals status, user_id, created_at), en één of twee samengestelde indexen voor stabiele multi-filter queries, zoals (account_id, created_at) wanneer je altijd op account_id filtert en daarna sorteert op tijd.
De volgorde van kolommen in samengestelde indexen is belangrijk. Zet de kolom waar je het meest op filtert (en die het meest selectief is) vooraan. Als je altijd filtert op tenant_id, hoort die vaak vooraan in veel indexen.
Vermijd het indexeren van alles “voor het geval dat.” Elke index voegt werk toe bij INSERT en UPDATE en kan meer schaden dan een iets tragere zeldzame query.
Plan tekstzoekopdrachten apart. Als je alleen eenvoudige “contains”-matching nodig hebt, is ILIKE misschien eerst voldoende. Als zoeken kernfunctionaliteit is, plan dan vroeg voor full-text search (tsvector) zodat je later niet hoeft te herontwerpen.
Een schema is niet “klaar” zodra je de eerste tabellen maakt. Het verandert elke keer dat je een feature toevoegt, een fout corrigeert of meer leert over je data. Als je vooraf je migratiestrategie bepaalt, voorkom je pijnlijke herschrijvingen na codegeneratie.
Houd een eenvoudige regel aan: verander de database in kleine stappen, één feature per keer. Elke migratie moet makkelijk te reviewen zijn en veilig uit te voeren in elke omgeving.
De meeste breuken komen door kolomnamen te veranderen of te verwijderen, of door types te wijzigen. In plaats van alles in één keer te doen, plan een veilige route:
Dit kost meer stappen, maar is in de praktijk sneller omdat het uitval en noodpatches vermindert.
Seed-data hoort ook bij migraties. Bepaal welke referentietabellen “altijd bestaan” (roles, statuses, countries, plan types) en maak ze voorspelbaar. Zet inserts en updates voor deze tabellen in aparte migraties zodat elke ontwikkelaar en elke deploy hetzelfde resultaat krijgt.
Stel verwachtingen vroeg:
Rollbacks zijn niet altijd een perfecte "down migration." Soms is de beste rollback een restore van een backup. Als je Koder.ai gebruikt, is het ook de moeite waard te beslissen wanneer je op snapshots vertrouwt voor snelle herstelopties, vooral vóór risicovolle wijzigingen.
Stel je een kleine SaaS-app voor waarin mensen teams joinen, projecten maken en taken bijhouden.
Begin met het opsommen van entiteiten en alleen de velden die je op dag één nodig hebt:
Relaties zijn eenvoudig: een team heeft veel projecten, een project heeft veel taken, en users voegen zich bij teams via team_members. Taken horen bij een project en kunnen toegewezen zijn aan een gebruiker.
Voeg nu een paar constraints toe die bugs voorkomen die je vaak te laat vindt:
citext gebruikt).Indexen moeten overeenkomen met echte schermen. Bijvoorbeeld, als de takenlijst filtert op project en state en sorteert op nieuwste, plan dan een index zoals tasks (project_id, state, created_at DESC). Als “Mijn taken” een sleutelweergave is, helpt een index zoals tasks (assignee_user_id, state, due_date).
Voor migraties, houd de eerste set veilig en eenvoudig: maak tabellen, primaire sleutels, foreign keys en de kern unique constraints. Een goede vervolgstap voeg je toe nadat gebruik het nodig maakt, zoals soft delete (deleted_at) op taken en het aanpassen van “actieve taken” indexen om verwijderde rijen te negeren.
De meeste herschrijvingen gebeuren omdat het eerste schema regels en gebruiksdetails mist. Een goede planningsronde draait niet om perfecte diagrammen, maar om het vroeg opsporen van valkuilen.
Een veelgemaakte fout is belangrijke regels alleen in applicatiecode houden. Als een waarde uniek, verplicht of binnen een bereik moet zijn, moet de database dat afdwingen. Anders kan een background job, een nieuw endpoint of een handmatige import je logica omzeilen.
Een andere veelgemaakte miss is indexes behandelen als een later probleem. Ze pas toevoegen na lancering sluipt vaak in giswerk, en je indexeert mogelijk het verkeerde terwijl de echte trage query een join of filter op een statusveld is.
Many-to-many tabellen zijn ook een bron van stille bugs. Als je join-tabel duplicaten niet voorkomt, kun je twee keer dezelfde relatie opslaan en uren besteden aan debuggen waarom “deze gebruiker twee rollen heeft”.
Het is ook eenvoudig om tabellen eerst te maken en later te beseffen dat je auditlogs, soft deletes of eventgeschiedenis nodig hebt. Die toevoegingen werken door in endpoints en rapporten.
Ten slotte zijn JSON-kolommen verleidelijk voor “flexibele” data, maar ze halen checks weg en maken indexeren lastiger. JSON is prima voor echt variabele payloads, niet voor kernbusinessvelden.
Voer vóór je code genereert deze snelle checklist uit:
Pauzeer en zorg dat het plan genoeg compleet is om code te genereren zonder achtervolgende verrassingen. Het doel is geen perfectie, maar het dichten van de gaten die later herschrijvingen veroorzaken: ontbrekende relaties, onduidelijke regels en indexen die niet overeenkomen met hoe de app werkelijk gebruikt wordt.
Gebruik dit als een snelle pre-flight check:
amount >= 0 of toegestane statussen).Een snelle sanity-test: stel dat een collega morgen begint. Kan diegene de eerste endpoints bouwen zonder elk uur te vragen “mag dit NULL zijn?” of “wat gebeurt er bij delete?”
Zodra het plan helder leest en de hoofdstromen logisch zijn op papier, zet het om in iets uitvoerbaars: een echt schema plus migraties.
Begin met een initiële migratie die tabellen, types (als je enums gebruikt) en de onmisbare constraints aanmaakt. Houd de eerste versie klein maar correct. Laad wat seed-data en voer de queries uit die je app echt nodig heeft. Als een flow onhandig voelt, pas dan het schema aan terwijl de migratiegeschiedenis nog kort is.
Genereer modellen en endpoints pas nadat je een paar end-to-end acties met het schema kunt testen (create, update, list, delete, plus één echte zakelijke actie). Codegeneratie is het snelst wanneer tabellen, sleutels en naamgeving stabiel genoeg zijn dat je niet alles de volgende dag hernoemt.
Een praktisch loopje dat herschrijvingen laag houdt:
Bepaal vroeg wat je in de database valideert versus in de API-laag. Leg permanente regels in de database (foreign keys, unique constraints, check constraints). Houd zachte regels in de API (feature flags, tijdelijke limieten en complexe cross-table logica die vaak verandert).
Als je Koder.ai gebruikt, is een verstandige aanpak om eerst overeenstemming te hebben over entiteiten en migraties in Planning Mode, en daarna je Go plus PostgreSQL-backend te genereren. Wanneer een wijziging misgaat, kunnen snapshots en rollback je helpen snel terug te keren naar een bekende goede versie terwijl je het schema-plan bijstelt.
Plan eerst het schema. Het legt een stabiel data-contract vast (tabellen, sleutels, constraints) zodat gegenereerde modellen en endpoints later niet constant hernoemd of herschreven hoeven te worden.
In de praktijk: schrijf je entiteiten, relaties en belangrijkste queries op, en vergrendel daarna constraints, indexes en migraties voordat je code genereert.
Schrijf 2–3 zinnen die beschrijven wat de app moet onthouden en wat gebruikers ermee moeten kunnen doen.
Vermeld daarna:
Dat geeft genoeg duidelijkheid om tabellen te ontwerpen zonder te veel te bouwen.
Begin met de zelfstandige naamwoorden die je steeds terugziet (user, project, invoice, task). Voeg bij elk één zin toe: wat het is en waarom het bestaat.
Als je het niet helder kunt beschrijven, krijg je waarschijnlijk vage tabellen zoals items of misc en zul je daar later spijt van hebben.
Houd je aan één consistente ID-strategie voor je hele schema.
Als je een mensvriendelijke identifier nodig hebt, voeg dan een aparte unieke kolom toe (bijv. project_code) in plaats van deze als primaire sleutel te gebruiken.
Bepaal per relatie wat gebruikers verwachten en wat bewaard moet blijven.
Gebruik deze vuistregels:
RESTRICT/NO ACTION wanneer het verwijderen van de ouder belangrijke records zou wissen (bijv. customers → orders)CASCADE wanneer child-rows zonder parent geen betekenis hebben (bijv. order → line items)Neem deze beslissing vroeg, want het beïnvloedt API-gedrag en randgevallen.
Leg permanente regels in de database zodat alle writers (API, scripts, imports, admin-tools) zich eraan houden.
Geef prioriteit aan:
Begin bij echte query-patronen, niet bij giswerk.
Schrijf 5–10 eenvoudige queries in gewone taal (filters + sort) en indexeer daarvoor:
status, user_id, created_atMaak een join-tabel met twee foreign keys en voeg een composite unique constraint toe.
Patroonvoorbeeld:
team_members(team_id, user_id, role, joined_at)UNIQUE (team_id, user_id) toe om duplicaten te voorkomenDat voorkomt subtiele bugs zoals “waarom verschijnt deze gebruiker twee keer?” en houdt queries schoon.
Standaardkeuzes:
timestamptz voor timestamps (minder tijdzone-verrassingen)numeric(12,2) of integer cents voor geld (vermijd floats)CHECK constraintsHoud types consistent tussen tabellen (zelfde concept = hetzelfde type) zodat joins en validaties voorspelbaar blijven.
Gebruik kleine, reviewbare migraties en vermijd grootschalige breaking changes in één stap.
Een veilige route:
Bepaal ook vooraf hoe je seed/reference data behandelt zodat elke omgeving overeenkomt.
PRIMARY KEY op elke tabelFOREIGN KEY voor elke “belongs to” kolomUNIQUE waar duplicaten schadelijk zijn (email, (team_id, user_id) in join-tabellen)CHECK voor eenvoudige regels (niet-negatieve bedragen, toegestane statussen)NOT NULL voor velden die essentieel zijn voor de betekenis van de rij(account_id, created_at))Vermijd alles te indexeren; elke index vertraagt INSERT en UPDATE.