reugenio
04c5d41956
CRITICAL FIX: SQLite was compiled single-threaded but the library provides a ConnectionPool which implies multi-threaded usage. THREADSAFE=2 (multi-thread mode) allows different connections to be used from different threads, which is exactly what ConnectionPool needs. Updated: build.zig, README.md, CLAUDE.md, docs/ARCHITECTURE.md Reported by: Gemini audit (2025-12-14) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
153 lines
4.2 KiB
Markdown
153 lines
4.2 KiB
Markdown
# zcatsql
|
|
|
|
> SQLite wrapper idiomático para Zig 0.15.2+
|
|
|
|
Parte del ecosistema **zcat**: `zcatui` (TUI), `zcatgui` (GUI), `zcatsql` (SQLite)
|
|
|
|
## Estado
|
|
|
|
**v1.1** | ~12,000 líneas | 16 módulos | 80 tests
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
zig build # Compilar
|
|
zig build test # Tests (80/80)
|
|
./zig-out/bin/basic # Ejemplo
|
|
```
|
|
|
|
## Arquitectura
|
|
|
|
```
|
|
src/
|
|
├── root.zig # Exports públicos
|
|
├── database.zig # Conexión, transacciones, pragmas, snapshots
|
|
├── statement.zig # Prepared statements, binding, row mapping
|
|
├── session.zig # Change tracking (Session extension)
|
|
├── serialize.zig # Serialize/Deserialize API
|
|
├── functions.zig # UDFs, callbacks, hooks
|
|
├── backup.zig # Backup API, Blob I/O
|
|
├── pool.zig # Connection pool
|
|
├── fts5.zig # Full-text search
|
|
├── json.zig # JSON1 helpers
|
|
├── rtree.zig # R-Tree spatial index
|
|
├── vtable.zig # Virtual tables API
|
|
├── types.zig # Tipos comunes
|
|
├── errors.zig # Mapeo de errores
|
|
├── c.zig # C bindings
|
|
└── audit/ # Sistema de auditoría
|
|
├── mod.zig # Exports
|
|
├── log.zig # AuditLog principal
|
|
├── entry.zig # Entry + JSON
|
|
├── context.zig # User/app context
|
|
├── index.zig # File index
|
|
├── writer.zig # File rotation
|
|
└── verify.zig # Hash chain verification
|
|
```
|
|
|
|
## Documentación
|
|
|
|
| Archivo | Contenido |
|
|
|---------|-----------|
|
|
| `REFERENCE.md` | **Manual técnico completo** (1566 líneas) - API, ejemplos, tipos |
|
|
| `docs/AUDIT_LOG_DESIGN.md` | Diseño del sistema de auditoría |
|
|
| `docs/API.md` | Referencia API detallada |
|
|
| `docs/ARCHITECTURE.md` | Arquitectura del proyecto |
|
|
| `README.md` | Introducción y ejemplos básicos |
|
|
| `examples/basic.zig` | Ejemplo ejecutable completo |
|
|
|
|
## SQLite Flags
|
|
|
|
```
|
|
-DSQLITE_THREADSAFE=2 # Multi-thread (required for ConnectionPool)
|
|
-DSQLITE_ENABLE_FTS5 # Full-text search
|
|
-DSQLITE_ENABLE_JSON1 # JSON functions
|
|
-DSQLITE_ENABLE_RTREE # R-Tree spatial
|
|
-DSQLITE_ENABLE_SESSION # Change tracking
|
|
-DSQLITE_ENABLE_SNAPSHOT # Snapshots
|
|
-DSQLITE_ENABLE_COLUMN_METADATA
|
|
-DSQLITE_ENABLE_PREUPDATE_HOOK # Pre-update hooks (audit)
|
|
```
|
|
|
|
## Notas Zig 0.15
|
|
|
|
| Cambio | Solución |
|
|
|--------|----------|
|
|
| `ArrayList.init` no existe | Usar `ArrayListUnmanaged` + `.empty` |
|
|
| `callconv(.C)` | Cambiar a `callconv(.c)` (minúscula) |
|
|
| `bufferedReader()` | Usar `readFileAlloc` |
|
|
| Strings para SQLite | `allocPrint` + null terminator |
|
|
| Named params | Incluir prefijo (`:name`) |
|
|
|
|
## Audit Log
|
|
|
|
```zig
|
|
var audit = try AuditLog.init(allocator, &db, .{
|
|
.log_dir = "/var/log/audit",
|
|
.app_name = "my_app",
|
|
});
|
|
defer audit.deinit();
|
|
audit.start(); // IMPORTANTE: después de que struct esté en memoria final
|
|
```
|
|
|
|
**Verificar integridad:**
|
|
```zig
|
|
var result = try verifyAuditChain(allocator, "/var/log/audit");
|
|
defer result.deinit(allocator);
|
|
if (!result.valid) { /* ALERTA */ }
|
|
```
|
|
|
|
---
|
|
|
|
## TEAM STANDARDS
|
|
|
|
**Ubicación:** `/mnt/cello2/arno/re/recode/teamdocs/`
|
|
|
|
### Normas Esenciales
|
|
|
|
**NUNCA:**
|
|
- Ejecutar binarios en background (`&`) - shells zombies
|
|
- Commit sin testing
|
|
- Silenciar warnings
|
|
- Duplicar código (verificar common/ primero)
|
|
- Archivos >600 líneas
|
|
- Modificar scope sin consultar
|
|
|
|
**SIEMPRE:**
|
|
- DRY - Una función por tarea
|
|
- Testing progresivo (compilar + verificar)
|
|
- Security commits antes de refactorizaciones
|
|
- Actualizar CLAUDE.md cada sesión
|
|
- Fragmentar: <400 líneas (core), <200 (utils)
|
|
|
|
### Comunicación
|
|
- Directo al grano, sin preámbulos
|
|
- Honestidad técnica total
|
|
- Si algo está mal, decirlo y explicar
|
|
|
|
### Workflow
|
|
1. Leer `teamdocs/LAST_UPDATE.md`
|
|
2. Leer CLAUDE.md del proyecto
|
|
3. Implementar con testing progresivo
|
|
4. Actualizar documentación
|
|
5. Commit tras confirmación usuario
|
|
|
|
### Documentos Clave
|
|
- `QUICK_REFERENCE.md` - Cheat sheet (<1 min)
|
|
- `NORMAS_TRABAJO_CONSENSUADAS.md` - Metodología completa
|
|
- `NORMAS_PATRONES_DESARROLLO.md` - Patrones específicos
|
|
|
|
---
|
|
|
|
## Git
|
|
|
|
```
|
|
origin: git@git.reugenio.com:reugenio/zcatsql.git
|
|
branch: main
|
|
```
|
|
|
|
## Zig Path
|
|
|
|
```bash
|
|
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
|
|
```
|