▣ gabysql

Objetivo: convertir gabysql en un motor embebido serio, paso a paso, sin romper lo que ya funciona y con controles explícitos de error, revisión, despliegue y benchmarking.

Base estratégica: este plan se apoya en ANALISIS_PROYECCIONES_GABYSQL.md y en la dirección general definida en ../ROADMAP.md.

🎯 Resultado esperado

Al terminar este plan, gabysql debería haber pasado de:

a:

🧱 Principios que no se negocian

1. No romper lo que ya existe

Cada fase debe preservar:

2. Todo cambio de storage debe tener guardrails

Si cambia:

entonces debe venir acompañado de:

3. Primero confiabilidad, luego amplitud

El orden correcto es:

  1. durability
  2. integrity
  3. correctness
  4. operability
  5. performance
  6. nuevas features SQL

4. Benchmark sin narrativa engañosa

gabysql debe compararse contra otros motores, pero con honestidad:

🗺️ Fases de implementación

Fase 0 — Línea base y control de daño

Objetivo

Congelar una base confiable antes de tocar componentes críticos.

Entregables

Trabajo

Gates de no-ruptura

Tiempo estimado

Fase 1 — Integridad del storage y recovery

Estado: entregada — INTEGRITY CHECK operacional, crash tests dirigidos y WAL recovery por COMMIT funcionando desde 2026-05 (ver hitos completos en CHANGELOG, con superficie SQL extendida en la sesión del 2026-05-25 con E1+E2+E3+F+T+J+J2 y en la sesión del 2026-05-26 con G1+G2+G3+H+I+K1+K2).

Objetivo

Endurecer el corazón del motor sin ampliar demasiado la superficie SQL.

Alcance

Trabajo paso a paso

  1. Especificar v1 formal del file format
  2. añadir checksum en páginas/WAL
  3. implementar verificación de integridad
  4. crear pruebas de crash-replay
  5. documentar compatibilidad y errores esperables

Riesgo principal

Corromper compatibilidad de archivos o recovery.

Mitigación

Revisión

Deploy

Tiempo estimado

Fase 2 — Correctitud funcional básica

Estado: superficie SQL relacional clásica cerrada el 2026-05-25, completada el 2026-05-27. Bloques entregados 2026-05-25: E1+E2+E3, F, T, J+J2. 2026-05-26: G1+G2+G3, H, I, K1+K2 (VERSION 8). 2026-05-27 (5 pushes, VERSION 8→13): L1 (FK actions + UNIQUE multi-col, V9), L2 (CHECK column/table-level, V10), L3 (ALTER TABLE ADD CHECK), residual #2 (named constraints + DROP CONSTRAINT, V11), residual #3 (FK multi-col, V12), residual #4 (ON UPDATE activo + UPDATE de PK), bloque V (vistas lógicas, V13). Pendientes priorizados: bloque W (CTE + window functions).

Objetivo

Completar las operaciones esenciales del motor y dejar reglas de datos más serias.

Alcance

Trabajo paso a paso

  1. implementar constraints en catálogo
  2. extender parser y engine con UPDATE/DELETE
  3. validar reglas de NULL y defaults
  4. ampliar tests de errores y edge cases
  5. ajustar API y admin web si hace falta

Gates de no-regresión

Revisión

Deploy

Tiempo estimado

Fase 3 — Índices y consultas usables

Estado: parcialmente entregada. ORDER BY, índices secundarios simples (Hash y OrderedInt para INT con range scan vía ADR-0017), índices compuestos all-INT vía fingerprint FNV-1a-64 (K2/VERSION 8, ADR-0019), WHERE por columna no-PK, JOINs ANSI (INNER/LEFT/RIGHT/FULL/CROSS/USING/NATURAL con index-loop), agregados single-table (bloque F), derived tables y scalar subqueries (H), set ops (I) y DDL extendido (K1+K2) ya están en main al 2026-05-26. Pendientes: partial indexes, ALTER COLUMN TYPE, ALTER PK, FK multi-col, range scan sobre claves compuestas, range scan por índice secundario sobre TEXT/FLOAT/DATE/DATETIME.

Objetivo

Quitar a la PK la carga de ser la única vía eficiente de consulta.

Alcance

Trabajo paso a paso

  1. definir metadata de índices en catálogo
  2. implementar create/drop de índices
  3. mantener índices en INSERT/UPDATE/DELETE
  4. usar índice secundario en filtros simples
  5. añadir ORDER BY inicial donde aplique

Riesgo principal

Desalineación entre índice primario, secundarios y filas reales.

Mitigación

Revisión

Deploy

Tiempo estimado

Fase 4 — Operación seria y tooling

Objetivo

Volver a gabysql operable y diagnosticable fuera del laboratorio.

Alcance

Trabajo paso a paso

  1. comando de backup offline verificado
  2. comando de restore y validación
  3. log estructurado en gabysql-server
  4. métricas básicas: latencia, errores, counts
  5. documentación de operación y recuperación

Gates

Tiempo estimado

Fase 5 — Rendimiento, explain y planificación básica

Objetivo

Empezar a explicar y optimizar consultas en vez de solo ejecutarlas.

Alcance

Trabajo paso a paso

  1. cerrar suite gabybench
  2. medir point lookup, range scan, insert batch, full scan, sort simple
  3. añadir EXPLAIN textual/JSON
  4. introducir stats básicas por tabla/índice
  5. planner por reglas antes de CBO

Revisión

Tiempo estimado

Fase 6 — Server más fuerte, sin sobredimensionarlo

Objetivo

Hacer que el modo server sea más serio sin convertirlo todavía en un Postgres alternativo.

Alcance

Tiempo estimado

🚫 Fuera de foco temprano

No deben entrar antes de cerrar bien las fases 1 a 5:

🧪 Control de errores y no-regresión

Pirámide de validación

Nivel 1 — Correctitud local

Nivel 2 — Compatibilidad del producto

Nivel 3 — Operación real

Nivel 4 — Performance y regresión

👀 Proceso de revisión por cambio

Todo cambio significativo debe pasar por esta lista:

  1. ¿rompe formato en disco o recovery?
  2. ¿rompe SQL existente?
  3. ¿cambia errores visibles al usuario?
  4. ¿cambia respuesta de API o admin web?
  5. ¿hay prueba nueva que cubra el cambio?
  6. ¿hay actualización documental?
  7. ¿hay benchmark si toca hot paths?

🚀 Estrategia de despliegue

Tipos de release

Tipo Cuándo usarlo Qué exige
patch bug fix sin cambio de formato tests + smoke
minor nuevas features compatibles tests + docs + benchmarks focales
minor con formato cambio de file format controlado compat policy + migración o rechazo explícito
experimental features grandes aún inmaduras bandera o rama separada

Política recomendada

⏱️ Medición de tiempos de comandos

Objetivo

No basta con “funciona”; hay que medir cuánto tarda y detectar regresiones.

Windows / PowerShell

Usar Measure-Command:

Measure-Command { cargo run --release --bin gabysql -- exec demo.db "SELECT * FROM users;" }

Para extraer milisegundos:

$time = Measure-Command { cargo run --release --bin gabysql -- exec demo.db "SELECT * FROM users;" }
$time.TotalMilliseconds

Linux / macOS

Usar /usr/bin/time:

/usr/bin/time -f "%E real, %M KB" cargo run --release --bin gabysql -- exec demo.db "SELECT * FROM users;"

Qué medir siempre

🗃️ Base de datos canónica de prueba: gabybench

Objetivo: tener una DB de referencia fija para validar funcionalidad, regresión y comparación con otros motores.

La especificación detallada vive en GABYBENCH_SPEC.md.

Debe incluir

Escalas recomendadas

🥊 Comparación con otros motores

Motores de referencia recomendados

Motor Rol en la comparación
SQLite baseline principal de motor embebido
PostgreSQL referencia OLTP server madura
MySQL/MariaDB referencia server tradicional
DuckDB referencia analítica / scans

Reglas de comparación

Qué debe mostrar la comparación

📅 Orden de ejecución recomendado

  1. Fase 0 — baseline, golden tests y gabybench
  2. Fase 1 — formato, WAL, checksums, crash tests
  3. Fase 2 — UPDATE, DELETE, constraints
  4. Fase 3 — índices secundarios y consultas más útiles
  5. Fase 4 — backup/restore, logs, métricas, tooling
  6. Fase 5 — benchmarks, EXPLAIN, planner básico
  7. Fase 6 — endurecimiento del modo server

✅ Criterio de éxito por etapa

Una fase solo se considera terminada si cumple las cuatro cosas:

Ese es el criterio correcto para que gabysql crezca con seriedad y no solo con features.