Connettori
I connettori sono le implementazioni reali di Source (estrazione) e Sink (caricamento) verso sistemi esterni. Vivono in src/connectors/<sistema>/ e si iniettano nelle pipeline (mai istanziati dentro la definizione).
Indice
| Connettore | Source | Sink | Doc |
|---|---|---|---|
| PostgreSQL | ✅ streaming (cursor) | ✅ upsert idempotente (ON CONFLICT) | postgres.md |
| SQL Server | ✅ streaming (pause/resume) | ✅ upsert idempotente (MERGE) | sqlserver.md |
| File (storage × codec) | ✅ fileSource | ✅ fileSink | file.md |
| — storage: filesystem · S3 · SFTP · FTP/FTPS · memory | (vedi file.md) | (vedi file.md) | file.md |
| — codec: CSV (anche grezzo) · JSON/NDJSON · XML · XLSX · Parquet | (vedi file.md) | (vedi file.md) | file.md |
| Noeva (file dei workspace) | ✅ file singolo · cartella | ✅ file singolo · multi-file, overwrite/new-version | noeva.md |
Oltre a Source e Sink, ogni connettore SQL fornisce il resolver del nodo lookup, che interroga il DB in sola lettura a metà grafo, a batch di chiavi (ADR-0041):
| DBMS | Resolver | Parametri bindati | Doc |
|---|---|---|---|
| PostgreSQL | postgresLookup | $1, $2, … | postgres.md § Lookup |
| SQL Server | mssqlLookup | @k0, @k1, … | sqlserver.md § Lookup |
La query è la stessa sui due database — segnaposto @chiavi, stesso controllo di sola lettura, stessa normalizzazione delle chiavi — perché la parte comune vive in src/connectors/shared/sql-lookup.ts. Un nuovo connettore SQL ottiene il lookup aggiungendo solo la sintassi dei parametri e la chiamata al driver.
Regole comuni
- DI del client: il
Pool/connessione è iniettato dal chiamante, che ne gestisce il ciclo di vita. - Streaming: i Source restituiscono
AsyncIterable, mai array interi. - Idempotenza: i Sink usano upsert/merge/swap sulla chiave naturale.
- Segreti: solo in
.env(vedi.env.example), mai nel codice/log. - Descriptor UI: ogni Source/Sink espone un
descriptornon sensibile (tipo + puntamenti) per la visualizzazione del nodo nel DAG — whitelist esplicita, mai segreti. Contratto e how-to: ../conventions/node-descriptor.md. - Errori:
ExtractError/LoadError/ConfigErrordasrc/core/errors.ts. - Test: logica pura in unit (CI); I/O reale in
tests/integration/(pnpm run test:integration).