Terug naar alle handleidingen
Databaseontwerp··3 min leestijd

Databasedocumentatie: je SQL-schema uitleggen met ERD’s

Documenteer databaseschema's met ERD's, SQL-voorbeelden, relatieopmerkingen en migratiecontext, zodat teams datamodellen sneller begrijpen.

Een klant-naar-bestellingdiagram naast aantekeningen die de vreemde sleutel en bedrijfsregel uitleggen
In deze gids
  1. Waarom databasedocumentatie mislukt
  2. Wat op te nemen in schema-documentatie
  3. Voorbeeld documentatieblok
  4. Een praktische documentatieworkflow
  5. Referenties en verdere lezing

SQL-voorbeelden gebruiken PostgreSQL, tenzij een andere dialect wordt genoemd. Korte fragmenten gaan ervan uit dat hun verwijderde tabellen al bestaan. Valideer DDL in uw doeldatabase voordat u deze toepast.

Waarom databasedocumentatie mislukt

Databasedocumentatie verouderd vaak omdat deze los van het schema wordt geschreven. Iemand maakt een diagram tijdens de eerste ontwerpsprint, de database verandert gedurende zes maanden en de documentatie wordt stilletjes misleidend.

Een betere benadering is om documentatie dicht bij de SQL-bron te houden. Genereer diagrammen uit DDL, voeg korte uitleg toe voor tabellen en relaties, en werk de documentatie bij wanneer het schema wijzigt.

SQL-schema, ERD-diagram, relatienotities en migratiecontext gecombineerd in documentatie
Sterke database documentatie koppelt de SQL-bron aan een ERD en korte relatie-notities, zodat de documenten praktisch blijven.

Wat op te nemen in schema-documentatie

Nuttige databasedocumentatie beantwoordt de vragen die ontwikkelaars daadwerkelijk stellen bij het bouwen van functies en het debuggen van productgegevens.

  • Een ERD. Toon tabellen, primaire sleutels, vreemde sleutels en de belangrijkste relatiepaden.
  • Notities over het doel van de tabel. Leg uit waarom elke belangrijke tabel bestaat en welke functie eigenaar is.
  • Relatieregels. Benoem cardinaliteit, optionele relaties en cascadende acties.
  • Belangrijke beperkingen. Documenteer unieke sleutels, controles, enum-waarden en bedrijfsregels die door SQL worden afgedwongen.
  • Migratiecontext. Koppel schemawijzigingen aan de functie, bugoplossing of operationele reden erachter.

Voorbeeld documentatieblok

Een lichtgewicht documentatie-item kan SQL koppelen aan notities in klare taal:

CREATE TABLE accounts (
    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    name TEXT NOT NULL
);

CREATE TABLE invoices (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    account_id  BIGINT NOT NULL REFERENCES accounts (id),
    status      VARCHAR(30) NOT NULL DEFAULT 'draft',
    total       NUMERIC(12, 2) NOT NULL CHECK (total >= 0),
    due_date    DATE,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE invoice_payments (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    invoice_id  BIGINT NOT NULL REFERENCES invoices (id) ON DELETE CASCADE,
    amount      NUMERIC(12, 2) NOT NULL CHECK (amount > 0),
    paid_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);

Documentatienotities kunnen luiden: een account heeft vele facturen, facturen hebben vele betalingsrecords en betalingsrijen worden verwijderd als een testfactuur wordt verwijderd. In productiesystemen met auditvereisten kunt u cascaderend verwijderen vervangen door beperkt verwijderen en archiefrecords.

Een praktische documentatieworkflow

Hier is een workflow die documenten nuttig houdt zonder van documentatie een fulltime baan te maken.

  • Begin met het SQL-schema en genereer een ERD in de Erd Go-editor.
  • Exporteer het diagram of meld u aan, sla het op en deel een openbare alleen-lezen link wanneer het schema geschikt is voor openbare toegang. Gebruik afbeeldingsexports voor private documentatie.
  • Voeg één korte alinea toe voor elk belangrijk tabelcluster: auth, billing, orders, content, audit of reporting.
  • Genereer de ERD opnieuw uit bijgewerkte SQL tijdens migraties, zodat de documentatie weerspiegelt wat er is gewijzigd.
  • Houd syntaxisvoorbeelden synchroon met de Erd Go DDL-documentatie zodat toekomstige bijdragers het diagram kunnen reproduceren.

Het doel is geen perfecte encyclopedie. Het doel is een levende kaart die mensen helpt de database snel te begrijpen en te vertrouwen wat ze lezen.

Referenties en verdere lezing

Meer berichten