Saltar a contenido

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:

  • datetime es una fecha y hora de reloj, sin zona: TIMESTAMP WITHOUT TIME ZONE en PostgreSQL, DATETIME en MySQL. Lo que escribes es lo que lees, se consulte desde donde se consulte.
  • timestamptz es 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:

codigo: col[str] = column(length=20)                    # VARCHAR(20)
precio: col[numeric] = column(precision=10, scale=2)    # NUMERIC(10, 2) / DECIMAL(10, 2)
codigo: str = column(length=20)
peso: Optional[numeric] = column(precision=8, scale=3)
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: length en un int, precision en un str;
  • un valor menor que 1 (en scale, menor que 0);
  • scale sin precision, o mayor que ella;
  • length junto a encrypt=True: lo que se guarda es el valor cifrado, que ocupa bastante más que el original. Quita length o declara la columna text;
  • length menor que 60 junto a hash=True: un hash bcrypt ocupa 60 caracteres.

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.