SQL COMMENT et SQL COMMENT ON

Le langage SQL propose deux façons de documenter le code et le schéma :

• des commentaires dans les scripts (SQL, PHP, etc.) pour expliquer les requêtes ;
• la commande SQL COMMENT ON (ou équivalent) pour documenter durablement les objets de la base (tables, colonnes, index).
  Les commentaires sur les tables peuvent aussi être ajoutés via une commande comme ALTER TABLE.

Syntaxe pour les commentaires sur une ligne et multi-lignes

-- Ceci est un commentaire sur une ligne

/* Ceci
est un commentaire
sur plusieurs lignes
*/

Format ligne unique —

Les deux tirets -- indiquent que tout ce qui suit, jusqu’au retour à la ligne, est ignoré par le moteur SQL. On les utilise pour expliquer rapidement une condition, un calcul ou l’objectif d’une requête.

SELECT nom_produit, prix -- Filtre prix catalogue actuel uniquement
FROM catalogue 
WHERE prix > 0 AND actif = 1;

-- Rapport mensuel chiffre d'affaires par région géographique
SELECT region, SUM(montant_ht) 
FROM ventes 
WHERE date_vente >= '2026-01-01'
GROUP BY region;

Format en bloc multi-lignes /* */

Les délimiteurs /* et */ encadrent un bloc ignoré par le moteur SQL. Ce format sert à documenter une partie de requête plus longue ou une section de script.

SELECT nom, ville 
/* Limitation géographique 
France métropolitaine uniquement */ 
FROM clients 
WHERE pays IN ('France') /* Exclut DOM TOM */
  AND statut = 'premium';

Commandes SQL COMMENT ON

La commande COMMENT ON (ou ses équivalents selon le SGBD) permet d’enregistrer des descriptions directement dans le catalogue système de la base. Ces textes sont associés aux tables, colonnes ou index et s’affichent dans les outils d’administration (pgAdmin, phpMyAdmin, etc.).

COMMENT ON TABLE

Ce commentaire indique le rôle de la table et donne un ordre de grandeur du volume de données.

COMMENT ON TABLE commandes IS 
'Commandes clients validées depuis janvier 2025. 
2,3 millions d'enregistrements au 22/01/2026. 
Relie clients, produits, paiements, transporteurs.';

COMMENT ON COLUMN

On précise ici le sens métier de la colonne, les cas particuliers (NULL) et les contraintes implicites.

COMMENT ON COLUMN produits.stock IS 
'Quantité physique disponible entrepôt principal. 
NULL autorisé pour produits digitaux/services. 
Minimum 0 unités physiques.';

Requête SQL avec COMMENT ON INDEX

Ce commentaire explique pourquoi l’index existe et quelles requêtes en dépendent.

COMMENT ON INDEX idx_ventes_client_date IS 
'Optimise SELECT WHERE client_id AND date_vente 
utilisé 12 000 fois/jour tableau bord client.';

Compatibilité entre les systèmes SGBDR

PostgreSQL

PostgreSQL implémente COMMENT ON pour de nombreux objets (tables, colonnes, index, vues, etc.). Les outils comme psql et pgAdmin affichent ces commentaires automatiquement. Mettre IS NULL permet de supprimer un commentaire devenu obsolète.

COMMENT ON COLUMN clients.statut_commercial IS 
'Enum: "prospect", "client", "premium", "vip" depuis refonte 2025.';

MySQL

MySQL n’utilise pas COMMENT ON, mais des clauses COMMENT dans les définitions d’objets et la commande SHOW CREATE TABLE ou les outils graphiques permettent de consulter ces métadonnées.

CREATE TABLE utilisateurs (
    id INT AUTO_INCREMENT PRIMARY KEY COMMENT 'Identifiant système unique',
    actif TINYINT(1) DEFAULT 1 COMMENT '1=actif, 0=archivé'
) COMMENT='Utilisateurs actifs plateforme e-commerce';

SQL Server

SQL Server stocke les descriptions dans des “extended properties” via des procédures système comme sp_addextendedproperty. Les valeurs peuvent ensuite être lues dans sys.extended_properties.

EXEC sys.sp_addextendedproperty 
@name=N'MS_Description', 
@value=N'Prix unitaire hors taxes en euros',
@level0type=N'SCHEMA',@level0name=N'dbo', 
@level1type=N'TABLE',@level1name=N'produits', 
@level2type=N'COLUMN',@level2name=N'prix_ht';

Bonnes pratiques de documentation SQL

• Utiliser les commentaires (-- et /* */) pour expliquer les requêtes complexes, les règles métier et les cas particuliers.
• Utiliser COMMENT ON (ou COMMENT / extended properties selon le SGBD) pour documenter durablement :
  • les tables (rôle métier),
  • les colonnes (signification, unité, valeurs possibles),
  • les index (requêtes ciblées).

Exemple de commentaire pour un rapport analytique :

/* Rapport mensuel de chiffre d'affaires
   par région et catégorie produit
   pour le tableau de bord de la direction générale */
SELECT region, categorie, SUM(montant_ht) AS ca 
FROM ventes_janvier 
GROUP BY region, categorie;

Exemple de documentation de cœur métier pour un site e‑commerce :

COMMENT ON TABLE commandes IS 
'Commandes validées sur la plateforme depuis janvier 2025.
Relations clients / produits / paiements / transporteurs / statuts.';

COMMENT ON COLUMN commandes.statut_global IS 
'Enum 8 valeurs : "panier", "paye", "preparee", "colis",
"en_route", "livre", "retour", "annulee".
Valeur par défaut : "panier".';

COMMENT ON INDEX idx_commandes_client_statut_date IS 
'Optimise WHERE client_id, statut_global, date_creation 
pour le tableau de bord client et le reporting logistique.';

En combinant les commentaires dans les scripts et les métadonnées dans la base, on obtient un système auto-documenté, plus facile à maintenir par les équipes actuelles et futures.

Sources: SQL Server, MySql , Postgresql