23fe67470b
Remplace les diagrammes Mermaid par DBML (via kroki-dbml) pour une meilleure expressivité des schémas de base de données : - Ajout support notes, contraintes et indexes détaillés - Migration de tous les schémas d'entités partagées - Ajout fichier exemple dbml-example.md - Configuration plugin mkdocs-kroki pour rendu DBML
96 lines
2.4 KiB
Markdown
96 lines
2.4 KiB
Markdown
# 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
|
|
|
|
```kroki-dbml
|
|
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](https://dbml.dbdiagram.io/docs/) pour la syntaxe complète.
|