reugenio/zcatsql
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
zcatsql/CLAUDE.md
reugenio fac8bcba62 feat: v1.0 - add row mapping, serialize, session, vacuum into, snapshots 
New features:
- Row-to-struct mapping (Row.to(), Row.toAlloc(), Row.freeStruct())
- Serialize/Deserialize API (toBytes, fromBytes, cloneToMemory, etc.)
- Session extension for change tracking (changesets, patchsets, diff)
- VACUUM INTO for creating compacted database copies
- Snapshot API for consistent reads in WAL mode
- Comprehensive README.md documentation

Technical changes:
- Enable -DSQLITE_ENABLE_SESSION and -DSQLITE_ENABLE_SNAPSHOT
- Add c.zig defines for session/snapshot headers
- Fix connection pool test to use temp file instead of shared cache
- 63 tests passing, 7563 lines of code across 15 modules

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-08 21:04:24 +01:00

322 lines
8.9 KiB
Markdown
Raw Blame History

# 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*
Reference in a new issue View git blame Copy permalink