zcatsql/docs/API.md

zsqlite - API Reference

Version: 0.3 Ultima actualizacion: 2025-12-08

Quick Reference

const sqlite = @import("zsqlite");

// Abrir base de datos
var db = try sqlite.openMemory();          // In-memory
var db = try sqlite.open("file.db");       // Archivo
defer db.close();

// SQL directo
try db.exec("CREATE TABLE ...");

// Prepared statement
var stmt = try db.prepare("SELECT * FROM users WHERE id = ?");
defer stmt.finalize();
try stmt.bindInt(1, 42);
while (try stmt.step()) {
    const name = stmt.columnText(1);
}

// Named parameters
var stmt = try db.prepare("INSERT INTO users VALUES (:name, :age)");
try stmt.bindTextNamed(":name", "Alice");
try stmt.bindIntNamed(":age", 30);

// Transacciones
try db.begin();
// ... operaciones ...
try db.commit();  // o db.rollback()

// Savepoints
try db.savepoint(allocator, "sp1");
try db.rollbackTo(allocator, "sp1");
try db.release(allocator, "sp1");

// Backup
try sqlite.backupToFile(&db, "backup.db");
var restored = try sqlite.loadFromFile("backup.db");

// User-defined functions
try db.createScalarFunction("double", 1, myDoubleFunc);

// Custom collations
try db.createCollation("NOCASE2", myCaseInsensitiveCompare);

---

Funciones de Modulo

open

pub fn open(path: [:0]const u8) Error!Database

Abre una base de datos SQLite.

Parametros:

• path: Ruta al archivo. Usar ":memory:" para base de datos en memoria.

Retorna: Database o error.

---

openMemory

pub fn openMemory() Error!Database

Abre una base de datos en memoria.

---

version / versionNumber

pub fn version() []const u8
pub fn versionNumber() i32

Retorna la version de SQLite como string ("3.47.2") o numero (3047002).

---

backupDatabase

pub fn backupDatabase(dest_db: *Database, source_db: *Database) Error!void

Copia una base de datos completa a otra.

---

backupToFile

pub fn backupToFile(source_db: *Database, path: [:0]const u8) Error!void

Guarda una base de datos a un archivo.

---

loadFromFile

pub fn loadFromFile(path: [:0]const u8) Error!Database

Carga una base de datos desde archivo a memoria.

---

Database

Apertura y Cierre

Funcion	Descripcion
open(path)	Abre conexion (read-write, create)
openWithFlags(path, flags)	Abre con flags especificos
close()	Cierra la conexion

Ejecucion SQL

Funcion	Descripcion
exec(sql)	Ejecuta SQL sin resultados
execAlloc(alloc, sql)	exec con string runtime
prepare(sql)	Crea prepared statement
prepareAlloc(alloc, sql)	prepare con string runtime

Transacciones

Funcion	Descripcion
begin()	Inicia transaccion (DEFERRED)
beginImmediate()	Inicia con lock inmediato
beginExclusive()	Inicia con lock exclusivo
commit()	Confirma transaccion
rollback()	Revierte transaccion

Savepoints

pub fn savepoint(self: *Database, allocator: Allocator, name: []const u8) !void
pub fn release(self: *Database, allocator: Allocator, name: []const u8) !void
pub fn rollbackTo(self: *Database, allocator: Allocator, name: []const u8) !void

Savepoints permiten transacciones anidadas.

Ejemplo:

try db.begin();
try db.savepoint(alloc, "sp1");
try db.exec("INSERT ...");
try db.rollbackTo(alloc, "sp1");  // Revierte INSERT
try db.release(alloc, "sp1");
try db.commit();

Configuracion

Funcion	Descripcion
setForeignKeys(enabled)	Habilita/deshabilita FKs
setBusyTimeout(ms)	Timeout en ms para locks
setJournalMode(alloc, mode)	"WAL", "DELETE", etc
setSynchronous(alloc, mode)	"OFF", "NORMAL", "FULL"
enableWalMode(alloc)	WAL + NORMAL sync

ATTACH/DETACH

pub fn attach(self: *Database, alloc: Allocator, path: []const u8, schema: []const u8) !void
pub fn attachMemory(self: *Database, alloc: Allocator, schema: []const u8) !void
pub fn detach(self: *Database, alloc: Allocator, schema: []const u8) !void
pub fn listDatabases(self: *Database, alloc: Allocator) ![][]const u8
pub fn freeDatabaseList(alloc: Allocator, list: [][]const u8) void

Ejemplo:

try db.attachMemory(alloc, "cache");
try db.exec("CREATE TABLE cache.items (...)");
// SELECT * FROM cache.items
try db.detach(alloc, "cache");

User-Defined Functions

pub fn createScalarFunction(
    self: *Database,
    name: [:0]const u8,
    num_args: i32,
    func: ScalarFn,
) !void

pub fn removeFunction(self: *Database, name: [:0]const u8, num_args: i32) Error!void

Ejemplo:

fn myDouble(ctx: FunctionContext, args: []const FunctionValue) void {
    if (args[0].isNull()) {
        ctx.setNull();
        return;
    }
    ctx.setInt(args[0].asInt() * 2);
}

try db.createScalarFunction("double", 1, myDouble);
// SELECT double(value) FROM table

Custom Collations

pub fn createCollation(self: *Database, name: [:0]const u8, func: CollationFn) !void
pub fn removeCollation(self: *Database, name: [:0]const u8) Error!void

Ejemplo:

fn reverseOrder(a: []const u8, b: []const u8) i32 {
    return -std.mem.order(u8, a, b);
}

try db.createCollation("REVERSE", reverseOrder);
// SELECT * FROM table ORDER BY name COLLATE REVERSE

Utilidades

Funcion	Descripcion
lastInsertRowId()	Ultimo rowid insertado
changes()	Filas modificadas (ultimo stmt)
totalChanges()	Total filas desde conexion
errorMessage()	Mensaje de error reciente
errorCode()	Codigo de error
extendedErrorCode()	Codigo extendido
interrupt()	Interrumpe operacion
isReadOnly(db_name)	Si DB es readonly
filename(db_name)	Ruta del archivo

---

Statement

Ciclo de Vida

Funcion	Descripcion
finalize()	Libera el statement
reset()	Resetea para re-ejecucion
clearBindings()	Limpia parametros
step()	Ejecuta un paso (true=hay fila)

Metadata

Funcion	Descripcion
sql()	Texto SQL del statement
isReadOnly()	Si es SELECT
parameterCount()	Numero de parametros
parameterIndex(name)	Indice de parametro named
parameterName(index)	Nombre de parametro

Bind Parameters (1-indexed)

Funcion	Descripcion
bindNull(idx)	NULL
bindInt(idx, val)	i64
bindFloat(idx, val)	f64
bindText(idx, val)	[]const u8
bindBlob(idx, val)	[]const u8
bindBool(idx, val)	bool (como 0/1)
bindZeroblob(idx, size)	Blob de ceros

Named Parameters

Funcion	Descripcion
bindNullNamed(name)	:name, @name, $name
bindIntNamed(name, val)
bindFloatNamed(name, val)
bindTextNamed(name, val)
bindBlobNamed(name, val)
bindBoolNamed(name, val)

Column Access (0-indexed)

Funcion	Descripcion
columnCount()	Numero de columnas
columnName(idx)	Nombre
columnType(idx)	ColumnType enum
columnInt(idx)	i64
columnFloat(idx)	f64
columnText(idx)	?[]const u8
columnBlob(idx)	?[]const u8
columnBool(idx)	bool
columnIsNull(idx)	bool
columnBytes(idx)	Tamano en bytes
columnDeclType(idx)	Tipo declarado

---

Backup

pub const Backup = struct {
    pub fn init(dest: *Database, dest_name: [:0]const u8,
                source: *Database, source_name: [:0]const u8) Error!Backup
    pub fn initMain(dest: *Database, source: *Database) Error!Backup
    pub fn step(self: *Backup, n_pages: i32) Error!bool
    pub fn stepAll(self: *Backup) Error!void
    pub fn remaining(self: *Backup) i32
    pub fn pageCount(self: *Backup) i32
    pub fn progress(self: *Backup) u8  // 0-100
    pub fn finish(self: *Backup) Error!void
    pub fn deinit(self: *Backup) void
};

Ejemplo con progreso:

var backup = try Backup.initMain(&dest_db, &source_db);
defer backup.deinit();

while (try backup.step(100)) {
    std.debug.print("Progress: {}%\n", .{backup.progress()});
}

---

User-Defined Functions

FunctionContext

pub const FunctionContext = struct {
    pub fn setNull(self: Self) void
    pub fn setInt(self: Self, value: i64) void
    pub fn setFloat(self: Self, value: f64) void
    pub fn setText(self: Self, value: []const u8) void
    pub fn setBlob(self: Self, value: []const u8) void
    pub fn setError(self: Self, msg: []const u8) void
};

FunctionValue

pub const FunctionValue = struct {
    pub fn getType(self: Self) ColumnType
    pub fn isNull(self: Self) bool
    pub fn asInt(self: Self) i64
    pub fn asFloat(self: Self) f64
    pub fn asText(self: Self) ?[]const u8
    pub fn asBlob(self: Self) ?[]const u8
};

ScalarFn Type

pub const ScalarFn = *const fn (ctx: FunctionContext, args: []const FunctionValue) void;

---

Types

OpenFlags

pub const OpenFlags = struct {
    read_only: bool = false,
    read_write: bool = true,
    create: bool = true,
    uri: bool = false,
    memory: bool = false,
    no_mutex: bool = false,
    full_mutex: bool = false,
};

ColumnType

pub const ColumnType = enum {
    integer,
    float,
    text,
    blob,
    null_value,
};

CollationFn

pub const CollationFn = *const fn (a: []const u8, b: []const u8) i32;

Retorna: negativo si a < b, cero si a == b, positivo si a > b.

Error

Mapeo completo de codigos SQLite:

Error	Descripcion
SqliteError	Error generico
Busy	Database bloqueada
Locked	Tabla bloqueada
Constraint	Violacion de constraint
OutOfMemory	Sin memoria
IoError	Error de I/O
Corrupt	DB corrupta
CantOpen	No se puede abrir
ReadOnly	DB es readonly
Range	Parametro fuera de rango
...	(25+ errores mapeados)

---

Ejemplos Completos

CRUD con Named Parameters

var db = try sqlite.openMemory();
defer db.close();

try db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)");

// Insert con named params
var insert = try db.prepare("INSERT INTO users (name, age) VALUES (:name, :age)");
defer insert.finalize();

try insert.bindTextNamed(":name", "Alice");
try insert.bindIntNamed(":age", 30);
_ = try insert.step();

// Query
var query = try db.prepare("SELECT * FROM users WHERE age > :min_age");
defer query.finalize();

try query.bindIntNamed(":min_age", 25);
while (try query.step()) {
    const name = query.columnText(1) orelse "(null)";
    std.debug.print("User: {s}\n", .{name});
}

Backup con Progreso

var source = try sqlite.open("production.db");
defer source.close();

var dest = try sqlite.open("backup.db");
defer dest.close();

var backup = try sqlite.Backup.initMain(&dest, &source);
defer backup.deinit();

while (try backup.step(100)) {
    const pct = backup.progress();
    std.debug.print("\rBackup: {d}%", .{pct});
}
std.debug.print("\nBackup complete!\n", .{});

UDF: String Length

fn strLen(ctx: sqlite.FunctionContext, args: []const sqlite.FunctionValue) void {
    if (args.len != 1 or args[0].isNull()) {
        ctx.setNull();
        return;
    }
    if (args[0].asText()) |text| {
        ctx.setInt(@intCast(text.len));
    } else {
        ctx.setNull();
    }
}

try db.createScalarFunction("strlen", 1, strLen);
// SELECT strlen(name) FROM users

Collation: Case-Insensitive

fn caseInsensitive(a: []const u8, b: []const u8) i32 {
    var i: usize = 0;
    while (i < a.len and i < b.len) : (i += 1) {
        const ca = std.ascii.toLower(a[i]);
        const cb = std.ascii.toLower(b[i]);
        if (ca < cb) return -1;
        if (ca > cb) return 1;
    }
    if (a.len < b.len) return -1;
    if (a.len > b.len) return 1;
    return 0;
}

try db.createCollation("ICASE", caseInsensitive);
// SELECT * FROM users ORDER BY name COLLATE ICASE

---

© zsqlite v0.3 - API Reference 2025-12-08