Conceptos centrales de Fetcher

El modelo de Fetcher en un solo lugar: conexiones, tipos de datasource, esquemas, jobs de extracción, filtros, resultados, hosts y el alcance de tenant que los separa.

Fetcher tiene un modelo pequeño. Registras una conexión a una base de datos externa. Fetcher descubre el esquema que hay detrás. Envías un job de extracción que nombra los campos que quieres. Fetcher te devuelve un resultado con un digest de integridad sobre los bytes exactos que produjo.

Esta página define cada concepto. Cada sección apunta después a la página que lo cubre por completo.

​

El modelo de un vistazo

---

Concepto	Definición
Conexión	Una referencia nombrada y almacenada a una base de datos externa.
Tipo de datasource	El motor de base de datos detrás de una conexión. Fetcher acepta cinco.
Esquema	Las tablas y los campos que Fetcher encuentra en un datasource.
Job de extracción	Una solicitud asíncrona de campos nombrados en tablas nombradas.
Filtro	Una condición por campo que limita las filas que devuelve un job.
Resultado	Las filas extraídas, más el digest que las identifica.
Engine	El núcleo de extracción. Decide qué significa una extracción.
Host	La aplicación que ejecuta el Engine. Es dueña de las colas, el almacenamiento y el transporte.
Tenant	El único límite de aislamiento. Cada operación lleva un ID de tenant.

​

Conexiones

---

Una conexión guarda el tipo de datasource, el host, el puerto, el nombre de la base, las credenciales y la configuración TLS opcional de una base de datos externa. Un configName corto la identifica dentro del tenant, y cada job y cada llamada de esquema direccionan el datasource por ese nombre.

Fetcher cifra la contraseña con AES-256-GCM antes de que llegue al almacenamiento. El registro almacenado también guarda la versión de clave que la protegió. Una conexión nunca vuelve a un llamador con su contraseña.

Lee Conexiones para el ciclo de vida completo, la prueba de conexión y la regla que bloquea una actualización o una eliminación mientras aún corren jobs.

​

Tipos de datasource

---

Una conexión declara uno de cinco tipos. Envía el valor en mayúsculas: la validación de la solicitud compara exactamente estas cinco cadenas y rechaza cualquier otra capitalización con 400.

• POSTGRESQL
• MYSQL
• ORACLE
• SQL_SERVER
• MONGODB

Los cinco se comportan de forma distinta por dentro. PostgreSQL y SQL Server califican las tablas que están fuera del esquema por defecto. Oracle trabaja en espacios de nombres de propietario. MongoDB no tiene ningún esquema declarado, así que Fetcher lo infiere a partir de una muestra de documentos.

​

Esquemas

---

Un snapshot de esquema lista las tablas de un datasource y los campos de cada tabla. Fetcher lo construye directamente desde el datasource, así que no mantienes un catálogo aparte.

Dos cosas se apoyan en un snapshot. La validación de esquema revisa el mapeo de un job contra él antes de que empiece la extracción. La caché de esquema guarda un snapshot reciente bajo el tenant y el nombre de configuración, de modo que el trabajo repetido evita la ida y vuelta a la base de datos.

Lee Descubrimiento de esquemas para el comportamiento en vivo frente al de caché, las diferencias por base de datos y el informe de validación.

​

Jobs de extracción

---

Un job nombra los campos que hay que extraer, por tabla y por datasource:

{
  "dataRequest": {
    "mappedFields": {
      "my_postgres": {
        "accounts": ["id", "email", "created_at"]
      },
      "my_mongo": {
        "transactions": ["*"]
      }
    }
  }
}

Un job puede abarcar varios datasources, varias tablas por datasource y varios esquemas. Usa ["*"] para tomar todos los campos de una tabla.

El Manager acepta un job y responde 202 Accepted. Una solicitud repetida dentro de una ventana de cinco minutos responde 200 OK y devuelve el job que ya existe. Un job que falló no impide un reintento.

Los límites del Engine acotan el trabajo de fuentes de datos genéricas. Los valores por defecto permiten 10 datasources por extracción, 20 tablas por datasource, 50 campos por tabla y un plazo de cinco minutos. Quienes incorporan el Engine pueden bajar, pero no subir, esos límites con ExtractionRequest.Overrides. La carga útil de jobs del Manager autónomo no tiene un campo de overrides de límites, y el Worker solo acepta un override positivo de ENGINE_MAX_RESULT_BYTES. La parte plugin_crm usa la ruta de compatibilidad explícita del Worker.

​

Filtros

---

Un filtro reduce las filas de una tabla. El payload del job anida los filtros en cuatro niveles: datasource, después tabla, después campo, después operador.

{
  "dataRequest": {
    "filters": {
      "my_postgres": {
        "transactions": {
          "status": { "in": ["completed", "pending"] }
        }
      }
    }
  }
}

Existen diez operadores: eq, ne, gt, gte, lt, lte, between, in, nin y like. Cada operador toma un arreglo JSON. Varios operadores sobre el mismo campo se combinan con AND.

​

Resultados

---

Una extracción produce exactamente una forma de resultado. En modo directo el Engine devuelve las filas en línea como JSON indentado y estampa un digest SHA-256 sobre esos bytes. El payload sale del Engine sin cifrar, y el host decide qué hacer después.

En modo de almacenamiento el Engine transmite las filas a un sink que provee el host, un objeto JSON por línea. Devuelve una referencia en lugar de los bytes, con un digest SHA-256 sobre exactamente los bytes escritos. En este camino el Engine no mantiene ningún resultado completo en memoria.

Cada modo calcula el hash de lo que emite: el modo directo el documento indentado, el modo de almacenamiento las líneas transmitidas. El Engine canoniza el orden planificado de campos y pasos antes de serializar. Un digest identifica los bytes exactos emitidos por esa ejecución; no lo trates como una garantía de equivalencia entre ejecuciones salvo que controles el orden de la consulta al datasource y todo el procesamiento del host. Los dos modos escriben formas distintas, así que compara un digest solo contra otro digest del mismo modo. El runner genérico del Engine se detiene en el primer paso que falla y no devuelve un resultado directo exitoso. Los hosts definen su propio comportamiento para rutas de compatibilidad u orquestación de varias etapas.

El Worker independiente conduce el modo directo. Después firma el texto plano con HMAC-SHA256, lo cifra con AES-GCM y lo escribe en almacenamiento de objetos compatible con S3. Consulta Arquitectura.

​

Engine y hosts

---

El Engine es la parte de Fetcher que es dueña del ciclo de vida de las conexiones, el descubrimiento de esquemas, la planificación de consultas, la extracción, los límites y la seguridad de tenant. Se distribuye como su propio módulo Go sin dependencias de terceros, y habla con el mundo exterior solo a través de puertos que provee un host.

Un host provee esos puertos y es dueño de todo lo que el Engine se niega a conocer: HTTP, colas, almacenamiento de objetos, autenticación y el ciclo de vida del job. El Manager y el Worker son dos de esos hosts. Tu propia aplicación puede ser un tercero.

Lee Arquitectura para conocer los dos servicios, los puertos y qué le corresponde a cada lado.

​

Tenants

---

El ID de tenant es el único límite de aislamiento en el Engine. No hay un concepto de organización ni un concepto de producto por debajo de él. Cada operación valida el tenant antes de tocar una conexión, una entrada de caché o un datasource.

El modo de tenant único es el valor por defecto. El modo multi-tenant da a cada tenant su propia base de datos de metadatos, que Fetcher resuelve a partir de los claims del JWT. Sin una base de datos de tenant en el contexto, la llamada falla. Nunca recurre a la base de datos compartida. Consulta Multi-tenancy para el modelo de toda la plataforma.

​

Próximos pasos

---

Arquitectura

El Manager, el Worker y el Engine que ambos ejecutan.

Conexiones

Registra, prueba, actualiza y elimina una conexión a un datasource.

Descubrimiento de esquemas

Cómo Fetcher lee un esquema, lo guarda en caché y valida un job contra él.

Primeros pasos

Ejecuta Fetcher en local y corre tu primer job de extracción.