Neon Postgres
La base de datos es optativa (AGENTS.md §0.5): úsala solo cuando la aplicación necesite datos
que sobrevivan a una sesión del navegador o que se compartan entre dispositivos. De lo contrario, no incluyas migraciones, no importes @/lib/db y mantén el estado en localStorage / zustand.
Esta plantilla incluye una integración de base de datos de doble modo ya preparada:
- Configurada (variable de entorno definida, ej. en despliegue): Neon Postgres real.
- No configurada (vista previa en vivo del sandbox): la BD recurre a una PGLite local (Postgres WASM embebido), por lo que la vista previa siempre se renderiza. Desarrolla usando el ayudante
@/lib/db; ambos modos funcionan con la misma API.
Los paquetes están preinstalados — no ejecutes npm install para ellos: pg (node-postgres, el controlador Postgres estándar) y @electric-sql/pglite (BD local de respaldo).
Para cuentas de usuario, inicio de sesión y lectura del usuario actual, consulta el skill auth aparte — este skill es solo la base de datos.
Activando la base de datos
Establece deploy.database a true en .grok/app-env.json:
{ "VITE_AUTH_ENABLED": "false", "deploy": { "database": true } }
Eso es lo que le indica a la plataforma que debe aprovisionar Neon para la aplicación desplegada; déjalo en false y el despliegue no tendrá DATABASE_URL, por lo que la aplicación se ejecutará silenciosamente sobre una PGLite desechable que perderá sus filas. Incluir archivos migrations/*.sql, o inicio de sesión, aprovisiona uno independientemente de esta bandera — esta bandera es para una aplicación que consulta @/lib/db sin ninguna de esas dos cosas. No es una clave VITE_ y nunca llega al navegador.
Variables de entorno — no crees un archivo .env
Nunca escribas un archivo .env / .env.local / .env.example para la base de datos. En la vista previa en vivo del sandbox, deja DATABASE_URL sin definir — @/lib/db usa automáticamente PGLite embebido. Cuando la aplicación se despliegue, la plataforma inyecta DATABASE_URL (Neon); tú no lo aprovisionas ni lo escribes.
| Variable | Dónde | Propósito |
|---|---|---|
DATABASE_URL | servidor | Cadena de conexión Neon cuando está desplegado (opcional — respaldo PGLite si no está definida) |
Nunca la codifiques; nunca expongas variables que no sean VITE_ al cliente.
Base de datos (solo servidor)
@/lib/db exporta getSql() y dbSource: un controlador Postgres estándar (node-postgres, pg) contra DATABASE_URL, o un respaldo PGLite local cuando no está definida. La misma API en ambos casos — una plantilla etiquetada (y .query()) que resuelve a rows[]. Llámalo SOLO desde un manejador createServerFn / cargador de servidor, nunca desde un componente cliente. Define el esquema en migrations/, no en línea.
import { createServerFn } from "@tanstack/react-start";
import { getSql } from "@/lib/db";
export const listPosts = createServerFn({ method: "GET" }).handler(async () => {
const sql = await getSql();
// Tipa la forma de la fila — el retorno de una función de servidor debe ser demostrablemente serializable.
return sql<{ id: number; title: string }>`select id, title from posts order by id desc`;
// o: return sql.query<{ id: number; title: string }>("select id, title from posts where id = $1", [id]);
});
Datos por usuario (solo una vez que la aplicación tenga inicio de sesión). Un controlador regular tiene acceso completo a la BD, por lo que debes acotar cada consulta al usuario autenticado del lado del servidor — nunca confíes en un id enviado por el cliente. Usa el authMiddleware preconfigurado para obtener un context.userId verificado, luego filtra por él. El patrón completo (middleware, llamada desde código cliente, semántica de fallo cerrado) está en el skill auth:
import { authMiddleware } from "@/lib/auth/middleware";
export const listTodos = createServerFn({ method: "GET" })
.middleware([authMiddleware])
.handler(async ({ context }) => {
const sql = await getSql();
return sql<{ id: number; title: string }>`select id, title from todos where user_id = ${context.userId} order by id desc`;
});
// las mutaciones también deben acotar escrituras: `... where id = ${id} and user_id = ${context.userId}`
Sin inicio de sesión (valor por defecto), NO uses authMiddleware / requireUserId.
El usuario de desarrollo al que recurren es una conveniencia solo de vista previa. La variable VITE_AUTH_ENABLED de una aplicación desplegada es establecida por la plataforma, no por este espacio de trabajo (hoy el desplegador siempre la establece a "true"), por lo que al estar desplegada, ambos rechazan a cada visitante — y una aplicación sin autenticación no incluye ninguna ruta de inicio de sesión para que se recuperen. Una aplicación solo de base de datos mantiene sus filas sin dueño: sin columna user_id, o con una constante literal. Agrega el middleware como parte de activar el inicio de sesión (los pasos de actualización del skill auth), y re-acota o elimina esas filas entonces.
Las filas sin dueño son legibles y escribibles mundialmente a través de tus funciones de servidor públicas: nunca persistas datos personales o sensibles (nombres, correos electrónicos, texto libre sobre una persona) en este modo, y omite mutaciones destructivas masivas (eliminar todo, sobrescribir todo) — si la aplicación las necesita, propón en su lugar inicio de sesión.
Migraciones
Los archivos migrations/*.sql son la única fuente del esquema. Se aplican a Neon al desplegar (npm run build ejecuta db:migrate contra DATABASE_URL, por lo que Vercel se despliega con el esquema listo) y a la vista previa PGLite automáticamente al iniciar, por lo que desarrollo y producción coinciden.
Ningún aplicador desciende a subdirectorios, por lo que el esquema de Better Auth en migrations/auth/0001_auth.sql no se aplica a menos que la aplicación active el inicio de sesión y lo copie hacia arriba (no lo edites — consulta el skill auth). Coloca el esquema de tu aplicación en NUEVOS archivos ordenados a partir de 0002:
-- migrations/0002_schema.sql — ejemplo para una aplicación de tareas; usa LAS TABLAS de TU aplicación
create table if not exists todos (
id serial primary key,
user_id text not null,
title text not null,
done boolean not null default false,
created_at timestamptz not null default now()
);
create index if not exists todos_user_id_idx on todos (user_id);
Nunca edites un archivo ya aplicado — se rastrea por nombre en _migrations y no se volverá a ejecutar (agrega un nuevo archivo en su lugar; los nuevos archivos se aplican a la vista previa en ejecución en la siguiente solicitud). Prefiere sentencias idempotentes (… if not exists). Las tablas con datos por usuario deben tener una columna user_id text not null (TEXT, no UUID — el id de usuario de desarrollo en vista previa es la cadena 'dev-user').
Paridad vista previa ↔ producción
getSql() normaliza los tipos de resultado para que ambos backend devuelvan formas idénticas y seguras para JSON: bigint/count(*) → number, date → cadena 'YYYY-MM-DD', interval → texto, numeric → cadena. Diferencias restantes a respetar:
bigintmás allá de 2^53 pierde precisión como número — convierte con::textsi alguna vez necesitas enteros enormes (los recuentos de filas están bien).- La BD de vista previa está en memoria: se borra al reiniciar el servidor de desarrollo, es de una sola conexión (sin contención de bloqueos ni conflictos de escritura concurrente), y no carga extensiones — no uses
create extension; quédate con Postgres básico. - El extremo agrupado de Neon no mantiene estado de sesión — no confíes en
SET,LISTEN/NOTIFY, ni bloqueos de sesión con asesoramiento. - Mantén las columnas
user_idcomotext— la vista previa usa'dev-user', producción usa los ids de texto de Better Auth; una columnauuidrompe las inserciones en vista previa. - Las consultas a Neon desplegado atraviesan la red (y pueden reactivarse en frío) — evita patrones de consulta N+1 que se sientan gratuitos contra la BD de vista previa en proceso.