SQL.Check

Nombre       : README.md
Funcionalidad: Documentar objetivo, estructura y uso base del framework SQL.Check.
Autor        : DBATivit / Codex para FFortuno
Version      : 2.0.0
Creado       : 2026-04-22
Modificado   : 2026-04-23

Framework liviano para ejecutar checks operacionales sobre SQL Server usando T-SQL, PowerShell y SQL Server Agent.

Repositorio destino: Forgejo SQL.Check

Rutas de trabajo

El proyecto separa codigo fuente y ruta operativa:

• Desarrollo y Git: C:\Users\franc\OneDrive\Codex\SQL.Check
• Implementacion y ejecucion: C:\DBATivit\SQL.Check

Toda nueva version debe modificarse, documentarse, validarse y subirse a Git desde la ruta de desarrollo. La ruta C:\DBATivit\SQL.Check se usa como destino de despliegue para ejecutar checks, generar HTML, escribir logs y operar desde SQL Server Agent.

Objetivo

Centralizar procesos de validacion para SQL Server con una estructura estandar:

• Configuracion declarativa por archivo JSON.
• Consultas T-SQL separadas por check.
• Ejecucion por PowerShell.
• Informe HTML por ejecucion.
• Envio opcional de correo.
• Plantillas para ejecucion por SQL Server Agent Job.

Estructura

C:\Users\franc\OneDrive\Codex\SQL.Check\
  checks\AlwaysOnBalance\        Check inicial de balanceo y salud Always On
  checks\AzureSqlManagedInstanceMorningHealth\ Check matinal Azure SQL MI
  checks\BackupFreshness\      Check de frescura de backups
  checks\FailoverClusterInstanceOwner\ Check de nodo owner para FCI
  checks\JobFailures\          Check de fallas recientes de SQL Agent
  config\                        Configuraciones versionables y locales
  docs\                          Documentacion funcional y operativa
  jobs\                          Scripts para SQL Server Agent
  logs\                          Logs tecnicos de ejecucion
  output\                        Informes HTML y resultados generados
  scripts\                       Ejecutores y modulos PowerShell comunes
  sql\                           Consultas T-SQL reutilizables

En despliegue, la misma estructura se copia a:

C:\DBATivit\SQL.Check\

Version 2.0.0

La version 2.0.0 incorpora:

• contrato estandar de salida para todos los checks
• render HTML unificado
• resultado JSON por ejecucion
• validacion explicita de configuracion
• portabilidad basada en RootPath + rutas relativas
• modulos comunes de runtime y validacion
• mejoras operativas en los 3 checks existentes
• nuevos checks BackupFreshness y JobFailures
• base de pruebas con Pester

Checks disponibles

AlwaysOnBalance valida:

• Que cada Availability Group este activo en el host primario esperado segun configuracion.
• Que el estado de salud del grupo no reporte degradacion.
• Que las replicas reporten estado conectado y salud correcta.
• Que las bases de datos del grupo no reporten estados de sincronizacion anormales.
• Que las bases esten joined al AG.
• Que redo queue y log send queue no superen umbrales.
• Que el rol esperado y real de replicas sea consistente.

La salida principal es un archivo HTML en:

C:\DBATivit\SQL.Check\output\AlwaysOnBalance\

FailoverClusterInstanceOwner valida:

• Que cada instancia SQL Server Failover Cluster Instance este ejecutando en el nodo fisico esperado.
• Que la instancia consultada reporte IsClustered = 1.
• Que el nodo actual obtenido desde SERVERPROPERTY('ComputerNamePhysicalNetBIOS') coincida con la configuracion.
• Que SQL Server Agent aparezca operativo.
• Que el cluster group, network name e IP resource no se vean degradados cuando el host de ejecucion puede consultar FailoverClusters.

La salida principal es un archivo HTML en:

C:\DBATivit\SQL.Check\output\FailoverClusterInstanceOwner\

AzureSqlManagedInstanceMorningHealth valida:

• Estado general de Azure SQL Managed Instance al inicio de jornada DBA.
• Uptime reciente de la instancia.
• Estado de bases de usuario.
• Bloqueos activos.
• Requests de larga duracion.
• Fallas recientes de SQL Agent.
• Tamano asignado y autogrowth de bases segun umbral.
• Top waits acumulados.
• Top CPU queries acumuladas.

La salida principal es un archivo HTML en:

C:\DBATivit\SQL.Check\output\AzureSqlManagedInstanceMorningHealth\

BackupFreshness valida:

• antiguedad de backup full por base
• antiguedad de backup log para bases FULL/BULK_LOGGED
• estado de la base evaluada

JobFailures valida:

• fallas recientes de SQL Agent dentro de una ventana configurable
• jobs criticos deshabilitados
• jobs deshabilitados de interes general

Consola administrativa

La administracion de configuraciones se realiza desde consola:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\Users\franc\OneDrive\Codex\SQL.Check\scripts\Start-SQLCheckConsole.ps1

La consola sigue siendo el punto principal de administracion. Esta version agrega modulos comunes al runtime, aunque la consola aun conserva una estructura monolitica.

Contrato estandar

Cada check entrega:

• HTML
• JSON de resultado
• log tecnico

Ver detalle en docs/CheckContract.md.

Seguridad SQL Auth

SQL Auth siempre debe usar password cifrado. No se versionan passwords en texto plano.

Cuando se configura SQL Auth desde la consola:

• Se genera o reutiliza una llave AES local en C:\DBATivit\SQL.Check\config\keys\sqlcheck-secret.key.
• El password se guarda cifrado en AlwaysOnBalance.local.json.
• La conexion SQL se fuerza con Encrypt=True.
• La llave y los archivos *.local.json quedan fuera de Git.

La llave local debe protegerse con permisos NTFS para la cuenta que ejecuta los checks o el SQL Server Agent.

Proteccion de queries SQL

Los checks no ejecutan directamente las queries legibles. La ejecucion operativa usa archivos protegidos:

C:\DBATivit\SQL.Check\sql\*.sql.enc.json

Estos archivos estan cifrados y autenticados con HMAC. Si una query protegida es modificada o sustituida, el check falla antes de ejecutar SQL.

Las queries legibles para analisis DBA se mantienen en:

C:\DBATivit\SQL.Check\docs\sql-reference\

Para regenerar queries protegidas despues de un cambio autorizado:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\DBATivit\SQL.Check\scripts\Protect-SQLCheckQueries.ps1 -ProjectRoot C:\DBATivit\SQL.Check -RuntimeRoot C:\DBATivit\SQL.Check

Despliegue a ruta operativa

Desde la ruta de desarrollo:

robocopy C:\Users\franc\OneDrive\Codex\SQL.Check C:\DBATivit\SQL.Check /E /XD .git /XF *.html *.log *.tmp *.bak

Luego crear o ajustar la configuracion local en la ruta operativa.

Ejecucion manual en ruta operativa

Editar primero:

C:\DBATivit\SQL.Check\config\AlwaysOnBalance.sample.json

Se recomienda usar la consola administrativa para crear AlwaysOnBalance.local.json. Como alternativa manual:

Copy-Item C:\DBATivit\SQL.Check\config\AlwaysOnBalance.sample.json C:\DBATivit\SQL.Check\config\AlwaysOnBalance.local.json

Ejecutar:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\DBATivit\SQL.Check\checks\AlwaysOnBalance\Invoke-AlwaysOnBalanceCheck.ps1 -ConfigPath C:\DBATivit\SQL.Check\config\AlwaysOnBalance.local.json

Para ver debug en tiempo real:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\DBATivit\SQL.Check\checks\AlwaysOnBalance\Invoke-AlwaysOnBalanceCheck.ps1 -ConfigPath C:\DBATivit\SQL.Check\config\AlwaysOnBalance.local.json -ConsoleLog

Los checks usan el mismo patron, cambiando script y configuracion:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\DBATivit\SQL.Check\checks\FailoverClusterInstanceOwner\Invoke-FailoverClusterInstanceOwnerCheck.ps1 -ConfigPath C:\DBATivit\SQL.Check\config\FailoverClusterInstanceOwner.local.json -ConsoleLog

powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\DBATivit\SQL.Check\checks\AzureSqlManagedInstanceMorningHealth\Invoke-AzureSqlManagedInstanceMorningHealthCheck.ps1 -ConfigPath C:\DBATivit\SQL.Check\config\AzureSqlManagedInstanceMorningHealth.local.json -ConsoleLog

powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\DBATivit\SQL.Check\checks\BackupFreshness\Invoke-BackupFreshnessCheck.ps1 -ConfigPath C:\DBATivit\SQL.Check\config\BackupFreshness.local.json -ConsoleLog

powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\DBATivit\SQL.Check\checks\JobFailures\Invoke-JobFailuresCheck.ps1 -ConfigPath C:\DBATivit\SQL.Check\config\JobFailures.local.json -ConsoleLog

Codigo de salida

• 0: check ejecutado sin alertas.
• 1: check ejecutado con alertas funcionales.
• 2: error tecnico de ejecucion.

Pruebas

Base Pester:

Invoke-Pester C:\Users\franc\OneDrive\Codex\SQL.Check\tests

Git

Primer remote sugerido:

git remote add origin https://git.florerialaverbena.cl/ffortuno/SQL.Check.git

El remote debe configurarse en C:\Users\franc\OneDrive\Codex\SQL.Check, no en C:\DBATivit\SQL.Check.