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)
    description='',        # documentación: va a los DTOs, al diagrama y a las rules
    self_reference=None,   # jerarquía sobre la propia tabla
)

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	bigint para claves que vayan a crecer
Decimal	float, numeric	numeric cuando importa la precisión exacta
Texto	str, text	str mapea a VARCHAR; para campos largos, text
Booleano	bool
Fecha y hora	datetime, date, time
JSON	dict
Binario	largebinary
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, text, numeric, largebinary).

MySQL y los VARCHAR

MySQL exige una longitud en cada VARCHAR. Una columna str 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, usa text.

Columnas opcionales

email: col[str | None]        # v2
email: Optional[str]          # v1

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.