Tutoriel

Gardez un diagramme ER de votre base, à jour à chaque push

mcdview.dev · 6 min de lecture

Collez un schéma SQL, obtenez un diagramme entité-association interactif sur un lien stable. Branchez-le dans la CI et le diagramme se régénère à chaque changement de schéma : plus jamais de diagramme à dessiner à la main.

Diagramme ER de la base Chinook — Le schéma Chinook en une page explorable. Les liens s'ancrent au bord des tables, les relations se lisent d'un coup d'œil.

Le problème des diagrammes dessinés à la main

Un diagramme de base est périmé dès qu'on ajoute une colonne. On le dessine une fois pour la doc d'accueil, et trois migrations plus tard il ment. Le tenir à jour à la main, personne ne se porte volontaire.

mcdview prend le chemin inverse : le fichier de schéma est la source de vérité. Pointez l'outil sur votre schema.sql et il génère le diagramme : une page HTML autonome, sans runtime, sans connexion à la base.

Ce que fait le diagramme

Ce n'est pas une image figée. Chaque table et chaque relation est interactive :

Isoler une table dans mcdview — Cliquez une table et tout le reste s'estompe, pour vous concentrer sur elle et ses relations.

Une table isolée — Cliquez une table pour l'isoler avec ses relations.

Tables centrales — Repérez les tables centrales dont tout dépend.

Cycles de dépendances — Faites ressortir les cycles de dépendances.

Thème sombre — Clair ou sombre, en un clic.

Vous pouvez exporter le même modèle en SVG, en erDiagram Mermaid, ou en dictionnaire de données Markdown, pratique pour glisser le diagramme dans un dépôt ou un wiki.

Le meilleur

Mettez-le en CI : le diagramme se met à jour tout seul

L'idée : votre schéma vit dans le dépôt. À chaque push qui le touche, la CI envoie le fichier à mcdview.dev, qui régénère le diagramme derrière le même lien stable. On garde ce lien en favori une fois ; il est toujours à jour.

GitHub Actions

Ajoutez l'action publiée. À un push sur schema.sql, elle met à jour votre diagramme :

name: er-diagram
on:
  push:
    branches: [main]
    paths: [db/schema.sql]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Gheop/mcdview-action@v1
        with:
          file: db/schema.sql
          key: ${{ secrets.MCDVIEW_KEY }}   # met à jour le même lien
          fail-on: ok                     # échoue si le modèle ne parse pas

Sous Rails ? Pointez paths et file sur db/schema.rb (ou un db/structure.sql PostgreSQL) : mcdview les lit nativement, même flux, sans étape de conversion. L'historique git de ce fichier devient alors le time-lapse de votre schéma.

GitLab CI

La même chose, en composant du CI/CD Catalog :

include:
  - component: gitlab.com/Gheop/mcdview/mcdview@~latest
    inputs:
      file: db/schema.sql
      key: $MCDVIEW_KEY
      fail-on: ok

zéro clé Pas envie de gérer un secret ? Utilisez oidc: true au lieu d'une clé. Le pipeline prouve sa propre identité à mcdview.dev via un jeton signé, et le diagramme est lié à ce projet : rien à stocker.

include:
  - component: gitlab.com/Gheop/mcdview/mcdview@~latest
    inputs:
      file: db/schema.sql
      oidc: true

Un badge pour votre README

Le job renvoie un badge cliquable. Collez-le dans votre README, il pointe droit vers le diagramme vivant :

[![mcdview](https://mcdview.dev/badge/<token>.svg)](https://mcdview.dev/v/<token>)

En voici un en vrai, cliquez dessus : (il suit la démo Chinook).

Le même run peut aussi récupérer la source Mermaid, un SVG, un PNG, un QR code et une fiche de faits en texte dans votre dépôt. Choisissez avec fetch: mermaid,svg,badge,facts.

Bonus : chaque push est une version

Comme la CI pousse à chaque changement, votre diagramme se constitue un historique complet, gratuitement. Comparez deux versions pour voir ce qu'une migration a fait, ou rejouez le tout en time-lapse. Plus de détails dans lire l'histoire de votre schéma.

Diff entre deux versions du schéma : tables ajoutées en vert.

Ce qui le distingue

Trois choses qu'on réunit rarement dans un seul outil :

Un fichier, sans compte. Collez un schéma, obtenez un lien. La page est un seul fichier HTML statique : rien ne s'exécute à l'ouverture, aucune base n'est contactée, aucune inscription.
Il vit dans la CI. Une action GitHub ou un composant GitLab régénère le diagramme à chaque push, derrière le même lien stable, avec un badge README. Zéro clé via OIDC.
Il garde la mémoire. Chaque push est une version : parcourez le time-lapse, comparez deux états, voyez ce qu'une migration a changé.

Et par-dessus : isoler une table, repérer les tables centrales et les cycles, basculer clair/sombre, exporter en SVG, Mermaid ou dictionnaire de données Markdown.

Essayez en 30 secondes

Sans inscription. Collez un schéma, obtenez un lien. Puis branchez l'étape CI ci-dessus et oubliez-le.

Ouvrir mcdview.dev →

Prend en charge PostgreSQL, MySQL, dumps SQLite, un structure.sql PostgreSQL, un schema.rb Rails, pgModeler .dbm, DBML et Prisma, lus nativement. La page générée est du HTML statique, sûre à héberger, rien ne s'exécute à l'affichage.