zcatsql/docs/CGO_PARITY_ANALYSIS.md

Analisis de Paridad con CGo go-sqlite3

Fecha: 2025-12-08 Objetivo: Identificar todas las funcionalidades de go-sqlite3 para replicarlas en zcatsql

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 zcatsql.

---

Estado de Implementacion

Leyenda

• ✅ Implementado en zcatsql
• ⏳ Pendiente de implementar
• 🔄 Parcialmente implementado
• ❌ No aplicable a Zig

---

1. Conexion a Base de Datos

Funcionalidad	go-sqlite3	zcatsql	Notas
Open basico	✅	✅	sqlite.open()
Open con flags	✅	✅	Database.openWithFlags()
Close	✅	✅	db.close()
URI connection string	✅	✅	db.openUri() soporta file:path?mode=ro&cache=shared
DSN parameters	✅	✅	Via URI connection string
Connection pooling	✅ (via database/sql)	✅	ConnectionPool struct

---

2. Configuracion de Pragmas

Pragma	go-sqlite3	zcatsql	Prioridad
auto_vacuum	✅	✅	db.setAutoVacuum()
busy_timeout	✅	✅	db.setBusyTimeout()
cache_size	✅	✅	db.setCacheSize()
case_sensitive_like	✅	✅	db.setCaseSensitiveLike()
defer_foreign_keys	✅	✅	db.setDeferForeignKeys()
foreign_keys	✅	✅	db.setForeignKeys()
journal_mode	✅	✅	db.setJournalMode()
locking_mode	✅	✅	db.setLockingMode()
query_only	✅	✅	db.setQueryOnly()
recursive_triggers	✅	✅	db.setRecursiveTriggers()
secure_delete	✅	✅	db.setSecureDelete()
synchronous	✅	✅	db.setSynchronous()

---

3. Prepared Statements

Funcionalidad	go-sqlite3	zcatsql	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	✅	✅	stmt.expandedSql()

---

4. Bind de Parametros

Tipo	go-sqlite3	zcatsql	Notas
NULL	✅	✅	stmt.bindNull()
int64	✅	✅	stmt.bindInt()
float64	✅	✅	stmt.bindFloat()
string/text	✅	✅	stmt.bindText()
[]byte/blob	✅	✅	stmt.bindBlob()
bool	✅	✅	stmt.bindBool()
time.Time	✅	✅	stmt.bindTimestamp() ISO8601
Zeroblob	✅	✅	stmt.bindZeroblob()

---

5. Lectura de Columnas

Tipo	go-sqlite3	zcatsql	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	✅	✅	stmt.columnDatabaseName()
Table name	✅	✅	stmt.columnTableName()
Origin name	✅	✅	stmt.columnOriginName()

---

6. Transacciones

Funcionalidad	go-sqlite3	zcatsql	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	zcatsql	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	zcatsql	Prioridad
GetLimit	✅	✅	db.getLimit()
SetLimit	✅	✅	db.setLimit()
SetFileControlInt	✅	⏳	Baja
Interrupt	✅	✅	db.interrupt()

---

9. Callbacks y Hooks

Funcionalidad	go-sqlite3	zcatsql	Prioridad
Commit hook	✅	✅	db.setCommitHook()
Rollback hook	✅	✅	db.setRollbackHook()
Update hook	✅	✅	db.setUpdateHook()
Pre-update hook	✅	✅	db.setPreUpdateHook()
Authorizer	✅	✅	db.setAuthorizer()
Progress handler	✅	✅	db.setProgressHandler()
Busy handler	✅	✅	db.setBusyHandler()
Busy timeout	✅	✅	db.setBusyTimeout()

---

10. Funciones Personalizadas

Funcionalidad	go-sqlite3	zcatsql	Prioridad
RegisterFunc (scalar)	✅	✅	db.createScalarFunction()
RegisterAggregator	✅	✅	db.createAggregateFunction()
RegisterCollation	✅	✅	db.createCollation()
User-defined window func	✅	✅	db.createWindowFunction()

---

11. Backup API

Funcionalidad	go-sqlite3	zcatsql	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	zcatsql	Prioridad
Blob open	✅	✅	Blob.open()
Blob close	✅	✅	blob.close()
Blob read	✅	✅	blob.read()
Blob write	✅	✅	blob.write()
Blob bytes	✅	✅	blob.bytes()
Blob reopen	✅	✅	blob.reopen()

---

13. Extensiones

Funcionalidad	go-sqlite3	zcatsql	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 ✅ COMPLETADA

1. ✅ Blob I/O streaming - Blob struct con read(), write(), reopen()
2. ✅ Hooks (commit, rollback, update) - db.setCommitHook(), etc.
3. ✅ Aggregator functions - db.createAggregateFunction()
4. ✅ Mas pragmas

Fase 3B - Prioridad Baja ✅ COMPLETADA

1. ✅ Authorizer - db.setAuthorizer()
2. ✅ Progress handler - db.setProgressHandler()
3. ✅ Pre-update hook - db.setPreUpdateHook()
4. ✅ Limits API - db.getLimit(), db.setLimit()
5. ✅ Busy handler (custom callback) - db.setBusyHandler()
6. ✅ Timestamp binding - stmt.bindTimestamp()
7. ✅ Column metadata - stmt.columnDatabaseName(), etc.
8. ✅ Expanded SQL - stmt.expandedSql()
9. ✅ Window functions - db.createWindowFunction()

Fase 4 - Paridad Completa ✅ COMPLETADA

1. ✅ Window functions - db.createWindowFunction() con xStep, xFinal, xValue, xInverse
2. ✅ URI connection string - db.openUri(), sqlite.openUri()
3. ✅ Pragmas adicionales - setAutoVacuum, setCacheSize, setLockingMode, etc.
4. ✅ Connection pooling - ConnectionPool struct con acquire/release
5. ✅ Maintenance - vacuum(), optimize(), integrityCheck(), walCheckpoint()

---

Funciones SQLite C Relevantes (Referencia)

// 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()

---

© zcatsql - CGo Parity Analysis 2025-12-08