roadwave/docs/examples/dbml-example.md

Exemple DBML avec Kroki

Ce fichier montre comment utiliser DBML dans la documentation MkDocs avec le plugin Kroki.

Syntaxe de base

Pour créer un diagramme de base de données DBML, utilisez un bloc de code avec la balise kroki-dbml :

Exemple : Schéma utilisateurs et contenus

Table users {
  id uuid [primary key]
  email varchar(255) [not null, unique]
  username varchar(50) [not null, unique]
  password_hash varchar(255) [not null]
  created_at timestamp [not null, default: `now()`]
  updated_at timestamp [not null, default: `now()`]

  indexes {
    (email) [unique]
    (username) [unique]
  }
}

Table contents {
  id uuid [primary key]
  user_id uuid [not null, ref: > users.id]
  title varchar(255) [not null]
  description text
  audio_url varchar(512) [not null]
  location geography(POINT, 4326) [note: 'PostGIS geography type']
  duration_seconds int [not null]
  category content_category [not null]
  status content_status [not null, default: 'draft']
  created_at timestamp [not null, default: `now()`]
  published_at timestamp

  indexes {
    (user_id)
    (status)
    (location) [type: gist, note: 'Spatial index']
    (created_at)
  }
}

Table interest_gauges {
  id uuid [primary key]
  user_id uuid [not null, ref: > users.id]
  category varchar(50) [not null]
  score decimal(5,2) [not null, default: 0, note: 'Score 0-100']
  last_updated timestamp [not null, default: `now()`]

  indexes {
    (user_id, category) [unique]
  }
}

Enum content_category {
  "automobile"
  "travel"
  "music"
  "culture"
  "sport"
  "education"
}

Enum content_status {
  "draft"
  "published"
  "archived"
  "moderated"
}

Avantages de DBML

• ✅ Syntaxe claire : Plus lisible que Mermaid pour les schémas BDD
• ✅ Types PostGIS : Peut documenter les types spéciaux (geography, geometry)
• ✅ Index et contraintes : Documentation complète des index et contraintes
• ✅ Relations : Relations explicites entre tables
• ✅ Enums : Support natif des types énumérés
• ✅ Notes : Annotations directement dans le schéma

Utilisation dans votre projet

Pour documenter vos schémas de base de données dans RoadWave :

1. Créez vos fichiers .md dans docs/domains/<domain>/
2. Ajoutez des blocs kroki-dbml pour les schémas
3. Le rendu sera automatique lors de make docs-serve

Référence DBML

Consultez la documentation DBML officielle pour la syntaxe complète.