SQLAlchemy Core
Lenguaje de expresión, conexiones e inserciones/selecciones de Core.
Receta
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
from sqlalchemy import MetaData, Table, Column, Integer, String, insert, select
metadata = MetaData()
items = Table("items", metadata, Column("id", Integer, primary_key=True), Column("name", String))
metadata.create_all(engine)
with engine.begin() as conn:
conn.execute(insert(items).values(name="a"))
print(conn.execute(select(items)).all())Cuándo usar esto:
- SQL masivo sin ORM
- Metadatos de migraciones
- SQL crítico para el rendimiento
Ejemplo funcional
from sqlalchemy import update
stmt = update(items).where(items.c.id == 1).values(name="b")Lo que esto demuestra:
- Construcción de tabla
- insert/select
- sentencias update
Análisis en profundidad
Cómo funciona
- Core mapea tablas a construcciones SQL.
- Engine proporciona el pool de conexiones.
- Usa Core cuando la sobrecarga del ORM no es deseada.
Errores comunes
- Validación de límites omitida - Datos inválidos llegan a las capas de persistencia. Solución: Valida con Pydantic o formularios del framework en el borde.
- Fugas de trazas de pila - Los clientes ven errores internos. Solución: Mapea excepciones a respuestas HTTP estables.
- Bloqueo de bucles de eventos asíncronos - Los trabajadores se detienen bajo carga concurrente. Solución: Usa drivers asíncronos o envoltorios de threadpool.
- Secretos en control de código fuente - Credenciales filtradas a través del historial de git. Solución: Carga secretos desde variables de entorno o una bóveda en tiempo de ejecución.
- Falta de observabilidad - Los incidentes son difíciles de depurar. Solución: Añade logs estructurados, métricas e IDs de solicitud.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| Framework alternativo en este cookbook | Estándar del equipo o monolito existente | API Greenfield con diferentes restricciones |
| BaaS gestionado | MVP solo CRUD | Autenticación personalizada, flujos de trabajo o necesidades de cumplimiento |
| gRPC | RPC interno de alto rendimiento | Clientes HTTP públicos y acceso al navegador |
Preguntas frecuentes
¿Cuándo debería adoptar SQLAlchemy Core?
Úsalo cuando los patrones y las compensaciones de esta página coincidan con tu API o límite de datos.
¿Cuál es el principal error de producción con SQLAlchemy Core?
Omitir la validación, los tiempos de espera o los contratos de error explícitos en el borde HTTP.
¿Cómo pruebo SQLAlchemy Core?
Usa el cliente de prueba del framework, anula las dependencias y afirma el estado más la forma JSON.
¿Funciona SQLAlchemy Core con Python 3.14?
Sí, los ejemplos se dirigen a Python 3.14 con versiones de framework fijadas del pie de página de la pila.
¿Cómo se relaciona SQLAlchemy Core con Pydantic 2?
Valida y serializa en los límites; mantén los servicios funcionando con objetos de dominio tipados.
¿Síncrono o asíncrono?
Prefiere rutas asíncronas cuando las E/S dominan; mantén el trabajo de CPU pequeño o descárgalo a trabajadores.
¿Dónde debe residir la lógica de negocio?
Handlers delgados; los servicios poseen las reglas; los repositorios poseen las consultas.
¿Cómo documento las APIs?
Publica documentación OpenAPI o de esquema que coincida con los modelos de respuesta en el código.
¿Cómo manejo el versionado?
Versionado explícito de URL o encabezado con ventanas de deprecación - evita roturas silenciosas.
¿Qué debería leer a continuación?
Sigue los enlaces Relacionados para la siguiente capa de profundidad en esta sección.
¿Cómo me mantengo seguro?
Autentica a los llamadores, autoriza por recurso, limita la tasa y nunca registres secretos.
¿Primer paso para el rendimiento?
Mide la latencia de la base de datos y la ascendente antes de cambiar de framework.
Relacionado
- Conceptos básicos de bases de datos - Conexiones y transacciones
- SQLAlchemy ORM 2.0 - Patrones ORM
- Migraciones con Alembic - Cambios de esquema
- Acceso asíncrono a bases de datos - asyncpg
Versiones de la pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.