Aller au contenu principal

Extending DB adapters

Comment ajouter un nouveau dialecte SQL (ex: Oracle, ClickHouse) a Auralith. Cette page est destinee aux contributors / forks.

Quand l'utiliser​

  • Vous voulez supporter un dialecte additionnel.
  • Vous portez KytheraDB sur une DB interne / proprietary.
  • Vous experimentez avec une variante (Citus, Hyperscale).

Workflow rapide​

  1. Ajouter le driver Python a backend/requirements.txt (async de preference).
  2. Creer backend/app/domain/services/db_adapter/<dialect>.py avec une classe qui implemente l'interface adapter.
  3. Ajouter <dialect> a l'enum db_type dans les schemas Pydantic et les services qui dispatchent.
  4. Implementer les builders SQL (mass_patch, seed, anonymize) avec le quoting / types corrects. S'inspirer de l'adapter le plus proche.
  5. Ajouter une fixture Docker pour les tests d'integration.
  6. Cote frontend : ajouter le type a dbTypes dans connection-create.component.ts, ajouter une entree help drawer, ajouter une cle i18n.

Interface adapter​

class DbAdapter(Protocol):
    db_type: str

    def quote_ident(self, name: str) -> str: ...
    def quote_literal(self, value: Any) -> str: ...
    def limit_clause(self, n: int, offset: int = 0) -> str: ...
    def auto_increment_type(self) -> str: ...

    async def test_connection(self, dsn: str) -> ConnectionInfo: ...
    async def introspect_tables(self, conn) -> list[Table]: ...
    async def introspect_columns(self, conn, table: str) -> list[Column]: ...
    async def introspect_foreign_keys(self, conn, table: str) -> list[ForeignKey]: ...
    async def introspect_indexes(self, conn, table: str) -> list[Index]: ...

    def anon_strategy_sql(self, strategy: str, col: str, salt: str) -> str | None:
        """Return SQL expression for in-place anonymization, or None to fallback Python."""

A implementer dans l'ordre​

  1. test_connection : prouve que le driver fonctionne.
  2. Introspection : tables, colonnes, FK, index. Sans ca, le schema viewer ne marche pas.
  3. Mass Patch builder : quoting + dry-run select count.
  4. Seed builder : generation INSERT, ordre topologique FK.
  5. Anonymize SQL natif : optimisation. Sans ca, fallback Python toujours.
  6. Migrations DDL : compare + generate. Le plus complexe.

Pieges courants​

  • Async vs sync driver : Auralith est asyncio bottom-to-top. Un driver sync force l'usage de asyncio.to_thread, perd l'avantage. Choisir async natif quand possible.
  • Information schema variations : meme avec un driver compatible Postgres wire (CockroachDB), information_schema peut differer. Tester chaque vue.
  • Quoting edge cases : noms avec quotes, mots reserves. Regex robust required. Voir mass_patch.py apres le sprint securite — il a une suite de tests d'injection.

Tests​

cd backend
pytest tests/integration/test_<dialect>_adapter.py

Fournir une fixture Docker dans backend/docker-compose.test.yml.

Voir aussi​