Omika/docs/hfsql-odbc-probe.md

HFSQL ODBC Capability Probe

⚠ CRITICAL — pour base de test / clone uniquement

Cet outil est exclusivement réservé à une base clone ou de test. Il ne doit jamais être lancé contre une base de production.

Les probes d'écriture (transaction, returning) effectuent des INSERT temporaires (avec ROLLBACK), mais un auto-incrément peut être consommé même après rollback.

Pourquoi cet outil ?

Avant d'implémenter la création de Client (POST /clients), nous devons confirmer expérimentalement que le driver ODBC HFSQL supporte :

1. INSERT INTO ... RETURNING <colonne_auto_id> via OdbcCommand.ExecuteScalar() et ExecuteReader()
2. Les transactions (BEGIN / ROLLBACK)
3. Le format de GUID Omika (32 caractères, format N)

Ces capacités ne peuvent pas être vérifiées sans une connexion réelle.

Commandes

dotnet run --project tools/Omika.HfSqlProbe -- <commande> <options>

capabilities — lecture seule

Affiche les informations du driver ODBC et teste SELECT 1.

dotnet run --project tools/Omika.HfSqlProbe -- capabilities --connection-string "<DSN>"

transaction — écriture (exige --allow-write-probe)

Teste BEGIN / INSERT / SELECT / ROLLBACK sur une table de test.

dotnet run --project tools/Omika.HfSqlProbe -- transaction `
  --connection-string "<DSN>" `
  --allow-write-probe `
  --table ProbeTable `
  --marker-column TestMarker

returning — écriture (exige --allow-write-probe)

Teste INSERT ... RETURNING via ExecuteScalar et ExecuteReader.

dotnet run --project tools/Omika.HfSqlProbe -- returning `
  --connection-string "<DSN>" `
  --allow-write-probe `
  --table ProbeTable `
  --id-column PKID `
  --marker-column TestMarker

omika-guid — lecture seule

Statistiques sur les GUID de la table Client (longueur 32/36, doublons).

dotnet run --project tools/Omika.HfSqlProbe -- omika-guid --connection-string "<DSN>"

Options

Option	Description
--connection-string	Chaîne ODBC HFSQL (DSN=...) — obligatoire
--allow-write-probe	Confirme l'utilisation sur une base clone/test (obligatoire pour writes)
--table	Table pour les probes d'écriture
--id-column	Colonne auto-ID (défaut : PKID)
--marker-column	Colonne recevant la valeur marqueur (défaut : Marker)
--schema	batik ou omika (pour probes spécifiques Client)
--use-client-table	Écriture sur la table Client (clone DB uniquement !)

Codes de sortie

Code	Signification
0	Succès
1	Capacité testée non supportée / échec
2	Arguments invalides / sécurité
3	Connexion impossible

Ordre recommandé pour le premier test réel

1. capabilities sur une clone — valider le driver et la connexion
2. returning sur une table de test dédiée avec colonne auto-ID — prouver que RETURNING fonctionne
3. transaction sur la même table — prouver l'isolation
4. Si 1/2/3 sont verts : omika-guid pour les statistiques GUID
5. Ensuite seulement : tests spécifiques Client Batik/Omika

Niveaux de validation

• Niveau 1 : capacité générique du driver (returning, transaction)
• Niveau 2 : INSERT Client physique (Batik ou Omika) — nécessite le niveau 1 validé

Protection anti-production

• --allow-write-probe est obligatoire pour toute commande d'écriture
• La connection string n'est jamais lue automatiquement (pas de appsettings.json)
• Les credentials sont masqués dans les messages d'erreur
• Les identifiants SQL sont strictement validés (\A[A-Za-z_][A-Za-z0-9_]*\z)

Limitations connues

• La validation RETURNING n'a pas encore été exécutée contre un vrai driver HFSQL
• L'outil ne prouve pas comment l'application historique Omika générait ses GUID
• Un auto-ID peut être consommé par HFSQL même après ROLLBACK