SQL-exempel använder PostgreSQL såvida inte en annan dialekt anges. Korta kodsnuttar förutsätter att deras refererade tabeller redan existerar. Validera DDL i din måldatabas innan du tillämpar den.
Varför databasdokumentation misslyckas
Databasdokumentation blir ofta inaktuell eftersom den skrivs separat från schemat. Någon skapar ett diagram under den första designsprinten, databasen ändras under sex månader och dokumentationen blir tyst vilseledande.
Ett bättre tillvägagångssätt är att hålla dokumentationen nära SQL-källan. Generera diagram från DDL, lägg till korta förklaringar för tabeller och relationer, och uppdatera dokumentationen när schemat ändras.
Vad som ska inkluderas i schemadokumentationen
Användbar databasdokumentation besvarar de frågor utvecklare faktiskt ställer när de bygger funktioner och felsöker produktionsdata.
- Ett ERD. Visa tabeller, primärnycklar, främmande nycklar och de huvudsakliga relationsvägarna.
- Anteckningar om tabellens syfte. Förklara varför varje huvudtabell finns och vilken funktion som äger den.
- Relationsregler. Lyft fram kardinalitet, valfria relationer och kaskadåtgärder.
- Viktiga begränsningar. Dokumentera unika nycklar, kontroller, enum-värden och affärsregler som upprätthålls av SQL.
- Migreringskontext. Koppla schemaändringar till funktionen, buggfixen eller den operativa orsaken bakom dem.
Exempel på dokumentationsblock
En lättviktsdokumentationspost kan kombinera SQL med anteckningar i klartext:
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()
);Dokumentationsanteckningar kan säga: ett konto har många fakturor, fakturor har många betalningsposter, och betalningsrader tas bort om en testfaktura tas bort. I produktionssystem med granskningskrav kan du ersätta kaskad-borttagningar med begränsade borttagningar och arkiverade poster.
Ett praktiskt dokumentationsarbetsflöde
Här är ett arbetsflöde som håller dokument användbara utan att göra dokumentation till ett heltidsjobb.
- Börja med SQL-schemat och generera ett ERD i Erd Go-redigerare.
- Exportera diagrammet eller logga in, spara det och dela en skrivskyddad offentlig länk när schemat är lämpligt för allmän åtkomst. Använd bildexport för privat dokumentation.
- Lägg till ett kort stycke för varje viktigt tabellkluster: auth, billing, orders, content, audit eller reporting.
- Återskapa ERD från uppdaterad SQL under migreringar så att dokumentationen återspeglar vad som ändrats.
- Håll syntaxexempel synkroniserade med Erd Go DDL-dokumentation så att framtida bidragsgivare kan återskapa diagrammet.
Målet är inte ett perfekt uppslagsverk. Målet är en levande karta som hjälper människor att förstå databasen snabbt och lita på det de läser.



