ORM asíncrono de interfaz unificada para SQLite, MySQL, MariaDB,
PostgreSQL, SQL Server y Oracle, construido sobre pydantic. Proporciona un modelo de datos declarativo, CRUD
tipado, validación, relaciones (1:1 y 1:N), consultas con filtros y agregados,
migraciones, y capas opcionales de producto: REST (FastAPI), GraphQL
(Strawberry), seguridad (RBAC + JWT) y generación de código desde la base de
datos.
Estado: experimental (v0.3.0). encino_orm se encuentra en fase experimental: la API pública y su comportamiento pueden cambiar sin previo aviso en versiones posteriores, sin garantía de compatibilidad retroactiva. El núcleo ORM está probado sobre los tres motores (más de 350 pruebas, con integraciones reales de MySQL y PostgreSQL), pero no se recomienda depender de una API estable en producción. Documentación de usuario en
docs/; el detalle de los cambios incompatibles de esta versión vive en CHANGELOG.md y en la guía de migración a 0.3.0.
- Seis motores con un único API:
SqliteDb,MysqlDb,MariadbDb,PostgresDb,MssqlDbyOracleDb, y un pool de conexionesPoolDbcon transacciones atómicas porcontextvar. - Modelos declarativos basados en
pydantic, con restricciones reutilizables (STR_100,INT_POS,CURRENCY,DATETIME,DECIMAL,JSON, …). - CRUD completo:
insert,save,upsert,load,update,delete,search,count,paginate,insert_many(bulk). - Claves primarias flexibles:
idauto-incremental (por defecto), clave natural simple o clave compuesta, y claves foráneas compuestas. - Relaciones: referencias 1:1, colecciones 1:N (
has_many), y carga por lotes (batch_reference/batch_has_many) para evitar N+1. - Consultas:
Filtercomponible yQueryBuilderconjoin,group_by, agregados (sum/avg/min/max/count) y subconsultas. - Esquema:
create_table, migraciones versionadas,diff_schemaysync_schema. - Hooks de ciclo de vida y caché (
CachedModel+CacheBackend). - Conexión implícita: un
ConnectionRegistryinyectable, másbindysession, eliminan la necesidad de pasardba cada instancia.set_default_db/get_default_dbsiguen disponibles pero están deprecados (emitenDeprecationWarning); usaConnectionRegistry(ver contexto). - Observabilidad:
trace_idpor request yQueryTracercon métricas. - Capas opcionales: REST (
create_crud), GraphQL (build_schema), seguridad (emit_token,require, RBAC tri-estado) y CLI/codegen (encino_orm generate models).
Para instalar la librería desde PyPI, fija la versión con ~=:
pip install "encino-orm~=0.2.6"El operador ~= acepta únicamente parches de la misma minor (0.2.x) y no
salta a la siguiente minor. Durante la ventana 0.x esto es esencial: pip
no trata las versiones 0.x como especiales para un rango abierto (>=),
de modo que pip install/pip install -U puede entrar en una minor nueva y
auto-instalar sus cambios incompatibles. Con encino-orm~=0.2.6, una futura
0.3.0 solo se instala si la pides explícitamente.
Para desarrollo sobre el repositorio, instala en modo editable:
# núcleo (SQLite + MySQL + MariaDB + PostgreSQL)
pip install -e .
# con extras opcionales
pip install -e ".[http,security,graphql]"
# caché en Redis (CachedModel + RedisCacheBackend)
pip install -e ".[cache]"
# motores opcionales (SQL Server / Oracle)
pip install -e ".[mssql,oracle]"Extras disponibles:
| Extra | Incluye |
|---|---|
http |
fastapi (REST CRUD) |
security |
fastapi + PyJWT (RBAC + JWT) |
graphql |
strawberry-graphql (GraphQL) |
cache |
redis (CachedModel + RedisCacheBackend) |
mssql |
aioodbc + pyodbc (SQL Server, requiere ODBC Driver 18) |
oracle |
oracledb (Oracle, modo thin) |
all-db |
mssql + oracle |
Requiere Python 3.10+.
import asyncio
from encino_orm import create_db
from encino_orm.model import Model, Filter, STR_100, INT_POS
class User(Model):
_table = "users"
name: STR_100(required=True)
age: INT_POS()
async def main():
db = await create_db("sqlite", database=":memory:")
await User.cursor(db).create_table() # genera el DDL y lo aplica
u = User(db, name="Ana", age=30)
await u.insert() # INSERT (id auto-incremental)
found = await User.cursor(db, id=u.id).load() # SELECT por clave primaria
assert found.name == "Ana"
adults = await User.cursor(db).search(Filter.ge("age", 18)) # SELECT ... WHERE age >= 18
assert len(adults) == 1
await db.close()Ejemplo completo (incluidos
Filtery las capas REST/GraphQL) endocs/getting-started.md.
| Documento | Contenido |
|---|---|
| Getting started | Instalación y primer modelo en 5 minutos. |
| Migración a 0.3.0 | Rupturas acumuladas desde 0.2.6, con pares Antes/Después y la acción concreta para adaptar tu código. |
| Guía de uso | Modelos, restricciones, CRUD, filtros, relaciones, claves primarias y foráneas. |
| Integraciones | REST, GraphQL, seguridad, codegen/CLI y observabilidad. |
| Agregar un motor | Guía para desarrolladores: cómo añadir un nuevo motor de base de datos. |
| Créditos | Herramientas y tecnologías utilizadas. |
| Diseño | Documentos de diseño (design_*.md) de la arquitectura interna. |
uv run pytest # suite completa (SQLite + MySQL + PostgreSQL)
uv run pytest -m "not integration" # (si los servidores no están disponibles)Las integraciones de MySQL, MariaDB, PostgreSQL, SQL Server y Oracle se omiten automáticamente si el servidor correspondiente no está disponible.
Credenciales SOLO para desarrollo local. Las credenciales de
docker-compose.ymly de.env.exampleson valores desechables de juguete, pensados exclusivamente para levantar los servicios de prueba en tu máquina. Nunca las uses en producción: sustitúyelas siempre por secretos gestionados (variables de entorno del despliegue o un gestor de secretos).
Distribuido bajo la licencia MIT. Consulta el archivo LICENSE
para el texto íntegro.
El proyecto sigue Versionado Semántico. Mientras esté en
0.x, no hay garantía de estabilidad: cada versión minor puede introducir
cambios incompatibles. La estabilidad de la API se declarará a partir de 1.0.0.
Desarrollado con la asistencia de OpenCode y el modelo DeepSeek V4 Pro. Véase docs/credits.md para el detalle completo.