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.
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.



