Skip to content

v0.7.0 — sql-write: persistir resultados con guardrails

Choose a tag to compare

View all tags
@berriosb berriosb released this 14 Sep 18:53
· 27 commits to main since this release
v0.7.0
9bdeaf2

ADR-002 Nivel 3 cerrado: end-to-end-delivery

Este release agrega sql-write en modo conservador, que cierra el circulo: el data analyst ya no solo consulta y reporta — ahora puede persistir resultados de analisis en una DB de manera segura.

Skill nueva (1)

**sql-write**\ — Carga opcional de sql-analyst, SOLO si el usuario pide persistir resultados. Implementa el patron "dry-run + doble confirmacion + audit log" del ADR-002.

Operaciones permitidas:

  • CREATE TABLE [IF NOT EXISTS] (incluido CREATE TEMPORARY TABLE)
  • CREATE INDEX, CREATE UNIQUE INDEX
  • CREATE VIEW, CREATE OR REPLACE VIEW
  • INSERT INTO ... VALUES (...)
  • INSERT INTO ... SELECT ...
  • WITH cte AS (...) INSERT INTO ...

Operaciones BLOQUEADAS (BlockedOperationError con mensaje accionable):

  • DROP TABLE/DATABASE/SCHEMA/INDEX/VIEW
  • UPDATE, DELETE, TRUNCATE
  • ALTER TABLE ... DROP COLUMN/RENAME
  • GRANT, REVOKE

Guardrails obligatorios

  1. Validacion estatica del SQL antes de ejecutar (regex sobre tokens).
  2. Dry-run obligatorio: genera el DDL + muestra preview de las primeras 5 filas. El caller debe pedir confirmacion #1 al usuario.
  3. Doble confirmacion: execute_insert requiere auto_confirm=True. Sin eso, levanta SqlWriteError.
  4. Auditoria append-only en ~/.agents/audit/sql-write.log (formato JSONL). Cada escritura registra timestamp, action, engine, target, n_rows, duration_ms, sql_preview.
  5. Rotacion automatica cuando el log supera 1MB (mantiene hasta 10 archivos historicos).
  6. Rollback automatico si la transaccion SQLAlchemy falla.

Soporte de engines

Engine Soporte Dep
SQLite local v1 ✅ stdlib
Snowflake v1 ✅ (peerDep opcional) snowflake-connector-python
BigQuery v1 ✅ (peerDep opcional) sqlalchemy-bigquery + google-cloud-bigquery
Redshift v1 ✅ (peerDep opcional) sqlalchemy-redshift + redshift-connector
Postgres / MySQL follow-up (sin escribir en v1) —

Inferencia de tipos

Mapeo automatico de pandas dtypes al dialecto:

Pandas SQLite Postgres Snowflake BigQuery
int64 / int32 INTEGER BIGINT / INTEGER NUMBER(38,0) INT64
float64 / float32 REAL DOUBLE PRECISION FLOAT FLOAT64
bool BOOLEAN BOOLEAN BOOLEAN BOOL
datetime64[ns] TIMESTAMP TIMESTAMP TIMESTAMP_NTZ TIMESTAMP
object (str) TEXT TEXT TEXT STRING

Verificado

```bash
make test-sql-write

-> 5 filas insertadas en SQLite

-> Audit log escrito correctamente

-> DROP/UPDATE/DELETE bloqueados con error accionable

-> 17/17 tests del validator (10 permitidas + 7 bloqueadas)

```

Workflow end-to-end completo para una pega de data analytics

Dia Skill
Lunes: Excel corporativo sucio excel-profiler
Martes: limpieza + EDA csv-profiler + pandas-cleaning
Miercoles: warehouse cloud sql-cloud-warehouse
Jueves: insights insight-synthesis
Viernes: reporte ejecutivo report-export
Viernes (deploy): API REST api-builder
Viernes (persistir): tabla con resultados sql-write (este release)

ADR-002 — estado

  • ✅ excel-formulas (v0.6.0) — auditoria de formulas
  • ✅ sql-write (v0.7.0) — escribir con guardrails
  • ⏳ audit-log — transversal (siguiente)
  • ⏳ sql-write modo full (ADR-003) — DROP/UPDATE/DELETE con rollback
Assets 2
Loading