Torna a tutte le guide
Progettazione di database··3 min di lettura

Documentazione del database: spiegare lo schema SQL con gli ERD

Documenta gli schemi di database con ERD, esempi SQL, note sulle relazioni e contesto di migrazione in modo che i team possano comprendere i modelli di dati più rapidamente.

Un diagramma cliente-ordine accanto a note che spiegano la chiave esterna e la regola aziendale
In questa guida
  1. Perché la documentazione del database fallisce
  2. Cosa includere nella documentazione dello schema
  3. Esempio di blocco di documentazione
  4. Un flusso di lavoro pratico per la documentazione
  5. Riferimenti e letture aggiuntive

Gli esempi SQL utilizzano PostgreSQL a meno che non sia specificato un altro dialetto. Brevi frammenti presuppongono che le tabelle a cui fanno riferimento esistano già. Convalida il DDL nel tuo database di destinazione prima di applicarlo.

Perché la documentazione del database fallisce

La documentazione del database spesso diventa obsoleta perché viene scritta separatamente dallo schema. Qualcuno crea un diagramma durante il primo sprint di progettazione, il database cambia per sei mesi e la documentazione diventa silenziosamente fuorviante.

Un approccio migliore è mantenere la documentazione vicina al codice sorgente SQL. Genera diagrammi dal DDL, aggiungi brevi spiegazioni per tabelle e relazioni e aggiorna la documentazione ogni volta che lo schema cambia.

Schema SQL, diagramma ERD, note sulle relazioni e contesto di migrazione combinati nella documentazione
Una solida documentazione del database abbina la sorgente SQL a un ERD e a brevi note sulle relazioni, in modo che la documentazione rimanga pratica.

Cosa includere nella documentazione dello schema

Una documentazione del database utile risponde alle domande che gli sviluppatori pongono effettivamente durante la creazione di funzionalità e il debugging dei Dati di produzione.

  • Un Editor ERD. Mostra tabelle, chiavi primarie, chiavi esterne e i percorsi delle relazioni principali.
  • Note sullo scopo della tabella. Spiega perché esiste ogni tabella principale e quale funzionalità la possiede.
  • Regole di relazione. Evidenzia cardinalità, relazioni facoltative e azioni a cascata.
  • Vincoli importanti. Documenta chiavi uniche, controlli, valori di enumerazione e regole di business imposte da SQL.
  • Contesto di migrazione. Collega le modifiche dello schema alla funzionalità, alla correzione di bug o al motivo operativo sottostante.

Esempio di blocco di documentazione

Una voce di documentazione leggera può associare SQL a note in linguaggio semplice:

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()
);

Le note di documentazione potrebbero indicare: un account ha molte fatture, le fatture hanno molti record di pagamento e le righe di pagamento vengono eliminate se viene eliminata una fattura di test. Nei sistemi di produzione con requisiti di audit, potresti sostituire le eliminazioni a cascata con eliminazioni limitate e record di archivio.

Un flusso di lavoro pratico per la documentazione

Ecco un flusso di lavoro che mantiene la documentazione utile senza trasformarla in un lavoro a tempo pieno.

  • Inizia con lo schema SQL e genera un ERD nel Editor di Erd Go.
  • Esporta il diagramma o accedi, Salvalo e condividi un link pubblico di sola lettura quando lo schema è adatto all'accesso pubblico. Usa le esportazioni di immagini per la documentazione privata.
  • Aggiungi un breve paragrafo per ogni importante cluster di tabelle: auth, billing, orders, content, audit o reporting.
  • Rigenera l'ERD dal codice SQL aggiornato durante le migrazioni in modo che la documentazione rifletta ciò che è cambiato.
  • Mantieni gli esempi di sintassi sincronizzati con il Documentazione DDL di Erd Go in modo che i futuri collaboratori possano riprodurre il diagramma.

L'obiettivo non è un'enciclopedia perfetta. L'obiettivo è una mappa vivente che aiuti le persone a comprendere rapidamente il database e a fidarsi di ciò che stanno leggendo.

Riferimenti e letture aggiuntive

Altri post