reugenio/zcatsql
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
zcatsql/docs/CGO_PARITY_ANALYSIS.md
reugenio 532cf827f8 v0.3: Fase 2A+2B complete - Major feature additions 
New features:
- Backup API: Backup struct with step(), progress(), remaining(), pageCount()
- Convenience functions: backupToFile(), loadFromFile(), backupDatabase()
- ATTACH/DETACH: attach(), attachMemory(), detach(), listDatabases()
- User-Defined Functions: createScalarFunction(), FunctionContext, FunctionValue
- Custom Collations: createCollation(), CollationFn, removeCollation()
- Named parameters: bindTextNamed(), bindIntNamed(), etc. (:name, @name, $name)
- Savepoints: savepoint(), release(), rollbackTo()
- Configuration: setBusyTimeout(), setJournalMode(), setSynchronous(), enableWalMode()
- Statement metadata: sql(), isReadOnly(), parameterCount(), parameterIndex()
- Transaction: beginExclusive()
- Utilities: errorCode(), extendedErrorCode(), interrupt(), isReadOnly(), filename()
- Additional bind/column: bindBool(), bindZeroblob(), columnBool(), columnBytes(), columnDeclType()

Documentation:
- Created docs/API.md - Complete API reference
- Created docs/ARCHITECTURE.md - Technical architecture
- Created docs/CGO_PARITY_ANALYSIS.md - Feature parity tracking with go-sqlite3
- Updated CLAUDE.md with all new features

All 20 tests passing.

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-08 17:54:50 +01:00

334 lines
9.4 KiB
Markdown
Raw Blame History

# Analisis de Paridad con CGo go-sqlite3
> **Fecha**: 2025-12-08
> **Objetivo**: Identificar todas las funcionalidades de go-sqlite3 para replicarlas en zsqlite
## Resumen
go-sqlite3 (https://github.com/mattn/go-sqlite3) es el wrapper SQLite mas maduro para Go.
Este documento analiza todas sus funcionalidades para asegurar paridad en zsqlite.
---
## Estado de Implementacion
### Leyenda
- ✅ Implementado en zsqlite
- ⏳ Pendiente de implementar
- 🔄 Parcialmente implementado
- ❌ No aplicable a Zig
---
## 1. Conexion a Base de Datos
| Funcionalidad | go-sqlite3 | zsqlite | Notas |
|---------------|------------|---------|-------|
| Open basico | ✅ | ✅ | `sqlite.open()` |
| Open con flags | ✅ | ✅ | `Database.openWithFlags()` |
| Close | ✅ | ✅ | `db.close()` |
| URI connection string | ✅ | ⏳ | Parsear `file:path?mode=ro&cache=shared` |
| DSN parameters | ✅ | ⏳ | Configuracion via string |
| Connection pooling | ✅ (via database/sql) | ⏳ | Pool propio |
---
## 2. Configuracion de Pragmas
| Pragma | go-sqlite3 | zsqlite | Prioridad |
|--------|------------|---------|-----------|
| auto_vacuum | ✅ | ⏳ | Media |
| busy_timeout | ✅ | ✅ | `db.setBusyTimeout()` |
| cache_size | ✅ | ⏳ | Media |
| case_sensitive_like | ✅ | ⏳ | Baja |
| defer_foreign_keys | ✅ | ⏳ | Media |
| foreign_keys | ✅ | ✅ | `db.setForeignKeys()` |
| journal_mode | ✅ | ✅ | `db.setJournalMode()` |
| locking_mode | ✅ | ⏳ | Media |
| query_only | ✅ | ⏳ | Baja |
| recursive_triggers | ✅ | ⏳ | Baja |
| secure_delete | ✅ | ⏳ | Baja |
| synchronous | ✅ | ✅ | `db.setSynchronous()` |
---
## 3. Prepared Statements
| Funcionalidad | go-sqlite3 | zsqlite | Notas |
|---------------|------------|---------|-------|
| Prepare | ✅ | ✅ | `db.prepare()` |
| Exec (sin resultados) | ✅ | ✅ | `db.exec()` |
| Query (con resultados) | ✅ | ✅ | `stmt.step()` loop |
| Bind posicional (?) | ✅ | ✅ | `stmt.bindInt(1, val)` |
| Bind named (:name) | ✅ | ✅ | `stmt.bindIntNamed(":name", val)` |
| Bind named (@name) | ✅ | ✅ | `stmt.bindIntNamed("@name", val)` |
| Bind named ($name) | ✅ | ✅ | `stmt.bindIntNamed("$name", val)` |
| Readonly check | ✅ | ✅ | `stmt.isReadOnly()` |
| SQL text | ✅ | ✅ | `stmt.sql()` |
| Expanded SQL | ✅ | ⏳ | `sqlite3_expanded_sql()` |
---
## 4. Bind de Parametros
| Tipo | go-sqlite3 | zsqlite | Notas |
|------|------------|---------|-------|
| NULL | ✅ | ✅ | `stmt.bindNull()` |
| int64 | ✅ | ✅ | `stmt.bindInt()` |
| float64 | ✅ | ✅ | `stmt.bindFloat()` |
| string/text | ✅ | ✅ | `stmt.bindText()` |
| []byte/blob | ✅ | ✅ | `stmt.bindBlob()` |
| bool | ✅ | ✅ | `stmt.bindBool()` |
| time.Time | ✅ | ⏳ | Formatear como string ISO8601 |
| Zeroblob | ✅ | ✅ | `stmt.bindZeroblob()` |
---
## 5. Lectura de Columnas
| Tipo | go-sqlite3 | zsqlite | Notas |
|------|------------|---------|-------|
| Column count | ✅ | ✅ | `stmt.columnCount()` |
| Column name | ✅ | ✅ | `stmt.columnName()` |
| Column type | ✅ | ✅ | `stmt.columnType()` |
| int64 | ✅ | ✅ | `stmt.columnInt()` |
| float64 | ✅ | ✅ | `stmt.columnFloat()` |
| text | ✅ | ✅ | `stmt.columnText()` |
| blob | ✅ | ✅ | `stmt.columnBlob()` |
| NULL check | ✅ | ✅ | `stmt.columnIsNull()` |
| Column bytes | ✅ | ✅ | `stmt.columnBytes()` |
| Declared type | ✅ | ✅ | `stmt.columnDeclType()` |
| Database name | ✅ | ⏳ | `sqlite3_column_database_name()` |
| Table name | ✅ | ⏳ | `sqlite3_column_table_name()` |
| Origin name | ✅ | ⏳ | `sqlite3_column_origin_name()` |
---
## 6. Transacciones
| Funcionalidad | go-sqlite3 | zsqlite | Notas |
|---------------|------------|---------|-------|
| BEGIN | ✅ | ✅ | `db.begin()` |
| BEGIN IMMEDIATE | ✅ | ✅ | `db.beginImmediate()` |
| BEGIN EXCLUSIVE | ✅ | ✅ | `db.beginExclusive()` |
| BEGIN DEFERRED | ✅ | ✅ | `db.begin()` (default) |
| COMMIT | ✅ | ✅ | `db.commit()` |
| ROLLBACK | ✅ | ✅ | `db.rollback()` |
| SAVEPOINT | ✅ | ✅ | `db.savepoint(alloc, "name")` |
| RELEASE | ✅ | ✅ | `db.release(alloc, "name")` |
| ROLLBACK TO | ✅ | ✅ | `db.rollbackTo(alloc, "name")` |
---
## 7. Metadatos y Utilidades
| Funcionalidad | go-sqlite3 | zsqlite | Notas |
|---------------|------------|---------|-------|
| LastInsertRowId | ✅ | ✅ | `db.lastInsertRowId()` |
| Changes | ✅ | ✅ | `db.changes()` |
| TotalChanges | ✅ | ✅ | `db.totalChanges()` |
| Error message | ✅ | ✅ | `db.errorMessage()` |
| Error code | ✅ | ✅ | `db.errorCode()` |
| Extended error code | ✅ | ✅ | `db.extendedErrorCode()` |
| SQLite version | ✅ | ✅ | `sqlite.version()` |
| Version number | ✅ | ✅ | `sqlite.versionNumber()` |
| Database filename | ✅ | ✅ | `db.filename()` |
| Is readonly | ✅ | ✅ | `db.isReadOnly()` |
---
## 8. Limites y Control
| Funcionalidad | go-sqlite3 | zsqlite | Prioridad |
|---------------|------------|---------|-----------|
| GetLimit | ✅ | ⏳ | Baja |
| SetLimit | ✅ | ⏳ | Baja |
| SetFileControlInt | ✅ | ⏳ | Baja |
| Interrupt | ✅ | ✅ | `db.interrupt()` |
---
## 9. Callbacks y Hooks
| Funcionalidad | go-sqlite3 | zsqlite | Prioridad |
|---------------|------------|---------|-----------|
| Commit hook | ✅ | ⏳ | Media |
| Rollback hook | ✅ | ⏳ | Media |
| Update hook | ✅ | ⏳ | Media |
| Pre-update hook | ✅ | ⏳ | Baja |
| Authorizer | ✅ | ⏳ | Baja |
| Progress handler | ✅ | ⏳ | Baja |
| Busy handler | ✅ | ⏳ | Media |
| Busy timeout | ✅ | ✅ | `db.setBusyTimeout()` |
---
## 10. Funciones Personalizadas
| Funcionalidad | go-sqlite3 | zsqlite | Prioridad |
|---------------|------------|---------|-----------|
| RegisterFunc (scalar) | ✅ | ✅ | `db.createScalarFunction()` |
| RegisterAggregator | ✅ | ⏳ | Media |
| RegisterCollation | ✅ | ✅ | `db.createCollation()` |
| User-defined window func | ✅ | ⏳ | Baja |
---
## 11. Backup API
| Funcionalidad | go-sqlite3 | zsqlite | Prioridad |
|---------------|------------|---------|-----------|
| Backup init | ✅ | ✅ | `Backup.init()` |
| Backup step | ✅ | ✅ | `backup.step()` |
| Backup finish | ✅ | ✅ | `backup.finish()` |
| Backup remaining | ✅ | ✅ | `backup.remaining()` |
| Backup pagecount | ✅ | ✅ | `backup.pageCount()` |
---
## 12. Blob I/O
| Funcionalidad | go-sqlite3 | zsqlite | Prioridad |
|---------------|------------|---------|-----------|
| Blob open | ✅ | ⏳ | Media |
| Blob close | ✅ | ⏳ | Media |
| Blob read | ✅ | ⏳ | Media |
| Blob write | ✅ | ⏳ | Media |
| Blob bytes | ✅ | ⏳ | Media |
| Blob reopen | ✅ | ⏳ | Baja |
---
## 13. Extensiones
| Funcionalidad | go-sqlite3 | zsqlite | Notas |
|---------------|------------|---------|-------|
| Load extension | ✅ | ❌ | Deshabilitado por seguridad |
| Enable load ext | ✅ | ❌ | |
---
## Plan de Implementacion
### Fase 2A - Prioridad Alta ✅ COMPLETADA
1. ✅ Busy timeout/handler - `db.setBusyTimeout()`
2. ✅ WAL mode (journal_mode pragma) - `db.setJournalMode()`, `db.enableWalMode()`
3. ✅ Named parameters - `stmt.bindTextNamed()`, etc.
4. ✅ SAVEPOINT/RELEASE/ROLLBACK TO - `db.savepoint()`, etc.
5. ✅ BEGIN EXCLUSIVE - `db.beginExclusive()`
### Fase 2B - Prioridad Alta ✅ COMPLETADA
1. ✅ Backup API completo - `Backup` struct, `backupToFile()`, `loadFromFile()`
2. ✅ User-defined functions (scalar) - `db.createScalarFunction()`
3. ✅ Collations personalizadas - `db.createCollation()`
4. ✅ ATTACH/DETACH - `db.attach()`, `db.detach()`, `db.listDatabases()`
### Fase 3A - Prioridad Media (Siguiente)
1. ⏳ Blob I/O streaming
2. ⏳ Hooks (commit, rollback, update)
3. ⏳ Aggregator functions
4. ⏳ Mas pragmas
### Fase 3B - Prioridad Baja
1. ⏳ Authorizer
2. ⏳ Progress handler
3. ⏳ Pre-update hook
4. ⏳ Window functions
5. ⏳ Limits API
---
## Funciones SQLite C Relevantes (Referencia)
```c
// Conexion
sqlite3_open_v2()
sqlite3_close_v2()
// Statements
sqlite3_prepare_v2()
sqlite3_finalize()
sqlite3_reset()
sqlite3_clear_bindings()
sqlite3_step()
sqlite3_sql()
sqlite3_expanded_sql()
sqlite3_stmt_readonly()
// Bind
sqlite3_bind_parameter_index()
sqlite3_bind_parameter_name()
sqlite3_bind_null()
sqlite3_bind_int64()
sqlite3_bind_double()
sqlite3_bind_text()
sqlite3_bind_blob()
sqlite3_bind_zeroblob()
// Column
sqlite3_column_count()
sqlite3_column_name()
sqlite3_column_type()
sqlite3_column_int64()
sqlite3_column_double()
sqlite3_column_text()
sqlite3_column_blob()
sqlite3_column_bytes()
sqlite3_column_decltype()
sqlite3_column_database_name()
sqlite3_column_table_name()
sqlite3_column_origin_name()
// Utilidades
sqlite3_last_insert_rowid()
sqlite3_changes()
sqlite3_total_changes()
sqlite3_errmsg()
sqlite3_errcode()
sqlite3_extended_errcode()
sqlite3_libversion()
sqlite3_libversion_number()
sqlite3_db_filename()
sqlite3_db_readonly()
// Busy
sqlite3_busy_timeout()
sqlite3_busy_handler()
// Hooks
sqlite3_commit_hook()
sqlite3_rollback_hook()
sqlite3_update_hook()
sqlite3_preupdate_hook()
// Funciones
sqlite3_create_function_v2()
sqlite3_create_collation_v2()
sqlite3_create_window_function()
// Backup
sqlite3_backup_init()
sqlite3_backup_step()
sqlite3_backup_finish()
sqlite3_backup_remaining()
sqlite3_backup_pagecount()
// Blob
sqlite3_blob_open()
sqlite3_blob_close()
sqlite3_blob_read()
sqlite3_blob_write()
sqlite3_blob_bytes()
sqlite3_blob_reopen()
// Control
sqlite3_interrupt()
sqlite3_limit()
sqlite3_progress_handler()
sqlite3_set_authorizer()
```
---
**© zsqlite - CGo Parity Analysis**
*2025-12-08*
Reference in a new issue View git blame Copy permalink