Tillbaka till alla guider
Databasdesign··3 min läsning

Databasdokumentation: förklara ditt SQL-schema med ERD

Dokumentera databasscheman med ERD:er, SQL-exempel, relationsanteckningar och migreringskontext så att team kan förstå datamodeller snabbare.

Ett kund-till-order-diagram bredvid anteckningar som förklarar den främmande nyckeln och affärsregeln
I den här guiden
  1. Varför databasdokumentation misslyckas
  2. Vad som ska inkluderas i schemadokumentationen
  3. Exempel på dokumentationsblock
  4. Ett praktiskt dokumentationsarbetsflöde
  5. Referenser och vidare läsning

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.

SQL-schema, Klassdiagram, relationsanteckningar och migreringskontext kombinerade i dokumentation
Stark databasdokumentation kopplar SQL-källan med ett ERD och korta relationsanteckningar, så att dokumenten förblir praktiska.

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.

Referenser och vidare läsning

Fler inlägg