Go + Postgres prestatieafstemming: een gericht API-playbook

Wat “traag” eruitziet voor Go API's op Postgres

AI-gegenereerde API's kunnen in vroege tests snel aanvoelen. Je raakt een endpoint een paar keer aan, de dataset is klein en requests komen één voor één binnen. Dan verschijnt echt verkeer: gemixte endpoints, piekbelastingen, koudere caches en meer rijen dan je had verwacht. Dezelfde code kan willekeurig traag gaan aanvoelen, ook al is er niets echt stuk.

Traagheid verschijnt meestal op een paar manieren: latency-spikes (de meeste requests zijn oké, sommige duren 5x tot 50x langer), timeouts (een klein percentage faalt) of CPU die hoog draait (Postgres-CPU door querywerk, of Go-CPU door JSON, goroutines, logging en retries).

Een veel voorkomend scenario is een list-endpoint met een flexibele zoekfilter dat een grote JSON-respons teruggeeft. In een testdatabase scant het een paar duizend rijen en is het snel klaar. In productie scant het een paar miljoen rijen, sorteert ze en past pas daarna een LIMIT toe. De API “werkt” nog, maar p95-latentie explodeert en een paar requests timen out tijdens pieken.

Om database-tragheid van app-tragheid te scheiden, houd het mentale model simpel.

Als de database traag is, brengt je Go-handler het grootste deel van de tijd door met wachten op de query. Je ziet mogelijk ook veel requests vast “in flight” terwijl Go-CPU normaal lijkt.

Als de app traag is, is de query snel klaar, maar gaat er tijd verloren na de query: grote response-objecten bouwen, JSON marshalen, extra queries per rij uitvoeren, of te veel werk per request doen. Go-CPU stijgt, geheugen stijgt en latentie groeit met de responsgrootte.

“Goed genoeg” performance voor de lancering is geen perfectie. Voor veel CRUD-endpoints streef je naar stabiele p95-latentie (niet alleen het gemiddelde), voorspelbaar gedrag bij pieken en geen timeouts bij je verwachte piek. Het doel is duidelijk: geen onverwachte trage requests wanneer data en verkeer groeien, en heldere signalen wanneer iets drift.

Baseline eerst: de paar cijfers die ertoe doen

Voordat je iets tuneert, bepaal wat “goed” betekent voor je API. Zonder baseline is het makkelijk om uren instellingen te veranderen en nog steeds niet te weten of je verbeterde of gewoon de bottleneck verplaatst hebt.

Drie cijfers vertellen meestal het grootste deel van het verhaal:

• p95 request-latentie (niet het gemiddelde)
• foutpercentage (HTTP 5xx, timeouts, geannuleerde requests)
• DB-tijd per request (hoe lang elk request op Postgres wacht)

p95 is de “slechte dag”-metric. Als p95 hoog is maar het gemiddelde goed, doet een kleine set requests te veel werk, wordt geblokkeerd op locks, of triggert het langzame plannen.

Maak trage queries vroeg zichtbaar. In Postgres schakel je slow query logging in met een lage drempel voor pre-launch tests (bijvoorbeeld 100–200 ms) en log je de volledige statement zodat je die in een SQL-client kunt plakken. Houd dit tijdelijk. Het loggen van elke trage query in productie wordt snel rumoerig.

Test vervolgens met realistische requests, niet alleen een enkele “hello world”-route. Een kleine set is genoeg als die overeenkomt met wat gebruikers daadwerkelijk doen: een list-call met filters en sortering, een detailpagina met een paar joins, een create of update met validatie, en een zoekachtige query met partial matches.

Als je endpoints genereert vanuit een specificatie (bijvoorbeeld met een vibe-coding tool zoals Koder.ai), draai dan steeds dezelfde handvol requests met consistente inputs. Dat maakt veranderingen zoals indexen, paginatie-aanpassingen en query-herschrijvingen makkelijker meetbaar.

Kies tenslotte een doel dat je hardop kunt zeggen. Voorbeeld: “De meeste requests blijven onder 200 ms p95 bij 50 gelijktijdige gebruikers, en fouten blijven onder 0,5%.” De exacte cijfers hangen van je product af, maar een duidelijk doel voorkomt eindeloos gesleutel.

Connection pooling die Postgres stabiel houdt

Een connection pool houdt een beperkt aantal open databaseverbindingen en hergebruikt ze. Zonder pool opent elke request mogelijk een nieuwe verbinding, en Postgres verspilt tijd en geheugen aan sessiebeheer in plaats van queries uit te voeren.

Het doel is Postgres bezig te houden met nuttig werk, niet met context-switching tussen te veel verbindingen. Dit is vaak de eerste zinvolle winst, zeker voor AI-gegenereerde API's die ongemerkt chattery endpoints worden.

Simpele startinstellingen

In Go stem je meestal max open connections, max idle connections en connection lifetime af. Een veilige start voor veel kleine API's is een klein veelvoud van je CPU-cores (vaak 5 tot 20 totale connecties), met een vergelijkbaar aantal idle connections, en verbindingen periodiek recyclen (bijvoorbeeld elke 30–60 minuten).

Als je meerdere API-instances draait, onthoud dan dat de pool vermenigvuldigt. Een pool van 20 connecties over 10 instances is 200 connecties naar Postgres, en zo lopen teams onverwacht tegen connection limits aan.

Hoe te zien of de pool het probleem is

Pool-problemen voelen anders dan trage SQL.

Als de pool te klein is, wachten requests voordat ze zelfs Postgres bereiken. Latentie spike-t, maar database-CPU en querytijden kunnen er normaal uitzien.

Als de pool te groot is, lijkt Postgres overbelast: veel actieve sessies, geheugenstress en ongelijke latentie tussen endpoints.

Een snelle manier om de twee te scheiden is je DB-calls in twee delen te timen: tijd besteed aan wachten op een verbinding versus tijd besteed aan het uitvoeren van de query. Als de meeste tijd “wachten” is, is de pool de bottleneck. Als de meeste tijd “in query” is, richt je op SQL en indexen.

Handige snelle checks:

• Log pool-statistieken (open, in-use, idle) en kijk of in-use vastzit op het max.
• Voeg een timeout toe op het verkrijgen van een verbinding zodat waits snel falen in staging.
• Monitor actieve connecties in Postgres en hoe dicht je bij max_connections zit.
• Bevestig dat elke request rows sluit en verbindingen snel vrijgeeft.
• Load test met hetzelfde aantal app-instances dat je van plan bent te draaien.

pgx pool vs database/sql

Als je pgxpool gebruikt, krijg je een Postgres-eerst pool met duidelijke statistieken en goede defaults voor Postgres-gedrag. Als je database/sql gebruikt, krijg je een standaardinterface die werkt over databases heen, maar moet je expliciet pool-instellingen en driver-gedrag instellen.

Een praktische regel: als je volledig op Postgres inzet en directe controle wilt, is pgxpool vaak eenvoudiger. Als je afhankelijk bent van libraries die database/sql verwachten, blijf dan daarbij, stel de pool expliciet in en meet waits.

Voorbeeld: een endpoint dat orders listeert doet er misschien 20 ms over, maar bij 100 gelijktijdige gebruikers springt het naar 2 s. Als logs 1.9 s tonen die wordt besteed aan wachten op een verbinding, helpt query-tuning niet totdat pool en totale Postgres-verbindingen juist geschaald zijn.

Queryplanning: snel lezen van EXPLAIN-output

Wanneer een endpoint traag aanvoelt, kijk wat Postgres daadwerkelijk doet. Een snelle blik op EXPLAIN wijst vaak binnen enkele minuten naar de oplossing.

Draai dit op de exacte SQL die je API verstuurt:

EXPLAIN (ANALYZE, BUFFERS)
SELECT id, status, created_at
FROM orders
WHERE user_id = $1 AND status = $2
ORDER BY created_at DESC
LIMIT 50;

Een paar regels zijn het belangrijkst. Kijk naar de top-node (wat Postgres koos) en de totalen onderaan (hoe lang het duurde). Vergelijk daarna geschatte vs daadwerkelijke rijen. Grote verschillen betekenen meestal dat de planner het fout had.

Wat de sleutelregels meestal betekenen

Als je Index Scan of Index Only Scan ziet, gebruikt Postgres een index, wat meestal goed is. Bitmap Heap Scan kan acceptabel zijn voor middelgrote matches. Seq Scan betekent dat de hele tabel is gelezen, wat alleen oké is wanneer de tabel klein is of bijna elke rij matcht.

Veelvoorkomende rode vlaggen:

• Seq Scan op een grote tabel
• Geschatte rijen vs daadwerkelijke rijen ver uit elkaar (bijv. 10 geschat vs 10.000 daadwerkelijk)
• Sort die het meeste van de tijd neemt (vaak gepaard met ORDER BY)
• “Filter:” die veel rijen verwijdert na een scan
• Hoge shared read blocks in BUFFERS (veel data gelezen)

Waarom plannen fout gaan (en makkelijke fixes)

Trage plannen komen meestal door een handvol patronen:

• Ontbrekende index voor je WHERE + ORDER BY patroon (bijv. (user_id, status, created_at))
• Niet-overeenkomende types (bijv. een UUID-kolom vergelijken met een text-parameter), wat indexgebruik kan blokkeren
• Functies in WHERE (bijv. WHERE lower(email) = $1), wat scans kan forceren tenzij je een bijpassende expression-index toevoegt

Als het plan vreemd uitziet en schattingen veraf zitten, zijn statistieken vaak verouderd. Draai ANALYZE (of laat autovacuum bijbenen) zodat Postgres actuele rij-aantallen en waardeverdelingen leert. Dit is belangrijk na grote imports of wanneer nieuwe endpoints veel schrijven.