Retour à tous les guides
Conception de bases de données··3 min de lecture

Documentation de base de données : expliquer votre schéma SQL avec des ERD

Documentez les schémas de base de données avec des ERD, des exemples SQL, des notes de relation et un contexte de migration afin que les équipes puissent comprendre les modèles de données plus rapidement.

Un diagramme client-commande aux côtés de notes expliquant la clé étrangère et la règle métier
Dans ce guide
  1. Pourquoi la documentation de base de données échoue
  2. Que faut-il inclure dans la documentation du schéma ?
  3. Exemple de bloc de documentation
  4. Un flux de travail de documentation pratique
  5. Références et lecture complémentaire

Les exemples SQL utilisent PostgreSQL à moins qu'un autre dialecte ne soit nommé. Les extraits courts supposent que leurs tables référencées existent déjà. Validez le DDL dans votre base de données cible avant de l'appliquer.

Pourquoi la documentation de base de données échoue

La documentation des bases de données devient souvent obsolète car elle est rédigée séparément du schéma. Quelqu'un crée un diagramme lors du premier sprint de conception, la base de données change pendant six mois et la documentation devient discrètement trompeuse.

Une meilleure approche consiste à conserver la documentation près de la source SQL. Générez des diagrammes à partir du DDL, ajoutez de brèves explications pour les tables et les relations, et mettez à jour la documentation chaque fois que le schéma change.

Schéma SQL, diagramme Constructeur ERD, notes de relation et contexte de migration combinés dans la documentation
Une documentation de base de données solide associe la source SQL à un ERD et de courtes notes de relation, afin que la documentation reste pratique.

Que faut-il inclure dans la documentation du schéma ?

Une documentation de base de données utile répond aux questions que les développeurs se posent réellement lors de la création de fonctionnalités et du débogage des données de production.

  • Un ERD. Afficher les tables, les clés primaires, les clés étrangères et les principaux chemins de relations.
  • Notes sur l'objectif de la table. Expliquez pourquoi chaque table principale existe et quelle fonctionnalité la possède.
  • Règles de relation. Mettez en valeur la cardinalité, les relations optionnelles et les actions en cascade.
  • Contraintes importantes. Documentez les clés uniques, les vérifications, les valeurs d'énumération et les règles métier appliquées par SQL.
  • Contexte de migration. Associer les modifications de schéma à la fonctionnalité, à la correction de bogue ou à la raison opérationnelle qui les sous-tend.

Exemple de bloc de documentation

Une entrée de documentation légère peut associer du SQL à des notes en langage clair :

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

Les notes de documentation peuvent indiquer : un compte a plusieurs factures, les factures ont plusieurs enregistrements de paiement, et les lignes de paiement sont supprimées si une facture de test est supprimée. Dans les systèmes de production soumis à des exigences d'audit, vous pouvez remplacer les suppressions en cascade par des suppressions restreintes et des enregistrements d'archives.

Un flux de travail de documentation pratique

Voici un flux de travail qui maintient l'utilité de la documentation sans transformer celle-ci en un emploi à temps plein.

  • Commencez par le schéma SQL et générez un ERD dans le Éditeur Erd Go.
  • Exportez le diagramme ou connectez-vous, enregistrez-le et partagez un lien public en lecture seule lorsque le schéma se prête à un accès public. Utilisez les exportations d'images pour la documentation privée.
  • Ajoutez un court paragraphe pour chaque groupe de tables important : authentification, facturation, commandes, contenu, audit ou rapports.
  • Régénérez le Constructeur ERD à partir du SQL mis à jour lors des migrations afin que la documentation reflète ce qui a changé.
  • Maintenez les exemples de syntaxe synchronisés avec Documentation DDL d'Erd Go pour que les futurs contributeurs puissent reproduire le diagramme.

L'objectif n'est pas d'obtenir une encyclopédie parfaite. L'objectif est de créer une carte vivante qui aide les gens à comprendre rapidement la base de données et à faire confiance à ce qu'ils lisent.

Références et lecture complémentaire

Plus d'articles