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

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)

• 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

# 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

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

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

Zig Path

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