ORM_TruncateTable
Vide intégralement une table SQL et réinitialise (par défaut) son auto-incrément. Procédure destructrice — toutes les lignes de la table sont effacées en une seule opération. Quand le mode metadata est actif sur une table métier, les lignes correspondantes de la table système cshx2_metadata sont également nettoyées dans la même transaction.
📋 Description
ORM_TruncateTable vide intégralement une table SQL en une seule opération, et réinitialise par défaut son compteur d'auto-incrément. C'est l'équivalent dans le framework de l'instruction SQL TRUNCATE TABLE, enrichi de deux comportements automatiques :
- Une transaction locale est ouverte par la procédure : commit en cas de succès, rollback en cas d'échec (avec les nuances décrites en §03).
- Quand le mode metadata est actif et que la table tronquée est une table métier, les lignes correspondantes de la table système
cshx2_metadatasont nettoyées dans la même transaction (voir §04).
L'opération est radicale : toutes les lignes sont supprimées sans condition. Elle ne se prête donc pas aux cas où l'on veut effacer une partie seulement des enregistrements (utiliser des DELETE ciblés ou mth_EffacerSelonID dans ce cas).
1. Réinitialisation d'une table de cache ou temporaire. Tables de logs applicatifs déjà archivés, files d'attente traitées, tables de session, tables de travail intermédiaires d'un traitement batch. Vider en une opération est plus rapide qu'un DELETE FROM ... WHERE 1=1.
2. Repeuplement complet d'une table depuis une source de référence. Cas typique : import full d'un référentiel externe (catalogue, taxonomie, données métier) où l'on veut repartir d'une table vierge avant l'insertion massive des nouvelles lignes.
3. Setup d'environnement de test. Repartir d'une table vide entre deux jeux de tests pour garantir l'indépendance des cas, avec auto-incrément remis à 1 pour des IDs prévisibles.
Toutes les lignes de la table sont effacées en une seule opération. Aucune confirmation n'est demandée par la procédure elle-même — c'est à l'application appelante d'organiser tout contrôle ou validation préalable.
Le caractère récupérable de l'opération dépend du provider (voir §03). Sauvegarde de la table préconisée avant tout appel sur des données de production.
🔑 Signature
LOCAL sTableSQL est une chaîne,
LOCAL bRestartID est un booléen = Vrai
) : (booléen, entier, chaîne)
| Élément | Valeur |
|---|---|
| Visibilité | PUBLIQUE |
Paramètres
| Paramètre | Type | Défaut | Rôle |
|---|---|---|---|
sTableSQL | chaîne | — | Nom de la table SQL à vider (par exemple "cshx2_logs", "cshx2_cache"). |
bRestartID | booléen | Vrai | Si Vrai, l'auto-incrément de la table est réinitialisé (le prochain INSERT obtiendra l'ID 1). Si Faux, l'auto-incrément conserve sa valeur courante (le prochain INSERT obtiendra maxID + 1). Voir §04. |
Valeur de retour
| Élément | Type | Description |
|---|---|---|
bProcessing | booléen | Vrai si le vidage a réussi, Faux en cas d'échec. |
nErrorCode | entier | Code d'erreur négatif en cas d'échec, 0 sinon. |
sErrorMessage | chaîne | Message d'erreur lisible en cas d'échec. |
⚠️ Comportement et précautions
Le TRUNCATE SQL n'est pas un simple DELETE en plus rapide. Plusieurs spécificités de l'instruction sous-jacente méritent d'être connues avant tout usage en production. Le comportement est précisé ci-dessous pour chaque provider supporté.
Caractéristiques générales
| Aspect | Comportement |
|---|---|
| Caractère destructif | Toutes les lignes de la table sont effacées en une seule opération. Aucune sélection partielle possible — pour cela, utiliser DELETE ou mth_EffacerSelonID. |
| Triggers | TRUNCATE ne déclenche pas les triggers DELETE définis sur la table. Si la cohérence métier dépend de ces triggers, préférer un DELETE en boucle plutôt que TRUNCATE. |
| Contraintes de clé étrangère | L'opération échoue si d'autres tables référencent celle-ci par contrainte FK et que ces lignes liées existent. Le code d'erreur retourné permet de détecter ce cas. |
| Performance | Très rapide même sur des tables volumineuses — c'est une opération d'allocation de stockage côté SGBD, pas un parcours ligne à ligne. Généralement la méthode la plus efficace pour vider une grande table. |
| Transaction locale | La procédure ouvre toujours une transaction locale qui englobe le TRUNCATE et, le cas échéant, le nettoyage cshx2_metadata. Le commit ou le rollback est géré automatiquement. |
Comportement transactionnel selon le provider
| Provider | Comportement transactionnel |
|---|---|
| PostgreSQL | TRUNCATE est transactionnel. La transaction locale ouverte par la procédure peut effectivement annuler aussi bien le vidage de la table que le nettoyage cshx2_metadata. Cohérence garantie sur les deux étapes. |
| MySQL · MariaDB | TRUNCATE provoque un commit implicite côté moteur — c'est une limitation de MySQL et MariaDB, pas du framework. Conséquence : si le vidage réussit mais que le nettoyage cshx2_metadata échoue ensuite, le TRUNCATE est déjà persisté en base et un rollback ne le restaurera pas. |
Sur MySQL et MariaDB, le TRUNCATE ne peut pas être annulé par un ROLLBACK ultérieur — c'est une limitation du moteur SQL, indépendante du framework. La transaction locale ouverte par la procédure ne protège donc pas contre un échec de l'étape 2 (nettoyage cshx2_metadata) après une étape 1 réussie. En cas d'échec à l'étape 2, le code retourné permet d'identifier le problème (ERR_ORM_TRUNCATE_META_SQL) — voir §04.
Avant tout usage en production, valider le comportement attendu sur un environnement de recette équivalent — notamment le scénario d'échec de l'étape metadata sur MySQL/MariaDB.
📊 Mode metadata et nettoyage de cshx2_metadata
Le framework ORM_CSHX2 peut fonctionner en mode metadata, dans lequel chaque ligne d'une table métier peut être associée à une ou plusieurs lignes complémentaires dans la table système cshx2_metadata, identifiées par le couple (TABLE_SQL, ID_TABLE_SQL). Ce mode est positionné au niveau de la session ORM.
Comportement de la procédure selon le mode
| Mode | Action de la procédure |
|---|---|
| Mode metadata désactivé | Seul le TRUNCATE de la table cible est effectué. Aucun accès à cshx2_metadata. |
| Mode metadata actif, table métier | Le TRUNCATE est effectué sur la table cible, suivi d'un DELETE FROM cshx2_metadata WHERE TABLE_SQL = ... qui supprime les lignes orphelines associées. Les deux étapes sont englobées dans la même transaction locale. |
| Mode metadata actif, table système | Seul le TRUNCATE est effectué — les tables système (incluant cshx2_metadata elle-même) ne génèrent pas de lignes dans cshx2_metadata par design, le nettoyage est donc inutile. |
Codes d'erreur associés
| Constante | Étape concernée |
|---|---|
ERR_ORM_TRUNCATE_SQL | Échec du TRUNCATE de la table cible (étape 1). |
ERR_ORM_TRUNCATE_META_SQL | Échec du DELETE sur cshx2_metadata (étape 2). Ne survient que si le mode metadata est actif et que la table tronquée est une table métier. |
L'application appelante n'a pas à se préoccuper du mode metadata ni du caractère système ou métier de la table : la procédure détecte ces deux conditions et applique automatiquement le bon comportement. Le seul effet visible côté appelant est l'éventuel retour d'erreur ERR_ORM_TRUNCATE_META_SQL, qui n'apparaît que dans le scénario explicite d'échec de l'étape 2.
🧭 Réinitialisation de l'auto-incrément
Le paramètre bRestartID contrôle ce qu'il advient de la séquence d'auto-incrément après le vidage de la table. Le support du paramètre dépend du provider.
Effet selon le provider
| Provider | Effet de bRestartID |
|---|---|
| PostgreSQL | Le paramètre est respecté. La requête sous-jacente utilise RESTART IDENTITY si bRestartID = Vrai, ou CONTINUE IDENTITY si bRestartID = Faux. |
| MySQL · MariaDB | Le paramètre est ignoré. Sur ces moteurs, TRUNCATE réinitialise toujours l'auto-incrément implicitement — il n'existe pas d'équivalent à CONTINUE IDENTITY. La séquence est donc systématiquement remise à zéro, quel que soit la valeur de bRestartID. |
Cas d'usage selon la valeur
| Valeur | Effet attendu (sur PostgreSQL) | Cas d'usage |
|---|---|---|
Vrai (défaut) | L'auto-incrément est réinitialisé. Le premier INSERT après le vidage obtient l'ID 1. | Setup d'environnement de test, repeuplement complet d'un référentiel, table de cache où les anciens IDs n'ont aucune valeur résiduelle. |
Faux | L'auto-incrément conserve sa valeur courante. Le premier INSERT après le vidage obtient un ID supérieur au plus grand jamais attribué dans cette table. | Tables où les IDs anciens peuvent être référencés par d'autres systèmes (logs externes, identifiants exportés vers une intégration tierce, journaux d'audit) — éviter qu'un nouvel enregistrement réutilise un ID déjà connu ailleurs. Cas d'usage non couvert sur MySQL/MariaDB — voir tableau précédent. |
Une application qui repose sur la conservation de la séquence (bRestartID = Faux) verra son comportement diverger entre les environnements PostgreSQL et MySQL/MariaDB. Si la conservation des IDs est critique, prévoir une stratégie alternative côté applicatif (par exemple ORM_ResetSequence ciblé après un DELETE) plutôt que de se reposer sur ce paramètre.
Pour ajuster une séquence d'auto-incrément sans vider la table, utiliser ORM_ResetSequence qui agit uniquement sur le compteur. ORM_TruncateTable est dédié au cas où le vidage et le reset sont associés.
💡 Exemples
Mode 1 — vidage simple avec reset de l'auto-incrément
Cas d'usage : nettoyage périodique d'une table de cache.
Mode 2 — vidage sans reset de l'auto-incrément
Cas d'usage : table de logs dont les IDs sont susceptibles d'être référencés par un système d'archivage externe — on veut éviter qu'un nouveau log réutilise un ID déjà archivé ailleurs.
Mode 3 — repeuplement complet d'un référentiel
Cas d'usage : import full quotidien d'un catalogue produits depuis une source externe.
Mode 4 — gestion défensive avec garde-fou
Cas d'usage : interdire le truncate sur une base de production avec un test explicite.
Mode 5 — gestion fine des codes d'erreur en mode metadata
Cas d'usage : application en mode metadata sur MySQL/MariaDB, où l'on veut différencier l'échec de l'étape 1 (irrécupérable) de l'étape 2 (incohérence à corriger).