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

8.9 KiB

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

Database open/close (file, memory, URI)
exec() SQL simple
execAlloc() runtime strings
Error mapping completo

Prepared Statements

prepare/finalize
reset/clearBindings
step() iteration
Statement metadata

Binding

bindNull/Int/Float/Text/Blob/Bool
Named parameters (:name, @name, $name)
bindAll() - Batch binding con tuples
rebind() - Reset + bind
bindTimestamp/bindCurrentTime

Column Access

columnCount/Name/Type
columnInt/Float/Text/Blob/Bool
columnIsNull/Bytes/DeclType
Column metadata (database, table, origin name)

Row Mapping (inspirado en zig-sqlite)

Row.to(T) - Map a struct (non-allocating)
Row.toAlloc(T) - Map con allocacion
Row.freeStruct() - Liberar structs allocados
RowIterator - Iterador idiomatico

Transacciones

begin/commit/rollback
beginImmediate/beginExclusive
Savepoints (savepoint, release, rollbackTo)
transaction() helper con auto-rollback

Pragmas y Configuracion

setBusyTimeout
setJournalMode/setSynchronous
enableWalMode
setForeignKeys
setLimit/getLimit
optimize()

ATTACH/DETACH

attach()/attachMemory()/detach()
listDatabases()

Backup API

Backup struct completo
backupDatabase/backupToFile/loadFromFile

Blob I/O

Blob.open/read/write/reopen/readAll

User-Defined Functions

Scalar functions
Aggregate functions
Window functions
Custom collations

Hooks y Callbacks

Commit/Rollback/Update hooks
Pre-update hook
Progress handler
Authorizer
Busy handler

File Control

getPersistWal/setPersistWal
setChunkSize
getDataVersion

VACUUM

vacuum()
vacuumInto(path) - VACUUM INTO file

FTS5 Full-Text Search

createSimpleTable/createTableWithTokenizer
search/searchWithHighlight/searchWithSnippet
rebuild/optimize/integrityCheck

JSON1 Extension

validate/isValid/getType
extract/extractInt/extractFloat/extractBool
insert/replace/set/setString/setInt/setFloat/setBool
remove
arrayLength/createArray/createObject
patch (RFC 7396)
each/tree (iteradores)

R-Tree Spatial Index

createSimpleTable2D/3D
insert2D/3D, insertPoint2D
queryIntersects2D/3D, queryContains2D
getIntersectingIds2D
BoundingBox2D/3D (intersects, containsPoint, area, expand)
GeoCoord (distanceKm con Haversine)

Virtual Tables API

VTableModule type
SimpleVTable helper
IndexConstraint/IndexOrderBy/IndexInfo
ResultHelper/ValueHelper
ColumnDef/generateSchema

Serialize/Deserialize API

toBytes() - Serializar DB a bytes
toBytesNoCopy() - Sin copia (puntero interno)
fromBytes() - Deserializar bytes a DB
fromBytesReadOnly() - DB read-only
deserializeInto() - Deserializar en DB existente
saveToFile/loadFromFile - Helpers para archivos
cloneToMemory() - Clonar DB en memoria
equals() - Comparar dos DBs
serializedSize() - Tamano sin copiar

Session Extension (Change Tracking)

Session.init/deinit - Crear/destruir session
Session.attach/attachAll - Trackear tablas
Session.setEnabled/isEnabled - Habilitar/deshabilitar
Session.setIndirect/isIndirect - Modo indirecto
Session.isEmpty - Verificar cambios
Session.changeset/patchset - Generar cambios
Session.diff - Diferencias entre DBs
applyChangeset() - Aplicar cambios
invertChangeset() - Invertir (para undo)
concatChangesets() - Concatenar cambios
ChangesetIterator - Iterar cambios
Rebaser - Rebase de cambios

Snapshot API (WAL mode)

Database.Snapshot - Handle de snapshot
getSnapshot() - Obtener snapshot actual
openSnapshot() - Abrir DB en snapshot
recoverSnapshot() - Recuperar snapshot

Connection Pool

ConnectionPool.init/deinit
acquire/release
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

# 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

# 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 - Principal inspiracion (Rust)
zig-sqlite - Row mapping comptime
zqlite.zig - Pool, thin wrapper
SQLite C API - Documentacion oficial
SQLite Session Extension
SQLite Backup API

zsqlite v1.0 - Wrapper SQLite completo para Zig 2025-12-08

8.9 KiB Raw Blame History