SaaS-architectuur
Factuurnummers per klant in PostgreSQL, zonder gaten
Sequence, max()+1, SERIALIZABLE of een tellerrij: vijf manieren om facturen per klant te nummeren, nagemeten in PostgreSQL 17 op dubbelen, gaten en snelheid.
Now-Next bouwt SaaS-producten en neemt bestaande over. Wat we bouwen
In een multi-tenant SaaS-product dat facturen verstuurt, is elke klant een bedrijf met zijn eigen factuurreeks. De facturen van klant A lopen 1, 2, 3, en die van klant B ook, hoeveel facturen de andere klanten er ook tussendoor maken. Dat klinkt als een kleine eis, en het is precies de plek waar wat PostgreSQL als eerste aanbiedt — een sequence, of max() + 1 — het verkeerde gereedschap is.
We hebben vijf aanpakken onder dezelfde belasting gemeten: acht gelijktijdige sessies, vijftien seconden lang met pgbench, in PostgreSQL 17.10, en daarna geteld hoeveel nummers dubbel waren uitgegeven en hoeveel er waren overgeslagen.
Hoe nummer je facturen per klant in PostgreSQL?
Met een tellerrij per klant, opgehoogd met UPDATE … RETURNING in dezelfde transactie die de factuur schrijft, en zo laat mogelijk in die transactie. In onze meting gaf dat nul dubbele en nul ontbrekende nummers over 1.000 klanten, ook toen één op de tien transacties werd teruggedraaid. Een sequence sloeg onder dezelfde terugdraaiingen 17.973 nummers over, en max(number) + 1 gaf 140.977 nummers dubbel uit.
Wat vraagt de wet?
De Belastingdienst zegt het zo: “Gebruik opeenvolgende nummers voor uw facturen, met 1 of meer reeksen. Elk factuurnummer mag maar 1 keer voorkomen.” De Europese btw-richtlijn noemt “a sequential number, based on one or more series, which uniquely identifies the invoice” als verplicht gegeven op een factuur (Richtlijn 2006/112/EG, artikel 226, punt 2).
Dus twee dingen: uniek, en opeenvolgend binnen een reeks. Geen van beide teksten gebruikt het woord “zonder gaten”, en of een enkel gat acceptabel is, is een vraag voor de accountant en niet voor de database. Wat de database beslist, is of je het kunt beloven. En “1 of meer reeksen” betekent dat een reeks per jaar, of per klant per jaar, mag — de teller hieronder neemt een reekskolom op zonder verdere wijziging.
Vijf aanpakken, nagemeten
Acht sessies, vijftien seconden, allemaal facturen voor dezelfde klant tenzij anders vermeld.
| Aanpak | Facturen per seconde | Dubbel uitgegeven | Overgeslagen |
|---|---|---|---|
| Eén sequence (identity-kolom), 10% teruggedraaid | 12.131 | 0 | 17.973 van 181.937 |
max(number) + 1, standaardisolatie | 10.769 | 140.977 van 161.479 | — |
max(number) + 1, SERIALIZABLE, tot 20 herhalingen | 1.475 | 0 | 0, maar 26,6% van de transacties mislukte |
| Tellerrij, één klant | 2.143 | 0 | 0 |
| Tellerrij, één klant, 10% teruggedraaid | 2.312 | 0 | 0 |
| Tellerrij, verdeeld over 1.000 klanten | 10.787 | 0 | 0 in elk van de 1.000 reeksen |
Waarom is een sequence niet genoeg?
Omdat hij daar bewust niet voor gebouwd is. De PostgreSQL-documentatie zegt het letterlijk: “the value obtained by nextval is not reclaimed for re-use if the calling transaction later aborts”, en daarom “PostgreSQL sequence objects cannot be used to obtain ‘gapless’ sequences”. Met één op de tien transacties teruggedraaid, werden 17.973 van de 181.937 nummers nooit gebruikt — vrijwel precies de tien procent die terugging.
En dat is nog het kleinere probleem. Eén sequence is één reeks voor alle klanten samen: klant A krijgt 1, 7, 12 en klant B krijgt 2, 3, 8. Dat is helemaal geen reeks per bedrijf. Een sequence per klant lost dat op en brengt het probleem van objecten per klant terug — duizend klanten, duizend sequences om aan te maken, te migreren en te back-uppen. Dat is dezelfde weg waarop schema per klant vastloopt.
Waarom geeft max() + 1 dubbele nummers?
Omdat twee transacties die tegelijk beginnen onder het standaardisolatieniveau hetzelfde hoogste nummer zien, er allebei één bij optellen en het allebei wegschrijven. Bij acht sessies op één klant gebeurde dat bij 87% van alle facturen: 161.479 rijen, maar 20.502 verschillende nummers.
Een unieke beperking op (tenant_id, number) maakt van die dubbelen fouten, en dat is beter — er wordt niets verkeerds opgeslagen — maar dan is het je gebruiker die ziet dat een factuur niet wil opslaan. Die beperking hoort er sowieso; alleen lost hij de nummering niet op.
Is SERIALIZABLE het antwoord?
Het is correct: geen dubbelen, geen gaten. Maar bij acht sessies op één klant moest 76% van de transacties opnieuw, en 26,6% mislukte na twintig pogingen nog steeds, bij 1.475 facturen per seconde. PostgreSQL doet wat het isolatieniveau belooft — hij breekt een van twee botsende transacties af — en het opnieuw proberen wordt het werk van je applicatie.
Wat kost nummeren zonder gaten?
Elke factuur van één klant wacht tot de vorige is vastgelegd, want ze werken allemaal dezelfde tellerrij bij. Dat is het hele mechanisme, en je ziet het in de cijfers: één sessie haalde 1.778 facturen per seconde, acht sessies 2.143. Meer gelijktijdigheid voor één klant helpt nauwelijks. Verdeeld over 1.000 klanten haalden dezelfde acht sessies er 10.787 per seconde, omdat ze zelden op dezelfde rij wachten.
Waar die kosten echt van afhangen, is hoe lang je de rij vasthoudt. We voegden 10 ms ander werk toe aan de transactie — het soort dingen dat het opslaan van een factuur doet: een pdf, een aanroep naar een andere dienst, nog een paar query’s.
| 10 ms werk… | Facturen per seconde (één klant, acht sessies) |
|---|---|
| ná het nummer nemen | 94 |
| vóór het nummer nemen | 746 |
Wie het nummer eerst neemt, houdt de tellerrij de hele transactie vast, dus wacht elke andere sessie voor die klant de volle 10 ms. Met één sessie in plaats van acht was het 93,5 per seconde: acht sessies leverden niets op. Wie het nummer als laatste neemt, houdt de rij alleen voor de laatste opdracht vast. Hetzelfde werk, dezelfde garantie, acht keer zoveel doorvoer.
Het patroon dat we gebruiken
Een tabel met één rij per klant (en per reeks, als je per jaar nummert), aangemaakt samen met de klant:
create table invoice_counters (
tenant_id uuid primary key references tenants(id),
last_number int not null default 0
);
Het volgende nummer nemen en de factuur schrijven in één opdracht, aan het eind van de transactie:
with n as (
update invoice_counters
set last_number = last_number + 1
where tenant_id = $1
returning tenant_id, last_number
)
insert into invoices (tenant_id, number, …)
select tenant_id, last_number, … from n;
commit;
Gaat de transactie terug, dan gaat de teller mee terug — daarom liet de test met 10% terugdraaien geen gaten achter. En in de praktijk is er een eenvoudiger manier om de vergrendeling kort te houden: een conceptfactuur heeft nog geen nummer. Geef hem een nummer als hij definitief wordt, in een eigen korte transactie, en al het trage werk gebeurt terwijl er niets is om op te wachten.
Met row-level security krijgt invoice_counters hetzelfde beleid als elke andere klanttabel; een teller is ook klantdata.
Hoe controleer je dat je nummers geen gaten hebben?
Twee query’s. De eerste geeft elk gat binnen de reeks van elke klant; de tweede elk nummer dat vaker dan één keer voorkomt. We toetsten ze door bij één klant de nummers 3 en 4 weg te halen, bij een tweede nummer 10, en bij een derde een tweede nummer 5 toe te voegen: ze gaven precies die drie bevindingen terug.
-- gaten binnen de reeks van elke klant
select tenant_id, number + 1 as gap_starts_at, next_number - 1 as gap_ends_at
from (
select tenant_id, number,
lead(number) over (partition by tenant_id order by number) as next_number
from invoices
) s
where next_number > number + 1
order by tenant_id, number;
-- nummers die vaker dan één keer zijn uitgegeven
select tenant_id, number, count(*)
from invoices
group by tenant_id, number
having count(*) > 1;
De eerste query ziet geen gat vóór de eerste factuur; begint een reeks bij 1, controleer dan ook min(number) per klant. Nummer je per jaar, zet de reekskolom dan in de partition by en de group by.
Wat we niet hebben gemeten
Crashes, replicatie, en meer dan acht sessies. Een crash valt onder hetzelfde argument als terugdraaien — de teller en de factuur worden samen vastgelegd of geen van beide — maar we hebben de stekker er niet uitgetrokken om het te bewijzen. Alle cijfers komen van één machine met standaardinstellingen; lees ze dus als verhoudingen. Die verhoudingen zijn duidelijk genoeg: max() + 1 is onder elke belasting fout, een sequence is snel en heeft bewust gaten, en een tellerrij is correct en kost precies zoveel als je de rest van de transactie laat wachten.
Bronnen: de Belastingdienst-pagina factuureisen; Richtlijn 2006/112/EG, artikel 226, op EUR-Lex (geconsolideerde versie van 14 april 2025); de PostgreSQL 17-documentatie over sequencefuncties. Alles gelezen op 28 september 2026. De metingen zijn van onszelf, in PostgreSQL 17.10, op 28 september 2026.