Guía

Base de datos

SQL de verdad con tipos de TypeScript gracias a brasa; un recurso entero —lista, alta, edición, baja y grilla— desde una tabla, y un admin de todas, con ascua-scaffold.

Ascua no trae ORM. La base se habla en SQL, y dos herramientas aparte lo hacen cómodo:

  • brasa lee tus migraciones y tus consultas al construir y genera funciones de TypeScript tipadas. En ejecución no hay motor: el código generado habla directo con pg o mysql2. Es un compilador en WebAssembly, sin dependencias ni postinstall.
  • ascua-scaffold toma una tabla de ese esquema y escribe un recurso de Ascua: consultas, formulario validado y rutas para listar, crear, editar y borrar.

Las dos necesitan un sitio con servidor: create-ascua --template server.

brasa: consultas tipadas

sh
stil add -D brasa-sql
stil add pg
stil exec brasa init

Las migraciones definen el esquema y cada consulta es SQL con una anotación:

sql
-- db/queries/products.sql
-- name: GetProduct :one
SELECT id, name, price FROM products WHERE id = :id;

stil exec brasa generate escribe src/db.ts, y una ruta la usa en load():

ts
// src/routes/products/[id].ts
import { notFound } from "vite-plugin-ascua/site";
import { getProduct } from "../../db.js";
import { db } from "../../pool.js";

export async function load({ id }: { id: string }) {
  const product = await getProduct(await db(), { id: Number(id) });
  if (!product) throw notFound();
  return product; // { id: number; name: string; price: string }
}

Una columna que no existe, un INSERT al que le falta una NOT NULL o una columna fuera del GROUP BY son errores al construir, con archivo, línea y columna. Los tipos son los que entrega el driver de verdad: en pg, numeric llega como string y las fechas como Date.

ascua-scaffold: un recurso en un comando

sh
stil add -D ascua-scaffold
stil exec ascua-scaffold products

Con una tabla así:

sql
CREATE TYPE category AS ENUM ('tools', 'books', 'garden');

CREATE TABLE products (
  id serial PRIMARY KEY,
  sku text NOT NULL UNIQUE,
  name text NOT NULL,
  description text,
  price numeric(10, 2) NOT NULL,
  active boolean NOT NULL DEFAULT true,
  category category NOT NULL DEFAULT 'tools',
  released_on date,
  created_at timestamptz NOT NULL DEFAULT now()
);

escribe:

db/queries/products.sql         ListProducts, GetProduct, CreateProduct, UpdateProduct, DeleteProduct
src/resources/products.ts       el esquema del formulario, sus campos y las conversiones
src/routes/products/index.ts    /products, de 50 en 50
src/routes/products/new.ts      /products/new
src/routes/products/[id].ts     /products/:id, editar y borrar
src/routes/products/grid.ts     /products/grid, todas las filas editables a la vez
src/pool.ts                     el pool, con las migraciones aplicadas una vez

y vuelve a generar src/db.ts con las consultas nuevas. Con DATABASE_URL apuntando a la base, /products ya funciona.

El formulario sale de las columnas

Cada columna editable se vuelve un campo de fields, según su tipo:

Columna Esquema Control
integer, bigint field.number({ integer: true }) type="number"
numeric, real field.number() type="number" step="any"
boolean field.checkbox() casilla
un enum field.choice(categoryValues) <select>
date, timestamptz field.text() type="date", datetime-local
email, contact_email field.email() type="email"
description, body, notes field.text() <textarea>

Una columna con clave foránea —category_id integer REFERENCES categories— se elige de un <select> con las filas de la otra tabla, por su nombre: la columna name, title, email… que tenga. La lista muestra ese nombre en vez del número.

Lo nullable va con field.optional y vacío se guarda como NULL. Quedan fuera la clave serial, lo que el formulario no sabe editar —JSON, binarios, arreglos— y created_at o updated_at con DEFAULT. Si una columna así es obligatoria y no tiene DEFAULT, el comando lo dice y no genera nada.

Lo que hace cada página

  • Los formularios son HTML: funcionan sin una línea de JavaScript.
  • Un error de validación vuelve con un 400, cada mensaje bajo su campo y lo escrito en su sitio.
  • Lo que la base rechaza vuelve con un 409 y el error bajo su columna, no con un 500: un UNIQUE o una clave repetidos, una clave foránea que no existe, borrar una fila que otras usan. En Postgres y en MySQL.
  • La clave de la URL se valida antes de ir a la base: /products/abc es un
    1. Un bigint entra como texto, para no perder precisión.
  • Borrar es <form method="post" action="?/delete">.

La grilla

/products/grid es la página entera editable, como una DataWindow de PowerBuilder: una fila por registro y una celda por campo. También es un <form> de HTML y funciona sin JavaScript.

Cada fila lleva los valores con que se mostró, así que al guardar solo se escriben las que cambiaron. Cada una se valida con el mismo ProductForm y todas se guardan en una sola transacción: si una falla, no se escribe ninguna, y el error aparece en su celda —un 400 si no valida, un 409 si repite un UNIQUE—.

El admin

sh
stil exec ascua-scaffold --admin

Genera todas las tablas a la vez bajo /admin, como el admin de Django: lista, alta, edición y grilla de cada una, un panel en /admin y una barra con las tablas.

  • Pide usuario y contraseña (HTTP Basic): ADMIN_PASSWORD y ADMIN_USER («admin» por defecto). Sin ADMIN_PASSWORD, /admin es un 404: nunca queda abierto por olvido. Va en src/routes/admin/_middleware.ts, para cambiarlo por el inicio de sesión del sitio (passkeys, una sesión) cuando lo tenga.
  • Reutiliza lo que hay: una tabla que ya tiene sus consultas y su src/resources/<tabla>.ts —de un ascua-scaffold <tabla> anterior— los conserva y solo recibe sus páginas del admin.
  • Lo que no puede generar lo salta y dice por qué: vistas, columnas obligatorias que el formulario no sabe editar, una clave compuesta con AUTO_INCREMENT en MySQL. El panel las lista.
  • Se puede volver a correr: tras una migración nueva, agrega las tablas nuevas y deja como están las que ya tenían página. --force las reescribe todas.

Lo generado es tuyo

No se vuelve a generar: cambia las consultas —un WHERE, otro orden, un JOIN— y brasa generate revisa que sigan valiendo; cambia las páginas como cualquier otra ruta. --force reescribe encima.

Una tabla con clave escrita por el usuario —code text PRIMARY KEY— pide la clave al crear y no deja cambiarla al editar. Una clave compuesta —PRIMARY KEY (order_id, line)— lleva sus partes en la URL, separadas por coma: /order-lines/5,2. Y una tabla puente —post_tags (post_id, tag_id), nada más que la clave— se crea y se borra, sin edición ni grilla.