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



