diff --git a/CLAUDE.md b/CLAUDE.md index cd8d8f8..9d40c9c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,322 +1,69 @@ -# zsqlite - SQLite Wrapper para Zig +# zsqlite -> **Ultima actualizacion**: 2025-12-08 -> **Lenguaje**: Zig 0.15.2 -> **Estado**: v1.0 - Completo -> **Inspiracion**: rusqlite (Rust), zig-sqlite, CGo go-sqlite3 +> SQLite wrapper idiomático para Zig 0.15.2+ -## Descripcion del Proyecto +## Estado -**zsqlite** es un wrapper idiomatico de SQLite para Zig que compila SQLite amalgamation directamente en el binario, resultando en un ejecutable unico sin dependencias externas. +**v1.0 - Completo** | 7,563 líneas | 15 módulos | 63 tests -**Filosofia**: -- Zero dependencias runtime -- API idiomatica Zig (errores, allocators, iteradores) -- Type-safe con verificacion comptime -- Binario unico y portable -- Documentacion completa - ---- - -## Estado Actual: COMPLETO - -### Estadisticas - -| Metrica | Valor | -|---------|-------| -| Lineas de codigo | 7,563 | -| Modulos | 15 | -| Tests | 63 | -| Version SQLite | 3.47.2 | - -### Arquitectura Modular +## Arquitectura ``` -zsqlite/ -├── src/ -│ ├── root.zig # Exports y 63 tests (1720 lineas) -│ ├── database.zig # Conexion, tx, pragmas (1052 lineas) -│ ├── statement.zig # Statements, binding, row mapping (903 lineas) -│ ├── session.zig # Change tracking (638 lineas) -│ ├── functions.zig # UDFs, callbacks (567 lineas) -│ ├── rtree.zig # Spatial index (564 lineas) -│ ├── json.zig # JSON1 helpers (437 lineas) -│ ├── serialize.zig # Serialize API (367 lineas) -│ ├── vtable.zig # Virtual tables (321 lineas) -│ ├── backup.zig # Backup y Blob I/O (292 lineas) -│ ├── fts5.zig # Full-text search (229 lineas) -│ ├── types.zig # Tipos comunes (154 lineas) -│ ├── pool.zig # Connection pool (151 lineas) -│ ├── errors.zig # Mapeo de errores (142 lineas) -│ └── c.zig # C bindings (26 lineas) -├── vendor/ -│ └── sqlite3.c/h # SQLite 3.47.2 amalgamation -├── examples/ -│ └── basic.zig # Ejemplo funcional -├── README.md # Documentacion completa -└── CLAUDE.md # Este archivo +src/ +├── root.zig # Exports públicos y tests +├── 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 ``` ---- - -## Funcionalidades Implementadas - -### Core -- [x] Database open/close (file, memory, URI) -- [x] exec() SQL simple -- [x] execAlloc() runtime strings -- [x] Error mapping completo - -### Prepared Statements -- [x] prepare/finalize -- [x] reset/clearBindings -- [x] step() iteration -- [x] Statement metadata - -### Binding -- [x] bindNull/Int/Float/Text/Blob/Bool -- [x] Named parameters (:name, @name, $name) -- [x] **bindAll() - Batch binding con tuples** -- [x] **rebind() - Reset + bind** -- [x] bindTimestamp/bindCurrentTime - -### Column Access -- [x] columnCount/Name/Type -- [x] columnInt/Float/Text/Blob/Bool -- [x] columnIsNull/Bytes/DeclType -- [x] Column metadata (database, table, origin name) - -### Row Mapping (inspirado en zig-sqlite) -- [x] **Row.to(T)** - Map a struct (non-allocating) -- [x] **Row.toAlloc(T)** - Map con allocacion -- [x] **Row.freeStruct()** - Liberar structs allocados -- [x] **RowIterator** - Iterador idiomatico - -### Transacciones -- [x] begin/commit/rollback -- [x] beginImmediate/beginExclusive -- [x] Savepoints (savepoint, release, rollbackTo) -- [x] transaction() helper con auto-rollback - -### Pragmas y Configuracion -- [x] setBusyTimeout -- [x] setJournalMode/setSynchronous -- [x] enableWalMode -- [x] setForeignKeys -- [x] setLimit/getLimit -- [x] optimize() - -### ATTACH/DETACH -- [x] attach()/attachMemory()/detach() -- [x] listDatabases() - -### Backup API -- [x] Backup struct completo -- [x] backupDatabase/backupToFile/loadFromFile - -### Blob I/O -- [x] Blob.open/read/write/reopen/readAll - -### User-Defined Functions -- [x] Scalar functions -- [x] Aggregate functions -- [x] Window functions -- [x] Custom collations - -### Hooks y Callbacks -- [x] Commit/Rollback/Update hooks -- [x] Pre-update hook -- [x] Progress handler -- [x] Authorizer -- [x] Busy handler - -### File Control -- [x] getPersistWal/setPersistWal -- [x] setChunkSize -- [x] getDataVersion - -### VACUUM -- [x] vacuum() -- [x] **vacuumInto(path)** - VACUUM INTO file - -### FTS5 Full-Text Search -- [x] createSimpleTable/createTableWithTokenizer -- [x] search/searchWithHighlight/searchWithSnippet -- [x] rebuild/optimize/integrityCheck - -### JSON1 Extension -- [x] validate/isValid/getType -- [x] extract/extractInt/extractFloat/extractBool -- [x] insert/replace/set/setString/setInt/setFloat/setBool -- [x] remove -- [x] arrayLength/createArray/createObject -- [x] patch (RFC 7396) -- [x] each/tree (iteradores) - -### R-Tree Spatial Index -- [x] createSimpleTable2D/3D -- [x] insert2D/3D, insertPoint2D -- [x] queryIntersects2D/3D, queryContains2D -- [x] getIntersectingIds2D -- [x] BoundingBox2D/3D (intersects, containsPoint, area, expand) -- [x] GeoCoord (distanceKm con Haversine) - -### Virtual Tables API -- [x] VTableModule type -- [x] SimpleVTable helper -- [x] IndexConstraint/IndexOrderBy/IndexInfo -- [x] ResultHelper/ValueHelper -- [x] ColumnDef/generateSchema - -### Serialize/Deserialize API -- [x] **toBytes()** - Serializar DB a bytes -- [x] **toBytesNoCopy()** - Sin copia (puntero interno) -- [x] **fromBytes()** - Deserializar bytes a DB -- [x] **fromBytesReadOnly()** - DB read-only -- [x] **deserializeInto()** - Deserializar en DB existente -- [x] **saveToFile/loadFromFile** - Helpers para archivos -- [x] **cloneToMemory()** - Clonar DB en memoria -- [x] **equals()** - Comparar dos DBs -- [x] **serializedSize()** - Tamano sin copiar - -### Session Extension (Change Tracking) -- [x] **Session.init/deinit** - Crear/destruir session -- [x] **Session.attach/attachAll** - Trackear tablas -- [x] **Session.setEnabled/isEnabled** - Habilitar/deshabilitar -- [x] **Session.setIndirect/isIndirect** - Modo indirecto -- [x] **Session.isEmpty** - Verificar cambios -- [x] **Session.changeset/patchset** - Generar cambios -- [x] **Session.diff** - Diferencias entre DBs -- [x] **applyChangeset()** - Aplicar cambios -- [x] **invertChangeset()** - Invertir (para undo) -- [x] **concatChangesets()** - Concatenar cambios -- [x] **ChangesetIterator** - Iterar cambios -- [x] **Rebaser** - Rebase de cambios - -### Snapshot API (WAL mode) -- [x] **Database.Snapshot** - Handle de snapshot -- [x] **getSnapshot()** - Obtener snapshot actual -- [x] **openSnapshot()** - Abrir DB en snapshot -- [x] **recoverSnapshot()** - Recuperar snapshot - -### Connection Pool -- [x] ConnectionPool.init/deinit -- [x] acquire/release -- [x] capacity/openCount/inUseCount - ---- - -## SQLite Compile Flags - -``` --DSQLITE_DQS=0 # Disable double-quoted strings --DSQLITE_THREADSAFE=0 # Single-threaded (mas rapido) --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_ENABLE_FTS5 # Full-text search --DSQLITE_ENABLE_JSON1 # JSON functions --DSQLITE_ENABLE_RTREE # R-Tree geospatial --DSQLITE_OMIT_LOAD_EXTENSION # No dynamic extensions --DSQLITE_ENABLE_COLUMN_METADATA --DSQLITE_ENABLE_PREUPDATE_HOOK --DSQLITE_ENABLE_SESSION # Session extension --DSQLITE_ENABLE_SNAPSHOT # Snapshot API -``` - ---- - ## Comandos ```bash -# Zig path -ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig +# Build +zig build -# Compilar -$ZIG build +# Tests +zig build test -# Tests (63 tests) -$ZIG build test - -# Ejecutar ejemplo -$ZIG build basic && ./zig-out/bin/basic +# Ejemplo +zig build basic && ./zig-out/bin/basic ``` ---- +## SQLite Flags -## Control de Versiones - -```bash -# Remote -git remote: git@git.reugenio.com:reugenio/zsqlite.git - -# Branch principal -main +``` +-DSQLITE_THREADSAFE=0 # Single-threaded +-DSQLITE_ENABLE_FTS5 # Full-text search +-DSQLITE_ENABLE_JSON1 # JSON functions +-DSQLITE_ENABLE_RTREE # R-Tree +-DSQLITE_ENABLE_SESSION # Change tracking +-DSQLITE_ENABLE_SNAPSHOT # Snapshots +-DSQLITE_ENABLE_COLUMN_METADATA +-DSQLITE_ENABLE_PREUPDATE_HOOK ``` ---- +## Notas Técnicas -## Historial de Desarrollo +- Zig 0.15: usar `std.ArrayListUnmanaged` (no `ArrayList.init`) +- Strings: `std.fmt.allocPrint` + null terminator manual +- Callbacks C: requieren `callconv(.c)` +- SQLITE_TRANSIENT: necesario para strings que Zig puede mover +- Named params: incluir prefijo (`:name`, no `name`) -### 2025-12-08 - v1.0 (COMPLETO) -**Nuevas funcionalidades avanzadas**: -- Row mapping a structs (`Row.to()`, `Row.toAlloc()`) -- Serialize/Deserialize API completa -- Session extension para change tracking -- VACUUM INTO -- Snapshot API para WAL mode -- 63 tests, 7563 lineas de codigo -- README.md con documentacion completa +## Git -### 2025-12-08 - v0.5 (Fase 4) -- Window functions -- URI opening -- Pragmas avanzados -- Connection pool thread-safe -- FTS5, JSON1, R-Tree helpers -- Virtual table API foundations - -### 2025-12-08 - v0.4 (Fase 3B) -- Authorizer, progress handler, pre-update hook -- Busy handler personalizado -- Limits API -- Timestamp binding - -### 2025-12-08 - v0.3 (Fase 3A) -- Blob streaming -- Aggregate/Window functions -- Update/Commit/Rollback hooks - -### 2025-12-08 - v0.2 (Fase 2) -- Named parameters -- Savepoints -- WAL mode helpers -- Backup API -- User-defined functions -- Custom collations -- ATTACH/DETACH - -### 2025-12-08 - v0.1 (Core) -- Estructura inicial -- SQLite amalgamation compilando -- Database, Statement, Error types -- Bind parameters, column access -- Transacciones basicas - ---- - -## Referencias - -- [rusqlite](https://github.com/rusqlite/rusqlite) - Principal inspiracion (Rust) -- [zig-sqlite](https://github.com/vrischmann/zig-sqlite) - Row mapping comptime -- [zqlite.zig](https://github.com/karlseguin/zqlite.zig) - Pool, thin wrapper -- [SQLite C API](https://sqlite.org/c3ref/intro.html) - Documentacion oficial -- [SQLite Session Extension](https://sqlite.org/sessionintro.html) -- [SQLite Backup API](https://sqlite.org/backup.html) - ---- - -**zsqlite v1.0 - Wrapper SQLite completo para Zig** -*2025-12-08* +``` +origin: git@git.reugenio.com:reugenio/zsqlite.git +branch: main +```