Aller au contenu

ADR-046 — Convention de nommage des catalogs Trino : <engine>_<storage>_<domain>

  • Status : Accepted
  • Date : 2026-05-01
  • Sprint : 62.1
  • Drivers : founder directive 2026-05-01 (« voir tout de suite dans le nom du catalog où vivent les données »), redesign démo data master
  • Related : ADR-045 (3 perimeters), ADR-036 (functional FQDN), Sprint 62 data master plan

Context

Avant Sprint 62 la liste SHOW CATALOGS sur Trino retourne :

iceberg
postgresql
climascore-pg
system / memory / jmx

Trois problèmes :

  1. Aucune information sur le moteur sous-jacent : iceberg est un format de table, pas une source ; postgresql ne dit pas quel Postgres (state DB AKKO ? OLTP banking ? PostGIS climat ?).

  2. Aucune information sur le domaine métier : un prospect qui regarde la page Catalogs ne sait pas si ce catalog contient du transactionnel, du curated DWH, ou du raw ingestion.

  3. Confusion lors de l'élargissement : Sprint 62 ajoute 8 nouveaux catalogs (Cloudera Hive managed/external/iceberg, S3 Iceberg climate, S3 Iceberg public sector, S3 raw taxi, Postgres OLTP banking, Oracle XE, MS SQL CRM, Postgres+PostGIS IoT). Sans convention forte, la liste devient illisible pour la démo prospect.

Le founder a explicitement demandé de « voir dans le nom du catalog que c'est Cloudera, Iceberg, object store, Postgres etc. pour facilement savoir dans la démo qu'on est en train de fédérer plusieurs sources dans Trino ».

Decision

Tous les catalogs Trino AKKO suivent le format :

<engine>_<storage>_<domain>
Composant Définition Exemples
<engine> Le connecteur Trino utilisé, en lower-case postgres, oracle, mssql, cloudera (Hive 3 kerberisé), s3, iceberg
<storage> Le store physique sous-jacent (omis si trivialement = engine) oltp, postgis, hive_managed, hive_external, iceberg, raw
<domain> Le domaine métier OU la sphère technique banking, climascore, iot, risk, climate, publicsector, taxi, legacy_hr, crm

Quand storage == nom natif de l'engine, on raccourcit (oracle_legacy_hr, pas oracle_oracle_legacy_hr).

Catalogs cible post-Sprint 62

Catalog Trino Engine Storage Domaine
postgres_oltp_banking Postgres 16 OLTP row store Banking transactions
postgres_postgis_climascore Postgres 16 + PostGIS row + geom Real estate / climat
postgres_postgis_iot Postgres 16 + PostGIS row + geom IoT asset locations
postgres_oltp_publicsector Postgres 16 OLTP row store INSEE SIRENE companies
oracle_legacy_hr Oracle XE 21c row store ERP HR legacy
mssql_crm MS SQL 2022 Express row store CRM Microsoft Dynamics-like
cloudera_hive_managed_iot Hive 3 (kerberisé) HDFS Parquet managed IoT sensor logs
cloudera_hive_external_climate Hive 3 (kerberisé) external → S3 raw Climat raw radar
cloudera_iceberg_risk Iceberg via Polaris REST HDFS Risk scores curated
s3_iceberg_climate Iceberg via Polaris REST SeaweedFS Climate time-series curated
s3_iceberg_publicsector Iceberg via Polaris REST SeaweedFS INSEE statistics curated
s3_raw_taxi Hive (Trino connector on S3) SeaweedFS Parquet raw Public sector NYC TLC

Catalogs internes Trino (non touchés)

system, memory, jmx, tpch — internals Trino, jamais renommés.

Catalogs legacy en transition

Pendant Sprint 62 : - iceberg reste actif, alias logique de s3_iceberg_climate puis dépublié Sprint 62.6 (cleanup pass) - postgresql reste actif, alias logique de postgres_oltp_state (la state DB AKKO interne — Superset, Airflow, JupyterHub state) — JAMAIS exposé en démo prospect - climascore-pg renommé en postgres_postgis_climascore Sprint 62.2 (le cockpit + ADEN refs sont valuifiés)

Règles

  1. Lower-case + underscore uniquement. Pas de tirets (compatibility avec Trino identifier rules sans backquote).
  2. Pas plus de 3 segments après <engine>_<storage>_<domain>. Si un catalog mélange 3 domaines, c'est un signe qu'il faut le splitter.
  3. Domaine au singulier (banking, pas bankings).
  4. Pas d'instance ID dans le nom (un catalog par démo, pas postgres_oltp_banking_demo1). L'isolation multi-tenant utilise des schémas dans le catalog, pas plusieurs catalogs.
  5. Cohérence avec le namespace k8s : cloudera_* → namespace akko-demo-cloudera ; postgres_postgis_climascore → namespace akko-tenant-climascore ; *_oltp_* ou *_postgis_iot → namespace akko-demo-sources.

Consequences

Positives

  • Lisibilité prospect immédiate : SHOW CATALOGS raconte « 4 sources OLTP
  • 4 stores analytiques + 1 mainframe simulé + 1 lake raw » sans explication.
  • Cohérence cockpit : la page Catalogs peut afficher les 11 cards groupées par engine (Postgres / Oracle / MS SQL / Cloudera / S3 / Iceberg) avec des badges colorés.
  • Diagnostic rapide : un message d'erreur Trino mentionnant cloudera_hive_managed_iot donne immédiatement le namespace, le pod et la table à inspecter.
  • Marketing self-explanatory : la démo banking AML qui fait SELECT … FROM postgres_oltp_banking JOIN cloudera_hive_managed_iot JOIN cloudera_iceberg_risk JOIN s3_raw_taxi montre 4 storages distincts en une seule requête — le titre du dashboard se vend tout seul.

Négatives

  • Renommage de l'existant : iceberg → s3_iceberg_climate, postgresql → postgres_oltp_state (admin only), climascore-pg → postgres_postgis_climascore. Coût : 12+ fichiers à toucher (cf audit Sprint 62 : airflow/dags/akko_common.py constant CATALOG, cockpit index.html/app.js/chat.js, notebooks, docs ADEN demo). Migration progressive Sprint 62.1 → 62.6 avec aliases logiques pendant la transition.
  • Nom plus long : cloudera_hive_managed_iot vs iot. Trade-off accepté pour la lisibilité bout-en-bout.

Tests baseline

  • tests/integration/test_security_baseline.py::test_trino_catalog_naming_convention : parse helm/akko/values.yaml, vérifie que tous les catalogs déclarés sous trino.additionalCatalogs matchent le pattern ^[a-z]+(_[a-z]+){1,2}$.
  • Liste explicite des catalogs autorisés à dériver (system, memory, jmx, tpch).
  • CI audit-hardcoded-identities.py audit pas de catalog inventé sans ADR.

Validation

  • helm template + grep connector.name retourne ≥ 11 catalogs nommés selon la convention (post Sprint 62.6 cleanup)
  • Cockpit Catalogs page affiche les cards avec naming convention
  • ADEN génère des SQL qui utilisent les noms canoniques (post training Sprint 62.6)

References

  • Sprint 62 master plan : /Users/ab2dridi/.claude/plans/precious-skipping-conway.md
  • ADR-045 — 3 perimeters (où vivent les sources)
  • ADR-036 — Functional FQDN canonical naming (pattern parent)
  • Founder directive 2026-05-01 chat