0004. Connettore SQL Server basato su mssql (tedious)

• Stato: Accettata
• Data: 2026-06-03
• Decisori: Team BI/ETL

Contesto

Serve un connettore verso Microsoft SQL Server (sorgente frequente in contesti enterprise/legacy), coerente con le convenzioni del connettore Postgres: streaming, idempotenza del caricamento, niente any, niente segreti hardcoded, DI del client.

Decisione

Adottiamo mssql (wrapper su tedious, puro JavaScript).

• mssqlSource usa la modalità streaming (request.stream) con backpressure (pause/resume).
• mssqlSink esegue un upsert idempotente con MERGE in transazione, a batch.
• Il pool (ConnectionPool) è iniettato: il connettore non ne possiede il ciclo di vita.
• batchSize default 200 per rispettare il limite di 2100 parametri per richiesta di SQL Server.
• Ambiente di test: container Docker mcr.microsoft.com/mssql/server:2022 (docker-compose.yml).

Alternative considerate

• msnodesqlv8 — usa l'ODBC Driver nativo Microsoft: addon nativo + ODBC da installare, più attrito su macOS/arm64 e CI. Scartato.
• ORM (Prisma/TypeORM) — troppo per un connettore ETL low-level.

Conseguenze

• Positive: nessuna dipendenza nativa (installazione semplice su Mac/CI), streaming reale, upsert idempotente, API simmetrica a Postgres.
• Costi/limiti:
  • L'immagine SQL Server è solo linux/amd64: su Apple Silicon gira in emulazione (più lenta).
  • Il limite di 2100 parametri impone batch piccoli (gestito col default e documentato).
  • I file I/O (source.ts, sink.ts) sono coperti dai test di integrazione, non dalla suite unitaria in CI (come per Postgres).