Controlador Oracle

Esta documentación explica la implementación del controlador Oracle y cómo los parámetros de conexión se corresponden con los campos de la interfaz de usuario en la aplicación Gigantic.

Parámetros de Conexión

Detalles Técnicos

La implementación del controlador Oracle utiliza la biblioteca Node.js oracledb con capacidades de agrupamiento de conexiones.

Aspectos técnicos clave:

• El agrupamiento de conexiones se utiliza a través de la clase Pool de oracledb
• Los conceptos de Propietario y Contenedor (PDB) son específicos de Oracle
• El controlador utiliza el paquete DBMS_METADATA para la generación de DDL
• Manejo de columnas virtuales en el método normalizeRecordOracle
• Múltiples modos de carga soportados: insert, update, merge

Cuando el túnel SSH está habilitado, las conexiones se establecen primero a través del túnel antes de conectarse al servidor Oracle.

Formato de Cadena de Conexión

Las conexiones Oracle combinan campos individuales de la UI en una cadena de conexión. Se soportan dos formatos:

1. Sintaxis de Conexión Fácil (por defecto):

//host:port/database

2. Cadena de Conexión Directa:

user/password@//host:port/database

La aplicación toma los campos individuales de la UI (Host, Puerto, Base de Datos) y los combina en el formato #1 para la biblioteca oracledb.

Opciones de Autenticación

Oracle soporta varios tipos de autenticación:

Soporte de Túnel SSH

El controlador Oracle soporta túneles SSH para acceso seguro a bases de datos detrás de firewalls o en redes privadas. Para información detallada sobre la configuración de túneles SSH, por favor consulte la documentación de Túneles SSH.

Endpoints de API Utilizados

Las conexiones Oracle se utilizan principalmente en:

• Creación de Tap (descubrimiento de fuente de datos)
• Creación de Sink (destino de datos para datos anonimizados)
• Ejecución de Pipeline (extracción y carga de datos)

Tablas Grandes y Reanudación

Esta sección recoge solo lo propio de Oracle. Cómo funcionan la reanudación, los rangos paralelos y las estimaciones de filas en todos los controladores se explica en Bases de datos grandes.

Lectura

• Las tablas se leen por bloques ordenados por la clave primaria, de modo que un job que se detiene se reanuda tras la última clave que guardó. Una tabla sin clave primaria se lee con un único cursor y empieza de nuevo si el job se detiene: no se usa ROWID, porque ordenar por él obliga a ordenar el resto de la tabla en cada bloque.
• Todas las columnas de la clave primaria deben ser NUMBER (con cualquier precisión y escala, o sin ellas, como NUMBER, NUMBER(10) o INTEGER) o de texto (CHAR, VARCHAR2, NVARCHAR2). Los valores de la clave se leen y comparan como texto, así que los números grandes y decimales se reanudan con exactitud. No se usa una clave con alguna columna FLOAT, BINARY_FLOAT o BINARY_DOUBLE, así que esa tabla se lee con un único cursor. Las claves de texto se comparan con NLS_SORT y NLS_COMP a BINARY.

Rangos Paralelos y Estimación de Filas

• Los rangos de clave primaria se cortan a partir de una muestra SAMPLE BLOCK ... SEED de la clave, dimensionada según la estadística BLOCKS de la tabla. Si la muestra es demasiado pequeña, una clave entera de una sola columna se reparte a partes iguales entre su mínimo y su máximo.
• La estimación de filas es NUM_ROWS de ALL_TABLES (USER_TABLES si no se indica Owner). Una tabla sin estadísticas no la tiene y se usa el número de filas guardado en el modelo: recoge estadísticas de las tablas grandes (DBMS_STATS.GATHER_TABLE_STATS).

Carga

• Antes de cargar, el job desactiva las foreign keys de las tablas que carga y las foreign keys de otras tablas que las referencian. Cada una se anota antes en la tabla GIGANTICS_DISABLED_CONSTRAINTS, que se crea en el esquema del Owner (o en el del usuario si no se indica Owner). Al terminar solo se vuelven a activar las anotadas, con ENABLE VALIDATE, y se borran sus anotaciones. Una foreign key que ya estaba desactivada antes del job sigue desactivada.
• Si un job muere, las anotaciones se quedan y el siguiente job que carga esas tablas las activa. Una foreign key que falla en ENABLE VALIDATE (porque las filas cargadas no la cumplen) sigue desactivada y anotada, y se avisa en el log.
• Si no se puede crear la tabla de anotaciones, el job avisa en el log y, al terminar, activa todas las foreign keys desactivadas de esas tablas.
• Los triggers de las tablas cargadas se desactivan con DISABLE ALL TRIGGERS y se activan con ENABLE ALL TRIGGERS al terminar. No se anotan: si un job muere, siguen desactivados hasta que termine otra carga de esas tablas.
• La opción truncate ejecuta TRUNCATE TABLE.
• Las cargas update y merge pasan por una tabla temporal global y un MERGE que compara todas las columnas de una clave primaria compuesta.
• Cuando fallan algunas filas de un lote, el job avisa en el log con el número de filas fallidas y el primer error, y confirma el resto del lote.

Permisos

Para un sink Oracle, el usuario de base de datos necesita:

• CREATE TABLE y cuota en su tablespace, para GIGANTICS_DISABLED_CONSTRAINTS y las tablas de staging del merge. Si el Owner es otro esquema, ambas se crean y se escriben en ese esquema, lo que requiere privilegios como CREATE ANY TABLE.
• SELECT sobre DBA_CONSTRAINTS si se indica Owner (por ejemplo mediante SELECT_CATALOG_ROLE).
• ALTER sobre las tablas que carga y sobre las tablas cuyas foreign keys las referencian (ALTER ANY TABLE si son de otro esquema).

Parámetros Personalizados

El controlador Oracle soporta parámetros personalizados adicionales que pueden especificarse en formato YAML para ajustar finamente el comportamiento de conexión, agrupamiento, configuraciones SSL y otras opciones avanzadas.

Atributos de Conexión

# Configuración de Conexión
stmtCacheSize: 30
edition: "ORA$BASE"
events: false
externalAuth: false
privilege: "SYSDBA"  # o "SYSOPER", "SYSASM", "SYSBACKUP", "SYSDG", "SYSKM", "SYSRAC"

# Soporte de Sharding
shardingKey: ["clave1", "clave2"]
superShardingKey: ["super_clave1", "super_clave2"]

# Etiquetado de Sesión
tag: "app_producción"

Atributos de Agrupamiento

# Configuración de agrupamiento
poolAlias: "miagrupamiento"
poolMin: 4
poolMax: 10
poolIncrement: 1
poolTimeout: 60
poolPingInterval: 60
poolMaxPerShard: 5

# Gestión de cola
queueMax: 50
queueRequests: true
queueTimeout: 60000

# Estadísticas de agrupamiento
enableStatistics: true

Configuración SSL/TLS

# Configuración SSL
sslServerCertDN: "CN=server.ejemplo.com,O=Ejemplo Corp,C=ES"
sslServerDNMatch: true
sslAllowWeakDNMatch: false
useSNI: true

# Cartera Oracle
walletLocation: "/ruta/a/la/cartera/oracle"
walletPassword: "contraseña_cartera"
walletContent: ${file:/ruta/a/la/cartera.zip}

Autenticación Basada en Tokens

# Autenticación basada en tokens
accessToken:
  token: "cadena_de_token_de_acceso_válido"
  privateKey: ${file:/ruta/a/la/llave_privada.pem}
  type: "OCI_TOKEN"  # o "OAUTH2_TOKEN"

Ejemplos de Configuraciones

Configuración Básica

poolMin: 2
poolMax: 15
stmtCacheSize: 50

Configuración SSL con Cartera

walletLocation: ${file:/ruta/a/la/cartera_oracle}
walletPassword: contraseña_cartera
sslServerDNMatch: true
enableStatistics: true
poolTimeout: 30

Configuración Multitenant

owner: propietario_app
poolMax: 20
queueTimeout: 30000

Autenticación Basada en Tokens

accessToken:
  token: ${env:OCI_ACCESS_TOKEN}
  type: "OCI_TOKEN"
stmtCacheSize: 100
events: true