zcatsql/CLAUDE.md

# zsqlite - SQLite Wrapper para Zig

> **Fecha creación**: 2025-12-08
> **Versión Zig**: 0.15.2
> **Estado**: En desarrollo inicial

## Descripción del Proyecto

Wrapper idiomático de SQLite para Zig. Compila SQLite amalgamation directamente en el binario, resultando en un ejecutable único sin dependencias externas.

**Filosofía**:
- Zero dependencias runtime
- API idiomática Zig (errores, allocators, iteradores)
- Binario único y portable
- Compatible con bases de datos SQLite existentes

## Arquitectura

```
zsqlite/
├── CLAUDE.md           # Este archivo
├── build.zig           # Sistema de build
├── src/
│   ├── root.zig        # Exports públicos
│   ├── sqlite.zig      # Wrapper principal
│   ├── statement.zig   # Prepared statements
│   ├── row.zig         # Iterador de filas
│   └── errors.zig      # Mapeo de errores SQLite
├── vendor/
│   ├── sqlite3.c       # SQLite amalgamation
│   └── sqlite3.h       # Headers SQLite
└── examples/
    └── basic.zig       # Ejemplo básico
```

## API Objetivo

```zig
const std = @import("std");
const sqlite = @import("zsqlite");

pub fn main() !void {
    var db = try sqlite.open("test.db");
    defer db.close();

    // Ejecutar SQL directo
    try db.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");

    // Prepared statement con parámetros
    var stmt = try db.prepare("INSERT INTO users (name) VALUES (?)");
    defer stmt.deinit();

    try stmt.bind(.{ "Alice" });
    try stmt.exec();

    stmt.reset();
    try stmt.bind(.{ "Bob" });
    try stmt.exec();

    // Query con iterador
    var query = try db.prepare("SELECT id, name FROM users");
    defer query.deinit();

    while (try query.step()) |row| {
        const id = row.int(0);
        const name = row.text(1);
        std.debug.print("User {}: {s}\n", .{ id, name });
    }
}
```

## Funcionalidades Planificadas

### Fase 1 - Core (Actual)
- [x] Estructura proyecto
- [ ] Compilar SQLite amalgamation
- [ ] Abrir/cerrar bases de datos
- [ ] Ejecutar SQL simple (exec)
- [ ] Prepared statements básicos
- [ ] Bind de parámetros (int, text, blob, null)
- [ ] Iterador de resultados

### Fase 2 - Transacciones y Errores
- [ ] BEGIN/COMMIT/ROLLBACK helpers
- [ ] Mapeo completo errores SQLite
- [ ] SAVEPOINT support

### Fase 3 - Avanzado
- [ ] Blob streaming (para archivos grandes)
- [ ] User-defined functions
- [ ] Collations personalizadas
- [ ] Backup API

## SQLite Amalgamation

Usamos SQLite amalgamation (sqlite3.c + sqlite3.h) que es la forma recomendada de embeber SQLite. Es un único archivo .c con todo el código de SQLite.

**Versión objetivo**: SQLite 3.45+ (última estable)

**Flags de compilación recomendados**:
```
-DSQLITE_DQS=0                    # Disable double-quoted strings
-DSQLITE_THREADSAFE=0             # Single-threaded (más rápido)
-DSQLITE_DEFAULT_MEMSTATUS=0      # Disable memory tracking
-DSQLITE_DEFAULT_WAL_SYNCHRONOUS=1
-DSQLITE_LIKE_DOESNT_MATCH_BLOBS
-DSQLITE_OMIT_DEPRECATED
-DSQLITE_OMIT_SHARED_CACHE
-DSQLITE_USE_ALLOCA
-DSQLITE_ENABLE_FTS5              # Full-text search
-DSQLITE_ENABLE_JSON1             # JSON functions
```

## Compilación

```bash
# Descargar SQLite amalgamation (una sola vez)
cd vendor
curl -O https://sqlite.org/2024/sqlite-amalgamation-3450000.zip
unzip sqlite-amalgamation-3450000.zip
mv sqlite-amalgamation-3450000/* .
rm -rf sqlite-amalgamation-3450000*

# Compilar
zig build

# Ejecutar tests
zig build test

# Ejecutar ejemplo
zig build example
```

## Diferencias con otros wrappers

| Característica | zsqlite | zig-sqlite | zqlite.zig |
|----------------|---------|------------|------------|
| Compila SQLite | Sí | No (linkea) | Sí |
| API idiomática | Sí | Parcial | Sí |
| Zero alloc option | Planificado | No | No |
| Zig 0.15 | Sí | ? | ? |

## Uso en simifactu-zig (futuro)

Este wrapper está diseñado para ser drop-in replacement del uso de SQLite en simifactu-fyne, soportando:
- Foreign keys
- Transactions
- Prepared statements
- BLOB storage
- JSON functions

---

## Equipo y Metodología

### Normas de Trabajo

**IMPORTANTE**: Todas las normas de trabajo están en:
```
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/
```

### Control de Versiones

```bash
# Remote
git remote: git@git.reugenio.com:reugenio/zsqlite.git

# Branches
main        # Código estable
develop     # Desarrollo activo
```

### Zig Path

```bash
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
```

---

## Notas de Desarrollo

*Se irán añadiendo conforme avance el proyecto*