# zsqlite - SQLite Wrapper para Zig > **Ultima actualizacion**: 2025-12-08 > **Lenguaje**: Zig 0.15.2 > **Estado**: v1.0 - Completo > **Inspiracion**: rusqlite (Rust), zig-sqlite, CGo go-sqlite3 ## Descripcion del Proyecto **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. **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 ``` 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 ``` --- ## 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 # Compilar $ZIG build # Tests (63 tests) $ZIG build test # Ejecutar ejemplo $ZIG build basic && ./zig-out/bin/basic ``` --- ## Control de Versiones ```bash # Remote git remote: git@git.reugenio.com:reugenio/zsqlite.git # Branch principal main ``` --- ## Historial de Desarrollo ### 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 ### 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*