Controlador MSSQL

Esta documentación explica la implementación del controlador MSSQL 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 MSSQL utiliza la biblioteca Node.js mssql que internamente usa la biblioteca tedious para conexiones.

Aspectos técnicos clave:

• El agrupamiento de conexiones es soportado a través de la bandera pooled en la configuración
• La autenticación puede ser de tipo SQL Server (usuario/contraseña) o autenticación de Windows
• El controlador utiliza vistas INFORMATION_SCHEMA y tablas del sistema para la extracción de metadatos
• La extracción de esquemas incluye nombres de tablas, información de columnas y tipos de datos
• La generación de DDL utiliza tablas del sistema para crear sentencias CREATE TABLE
• El controlador requiere permisos VIEW DATABASE STATE para acceder a sys.dm_db_partition_stats
• Las operaciones de inserción masiva son soportadas a través del método bulkBatchInsert
• Las relaciones de clave foránea se detectan consultando sys.foreign_keys y tablas relacionadas
• Manejo adecuado de tipos de datos específicos de Microsoft SQL Server (uniqueidentifier, datetime2, etc.)

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

Formato de Cadena de Conexión

Las conexiones MSSQL se construyen usando el formato de conexión de tedious:

Server=[host],[port];Database=[database];User ID=[user];Password=[password];Encrypt=true;TrustServerCertificate=true;

Para autenticación de Windows, la cadena de conexión omite el User ID y Password:

Server=[host],[port];Database=[database];Integrated Security=true;Encrypt=true;TrustServerCertificate=true;

Opciones de Autenticación

MSSQL soporta varios tipos de autenticación:

Soporte de Túnel SSH

El controlador MSSQL 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 MSSQL 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)

Dependencia de Controlador Node.js

El controlador MSSQL depende de la biblioteca Node.js mssql:

• Biblioteca: mssql
• Propósito: Conectarse a bases de datos Microsoft SQL Server
• Características: Agrupamiento de conexiones, sentencias preparadas, operaciones masivas, transacciones

Tablas Grandes y Reanudación

Esta sección recoge solo lo propio de SQL Server. 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ó. Solo se usa la clave primaria: un heap o cualquier tabla sin clave primaria se lee con un único cursor y empieza de nuevo si el job se detiene.
• Todas las columnas de la clave primaria deben ser enteras (int, bigint, smallint, tinyint, bit), decimal sin decimales y de hasta 15 dígitos, o de texto (char, varchar, nvarchar, uniqueidentifier). No se usa una clave con alguna columna numeric, float, real, money o de fecha u hora, ni un decimal con decimales o de más de 15 dígitos, porque un número de JavaScript no lo representa con exactitud.

Rangos Paralelos y Estimación de Filas

• Los rangos de clave primaria se cortan a partir de una muestra TABLESAMPLE (n PERCENT) REPEATABLE de la clave, dimensionada según las páginas de la tabla en sys.dm_db_partition_stats. 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 el row_count de la tabla (heap o índice clustered) en sys.dm_db_partition_stats, que SQL Server mantiene sin necesidad de estadísticas.

Carga

• Antes de cargar, el job marca cada tabla que carga con la propiedad extendida gigantics_nocheck, ejecuta NOCHECK CONSTRAINT ALL y DISABLE TRIGGER ALL sobre ella y activa IDENTITY_INSERT.
• En las cargas insert, las foreign keys de otras tablas que apuntan a las tablas cargadas también se desactivan con NOCHECK y se marcan. Una foreign key que ya estaba desactivada sin la marca se deja como está.
• La opción truncate ejecuta TRUNCATE TABLE, y DELETE si falla.
• Al terminar, el job vuelve a activar las restricciones con CHECK CONSTRAINT ALL, quita la marca, activa los triggers y desactiva IDENTITY_INSERT. Las foreign keys de otras tablas se activan WITH CHECK si antes eran de confianza (trusted).
• Por defecto, las restricciones de las tablas cargadas se activan sin comprobar las filas existentes, así que SQL Server las marca como no fiables (not trusted). Pon trustConstraints: true en Parámetros Personalizados para activarlas WITH CHECK: SQL Server lee entonces cada tabla entera, así que aumenta requestTimeout para las tablas grandes. Si la comprobación falla, el job avisa en el log y deja las restricciones activas pero no fiables.
• Si un job muere, sus marcas se quedan. Un job que carga otras tablas avisa de que las tablas marcadas siguen con las restricciones y los triggers desactivados, y el siguiente job que carga una tabla marcada los vuelve a activar.

Permisos

Para un sink SQL Server, el usuario de base de datos necesita:

• ALTER sobre las tablas que carga y sobre las tablas con foreign keys que apuntan a ellas. La propiedad extendida, NOCHECK, DISABLE TRIGGER, IDENTITY_INSERT y TRUNCATE TABLE lo requieren.
• VIEW DATABASE STATE, para las estimaciones de filas y el tamaño de las muestras.

Parámetros Personalizados

El controlador MSSQL 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.

Opciones de Conexión

# Seguridad y Encriptación
encrypt: true
trustServerCertificate: true
cryptoCredentialsDetails:
# Opciones de configuración TLS
rejectUnauthorized: false
multiSubnetFailover: false

# Opciones de Autenticación
domain: "MIDOMINIO"
trustedConnection: false  # Para autenticación de Windows con el controlador msnodesqlv8

# Comportamiento de Conexión
connectionRetryInterval: 500
maxRetriesOnTransientErrors: 3

Opciones de Agrupamiento

# Configuración de agrupamiento
pool:
  min: 0
  max: 10
  idleTimeoutMillis: 30000
  acquireTimeoutMillis: 30000

Opciones de Transacciones

# Configuración de transacciones
transaction:
  isolationLevel: "READ_COMMITTED"  # o "READ_UNCOMMITTED", "REPEATABLE_READ", "SERIALIZABLE", "SNAPSHOT"

Ejemplos de Configuraciones

Configuración Básica

encrypt: true
trustServerCertificate: false
connectionRetryInterval: 1000

Configuración con Dominio de Windows

domain: "CORPORATIVO"
trustedConnection: true
encrypt: true

Configuración Avanzada con Agrupamiento

pool:
  min: 5
  max: 20
  idleTimeoutMillis: 60000
transaction:
  isolationLevel: "SNAPSHOT"
multiSubnetFailover: true