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
pgomysql2. Es un compilador en WebAssembly, sin dependencias nipostinstall. - 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
stil add -D brasa-sql
stil add pg
stil exec brasa initLas migraciones definen el esquema y cada consulta es SQL con una anotación:
-- 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():
// 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
stil add -D ascua-scaffold
stil exec ascua-scaffold productsCon una tabla así:
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 vezy 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
UNIQUEo 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/abces un- Un
bigintentra como texto, para no perder precisión.
- Un
- 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
stil exec ascua-scaffold --adminGenera 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_PASSWORDyADMIN_USER(«admin» por defecto). SinADMIN_PASSWORD,/admines un 404: nunca queda abierto por olvido. Va ensrc/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 unascua-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_INCREMENTen 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.
--forcelas 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.