Datos y ORM¶
Database¶
Database es la capa SQLite incluida. Por defecto funciona bien como embebida
para demos, herramientas locales y servicios pequenos o medianos.
Constructor tipico:
from wsbuilder import Database
db = Database(
"data/app.sqlite3",
enable_replicas=True,
replica_count=2,
enable_wal=True,
cache_size_mb=10,
)
cache_size_mb se interpreta en MiB reales y se traduce al PRAGMA cache_size
de SQLite en KiB, que es la unidad esperada por SQLite cuando el valor es
negativo.
Capacidades principales:
execute,executemany,fetchone,fetchall,scalar.transaction()para bloques transaccionales.read_replica_*para lecturas balanceadas.set_pragma,get_pragma,checkpoint,vacuum,optimize.
set_pragma (y los pragmas del constructor, de las replicas y del cache)
solo acepta numeros, booleanos o una palabra clave simple como WAL o
NORMAL; cualquier otro valor lanza ValueError, porque los PRAGMA no admiten
parametros enlazados.
Los lotes de escritura ejecutados con executemany son atomicos: si una fila
falla, el prefijo ya procesado se revierte. replica_count debe ser mayor que
cero cuando se construye un pool de replicas.
Modelos¶
from datetime import UTC, datetime
from wsbuilder import DateTimeField, IntegerField, JSONField, Model, TextField
class Article(Model):
__tablename__ = "articles"
id = IntegerField(primary_key=True, auto_increment=True)
title = TextField(null=False, index=True)
body = TextField(default="", null=False)
tags = JSONField(default=list, null=False)
created_at = DateTimeField(default=lambda: datetime.now(UTC), null=False)
Operaciones tipicas:
Article.create_table(db)
Article.create(db, title="Hola", body="Contenido", tags=["docs"])
first = Article.get(db, id=1)
rows = Article.objects(db).filter(title__startswith="H").order_by("-id").all()
QuerySet¶
Operadores soportados:
field=valuefield__ne=valuefield__gt=valuefield__gte=valuefield__lt=valuefield__lte=valuefield__like=valuefield__ilike=valuefield__contains=valuefield__icontains=valuefield__startswith=valuefield__istartswith=valuefield__endswith=valuefield__iendswith=valuefield__in=[...]field__not_in=[...]field__isnull=True
like e ilike reciben un patron SQL (% y _ son comodines). contains,
startswith y endswith comparan el valor literal y distinguen mayusculas;
sus variantes i* tambien son literales pero ignoran mayusculas ASCII.
Metodos utiles:
filter,excludeorder_by,order_by_rawlimit,offset,paginateall,first,get,valuescount,exists,update,delete,createwhere_raw,using
update() y delete() respetan el slice: con limit u offset (y su
order_by) solo cambian las filas que seleccionaria la consulta, mediante una
subconsulta por clave primaria (o rowid si el modelo no declara una). Asi
Note.objects(db).order_by("-id").limit(1).delete() borra una sola fila. Sin
slice el WHERE es el de los filtros, como antes.
Ejemplo con replica de lectura:
rows = Article.objects(db).using("replica").order_by("-id").limit(20).all()
Los querysets con using("replica") son de solo lectura: update(),
delete() y create() levantan error.
Transacciones¶
with db.transaction():
Article.create(db, title="A")
Article.create(db, title="B")
Las transacciones se integran con save() y delete() de los modelos. Como
Database comparte una conexion SQLite entre hilos, una transaccion exterior
mantiene el bloqueo de esa conexion hasta terminar; otros hilos esperan y no
pueden confirmar ni revertir trabajo ajeno. Las transacciones anidadas usan
savepoints.
Campos incluidos¶
IntegerFieldRealFieldTextFieldBlobFieldBooleanFieldDateTimeFieldJSONField
Opciones comunes de campos:
primary_keyuniquenulldefaultindexauto_incrementenIntegerField
DateTimeField serializa valores datetime en ISO 8601 y los reconstruye al
leer. JSONField guarda estructuras JSON compatibles.
Tambien existen helpers SQL:
SQLcreate_tablesdrop_tablesquote_identifiervalidate_identifier
Lecturas optimizadas y replicas¶
db_replicas.py amplia el escenario SQLite:
SQLite3OptimizationConfig: pragmas y ajustes de rendimiento.DatabaseReplica: conexion de solo lectura.DatabaseReplicaPool: pool round-robin para lecturas.OptimizedDatabase: base optimizada con replicas activas por defecto.
Usa OptimizedDatabase cuando quieres dejar activados WAL, cache y replicas con
un constructor mas orientado a throughput de lectura.
from wsbuilder import OptimizedDatabase, SQLite3OptimizationConfig
config = SQLite3OptimizationConfig(cache_size=32768, wal_autocheckpoint=500)
db = OptimizedDatabase(
"data/app.sqlite3",
optimization_config=config,
enable_replicas=True,
replica_count=4,
)
Notas:
- las replicas no se crean para
:memory:. replica_countdebe ser mayor que cero.- las replicas usan conexiones read-only.
- las escrituras deben ejecutarse en la conexion principal.