Tablas y columnas¶
class Usuario(Table):
"""Usuarios del sistema.""" # el docstring es la descripción de la tabla
__tablename__ = 'usuario' # obligatorio
id: col[int] = column(primary_key=True, autoincrement=True)
nombre: col[str] # una columna sin column() es una columna normal
email: col[str] = column(unique=True)
activo: col[bool] = column(default=True)
creado_en: col[datetime] = column(server_now=True)
posts: onetomany[Post] # lado implícito de una relación
__tablename__ es el nombre físico en la base de datos, y es obligatorio. También es el
nombre con el que la tabla aparece en el cliente generado (public_sync_api.usuario).
column()¶
column(
primary_key=False, # forma parte de la clave primaria
unique=False, # restricción de unicidad de UNA columna
default=None, # valor por defecto (un valor o un callable, como datetime.now)
server_now=False, # DEFAULT NOW() del servidor
index=False, # índice de UNA columna
autoincrement=False, # solo con primary_key y tipo entero
encrypt=False, # cifrado en reposo (Fernet)
hash=False, # hasheado (bcrypt): solo se puede verificar
description='', # documentación: va a los DTOs, al diagrama y a las rules
self_reference=None, # deprecado: la jerarquía es relation(..., tree=True)
length=None, # tamaño de un str (VARCHAR(n)), text o largebinary
precision=None, # dígitos totales de un numeric
scale=None, # dígitos decimales de un numeric
)
server_now=True no se envía al crear
La pone la base de datos con NOW(): en el Create es opcional, y si no llega el cliente no
la envía. Si llega, se guarda el valor que llegó. Hasta la 0.7.12 el Create la exigía.
Toda tabla necesita clave primaria
Sin ella no se puede generar el DAO ni comparar el estado con la base de datos, y el análisis lo dice con un error (E002).
default= acaba también como DEFAULT de la base de datos
Aunque en el cliente generado sea un default de Python. Es coherente —se compara lo mismo
que se crea—, pero tenlo en cuenta al declarar un callable como datetime.now.
Tipos disponibles¶
| Tipo | Se declara | Notas |
|---|---|---|
| Entero | int, bigint, smallint |
bigint para claves que vayan a crecer; smallint es SMALLINT (INT64 en BigQuery) |
| Decimal | float, numeric |
numeric cuando importa la precisión exacta; su tamaño, con precision y scale |
| Texto | str, text |
str mapea a VARCHAR (su tamaño, con length); para campos largos, text |
| Booleano | bool |
|
| Fecha y hora | datetime, timestamptz, date, time |
datetime es hora de reloj; timestamptz, un instante. Ver abajo |
| Identificador universal | UUID |
Generado por la base en una clave primaria con autoincrement=True. Ver abajo |
| JSON | dict |
|
| Binario | bytes, largebinary |
En JSON, base64: ver los DTOs |
| Enumerado | la clase que declares | Ver enumerados |
| Vector | vector vía vector_column() |
Ver vectores |
Todos se importan con from tai_sql import *, incluidos los alias de conveniencia (List,
Optional, datetime, bigint, smallint, timestamptz, UUID, text, numeric,
largebinary).
UUID¶
UUID es el de la librería estándar (uuid.UUID), y from tai_sql import * lo trae. En el cliente es
un UUID de Python; en JSON, su texto (8-4-4-4-12).
| Motor | UUID |
|---|---|
| PostgreSQL | UUID |
| SQL Server | UNIQUEIDENTIFIER |
| MySQL / MariaDB | CHAR(32) |
| BigQuery | STRING |
Una clave primaria UUID con autoincrement=True la genera la base al insertar
(DEFAULT gen_random_uuid() en PostgreSQL, NEWID() en SQL Server), igual que una entera saca su
valor de una secuencia: en el Create no hace falta darla, y el feed y la clave natural la tratan
como una autoincremental. Aquí autoincrement no es un contador: significa «la pone la base», y el
valor es aleatorio. En MySQL y BigQuery no hay con qué generarla: el push lo dice, y hay que
generarla en la aplicación (sin autoincrement).
gen_random_uuid() es del núcleo de PostgreSQL desde la versión 13. En una anterior es de la
extensión pgcrypto, que hay que instalar (CREATE EXTENSION pgcrypto).
class Persona(Table):
__tablename__ = "persona"
id: col[UUID] = column(primary_key=True, autoincrement=True)
nombre: col[str] = column(unique=True)
Es la identidad que no se puede adivinar ni enumerar, y que sobrevive a un nombre que se reutiliza:
la del usuario en la plantilla auth. Se filtra por igualdad o por lista, y solo se cuenta.
MySQL y los VARCHAR
MySQL exige una longitud en cada VARCHAR. Una columna str sin length se compila ahí
como VARCHAR(255), que es lo máximo que cabe cómodamente en el índice que respalda una
restricción de unicidad. Si necesitas más, declara la longitud —column(length=1000)— o
usa text.
datetime o timestamptz¶
Los dos son un datetime en Python, pero no guardan lo mismo:
datetimees una fecha y hora de reloj, sin zona:TIMESTAMP WITHOUT TIME ZONEen PostgreSQL,DATETIMEen MySQL. Lo que escribes es lo que lees, se consulte desde donde se consulte.timestamptzes un instante absoluto: el mismo momento en cualquier zona.
| Motor | timestamptz |
|---|---|
| PostgreSQL | TIMESTAMP WITH TIME ZONE |
| MySQL / MariaDB | TIMESTAMP (se guarda en UTC y se convierte con la zona de la sesión) |
| SQL Server | DATETIMEOFFSET |
| BigQuery | TIMESTAMP |
moderada_en: col[timestamptz | None] # v2
votos: col[smallint] = column(default=0)
contada_en: Optional[timestamptz] # v1
No se llama timestamp a propósito: el nombre de un tipo es un nombre del DSL, y una columna
llamada timestamp —muy habitual— dejaría de poder declararse.
El tamaño exacto: length, precision y scale¶
Sin ellos, cada tipo tiene el tamaño por defecto del motor. Con ellos, el schema dice exactamente lo que hay en la base de datos:
| Parámetro | Tipo | Qué hace |
|---|---|---|
length |
str |
VARCHAR(n), en todos los motores |
length |
text, largebinary |
En MySQL elige el tamaño de TEXT/BLOB: hasta 255 TINY, hasta 65 535 el normal, hasta 16 777 215 MEDIUM, y a partir de ahí LONG. En los demás motores esos tipos no tienen tamaño y no cambia nada |
precision |
numeric |
Número total de dígitos |
scale |
numeric |
Dígitos decimales. Exige precision, y no puede ser mayor |
El cliente generado emite lo mismo en el modelo: String(20), Numeric(10, 2).
Existen porque sin ellos había tamaños que no se podían declarar: un VARCHAR(1000) solo se
podía escribir como str —que en MySQL es VARCHAR(255)— y un DECIMAL(10,2) como
numeric —que en MySQL es DECIMAL(10,0)—, así que el primer push truncaba textos y
céntimos.
Un parámetro mal puesto es un error de análisis (E009), no se ignora:
- un parámetro sobre un tipo que no lo acepta:
lengthen unint,precisionen unstr; - un valor menor que 1 (en
scale, menor que 0); scalesinprecision, o mayor que ella;lengthjunto aencrypt=True: lo que se guarda es el valor cifrado, que ocupa bastante más que el original. Quitalengtho declara la columnatext;lengthmenor que 60 junto ahash=True: un hash bcrypt ocupa 60 caracteres.
Columnas opcionales¶
Una columna sin | None es NOT NULL. Convertir una columna existente en obligatoria cuando ya
tiene NULLs es una operación BLOCKED en push: hay que rellenarlos primero.
Dunders reconocidos¶
| Dunder | Para qué |
|---|---|
__tablename__ |
Nombre físico. Obligatorio. |
__description__ |
Descripción, si prefieres no usar el docstring. |
__examples__ |
Ejemplos de fila, para la documentación generada. |
__constraints__ |
UNIQUE e índices de varias columnas. |
__operative_fields__ |
Fuerza las columnas de auditoría en esta tabla. |
__query__, __is_view__ |
Solo en vistas. |