Los DTOs¶
Por cada tabla se generan varios modelos Pydantic 2. Son objetos normales, sin sesión detrás: se
pueden serializar, devolver desde una API y guardar sin miedo a un DetachedInstanceError.
| DTO | Para qué |
|---|---|
<Modelo>Read |
Lo que devuelven las lecturas. Incluye las relaciones cargadas |
<Modelo>Create |
Datos de alta. Admite relaciones anidadas |
<Modelo>Filter |
Filtros; cuáles, según el tipo de cada columna |
<Modelo>UpdateValues |
Los valores a escribir en un update |
<Modelo>Update |
filter + values, para update_many. No admite escrituras anidadas |
<Modelo>UpdateNested |
Un hijo que se actualiza dentro del update de su padre: su clave + values |
<Padre><Relación>NestedUpdate |
create, update y delete de los hijos de una relación en un update (UsuarioPostsNestedUpdate). Se importa por su nombre |
<Modelo>DataFrameValidator |
Valida un DataFrame contra el esquema de la tabla |
Read¶
usuario = public_sync_api.usuario.find(id=1, includes=['posts'])
usuario.nombre # los campos, tipados
usuario.posts # List[PostRead], si se pidió en includes
usuario.model_dump() # dict
usuario.model_dump_json() # str
usuario.to_dict() # dict, como model_dump()
Incluye las columnas calculadas y las columnas de auditoría, si el schema las declara. Las columnas cifradas vienen descifradas y las vectoriales solo si se pidieron.
Create¶
UsuarioCreate(nombre='Ana', email='ana@x.com')
PostCreate(
titulo='Hola',
contenido='...',
autor=UsuarioCreate(nombre='Ana', email='ana@x.com'), # relación anidada
)
Las columnas con default, las opcionales y las autoincrementales no hacen falta. Los campos
que no existen en la tabla se rechazan (extra='forbid'): un typo en el nombre de un campo
es un error de validación, no un valor que se pierde en silencio.
Un hijo que va anidado en la lista de su padre —UsuarioCreate(posts=[PostCreate(...)])— no
puede traer a su vez la relación con ese padre (PostCreate(autor=...)): es un
ValidationError. La columna FK sí puede venir, y la pone el padre. Ver
escritura.
Las columnas bytes en JSON¶
En Python una columna bytes (o largebinary) es bytes; en JSON viaja en base64. Los
DTOs la declaran como JsonBytes, que solo cambia esa frontera:
FichaCreate.model_validate_json('{"imagen": "iVBORw0KGgo..."}').imagen # b'\x89PNG\r\n...'
ficha.model_dump_json() # '{"imagen":"iVBORw0KGgo...",...}'
- Al leer un JSON —el cuerpo de una petición,
model_validate_json— acepta base64 estándar o URL-safe, con o sin relleno. Lo demás, también con espacios o con el prefijodata:…;base64,, es un error de validaciónbytes_invalid_encoding. Unstrpasado desde Python se trata igual; unosbytes, no se tocan. - Al escribir un JSON —
model_dump_json,model_dump(mode='json'), la respuesta de un endpoint— sale en base64 estándar con relleno, que es lo que entiendenatob()y una URLdata:. El JSON Schema lo dice:{"type": "string", "contentEncoding": "base64"}.
Hasta la 0.7.21 se leían y escribían en UTF-8: el base64 que mandaba un frontend se guardaba
como texto dentro de la columna, y un binario de verdad no se podía devolver en JSON. Esas
filas no hay que migrarlas: unos bytes guardados que ya son base64 canónico se devuelven tal
cual, como antes. Un fichero real nunca lo es —su cabecera tiene bytes fuera del alfabeto—,
pero un contenido que sea él mismo texto base64 canónico (un hash en hexadecimal, una
palabra de longitud múltiplo de cuatro) sale sin recodificar. Si una columna guarda esa clase
de contenido, que sea str o text.
Filter y Update¶
from database.public import UsuarioFilter, UsuarioUpdateValues, UsuarioUpdate
public_sync_api.usuario.update_many(UsuarioUpdate(
filter=UsuarioFilter(activo=False, min_creado_en=datetime(2026, 1, 1)),
values=UsuarioUpdateValues(activo=True),
))
UpdateValues solo lleva lo que quieras escribir: lo que no declares no se toca.
Enumerados¶
Los campos de tipo enumerado se validan contra sus valores:
PostCreate(titulo='Hola', contenido='...', estado='publicado') # ✅
PostCreate(titulo='Hola', contenido='...', estado='inventado') # ValidationError
Y los valores posibles se consultan en la fachada:
Usarlos con FastAPI¶
Son modelos Pydantic estándar, así que encajan directamente:
from fastapi import FastAPI
from database.public import public_sync_api, UsuarioRead, UsuarioCreate
app = FastAPI()
@app.get('/usuarios', response_model=list[UsuarioRead])
def listar(limit: int = 50):
return public_sync_api.usuario.find_many(limit=limit)
@app.post('/usuarios', response_model=UsuarioRead)
def crear(usuario: UsuarioCreate):
return public_sync_api.usuario.create(usuario)