Neon Postgres
O banco de dados é opt-in (AGENTS.md §0.5): use-o apenas quando o aplicativo precisar de dados que sobrevivam a uma sessão do navegador ou sejam compartilhados entre dispositivos. Caso contrário, não envie migrations, não importe @/lib/db e mantenha o estado em localStorage / zustand.
Este template vem com uma integração de banco de dados dual-mode pronta:
- Configurado (variável de ambiente definida, por exemplo, em deploy): Neon Postgres real.
- Não configurado (preview do sandbox): o banco de dados cai para um PGLite local (Postgres WASM embarcado), para que o preview sempre renderize. Crie seu código contra o helper
@/lib/db; ambos os modos funcionam com a mesma API.
Os pacotes estão pré-instalados — não execute npm install neles: pg (node-postgres, o driver Postgres padrão) e @electric-sql/pglite (fallback local).
Para contas de usuário, login e leitura do usuário atual, consulte o skill auth separado — este skill é apenas o banco de dados.
Ativando o banco de dados
Defina deploy.database como true no arquivo .grok/app-env.json:
{ "VITE_AUTH_ENABLED": "false", "deploy": { "database": true } }
Isso informa à plataforma para provisionar Neon para o aplicativo em deploy; deixe como false e o deploy não receberá DATABASE_URL, então o aplicativo será executado silenciosamente em um PGLite descartável que perde seus dados. Enviar migrations/*.sql, ou login, provisiona um independentemente — esta flag é para um aplicativo que consulta @/lib/db sem nenhum deles. Não é uma chave VITE_ e nunca chega ao navegador.
Variáveis de ambiente — não crie um arquivo .env
Nunca escreva um arquivo .env / .env.local / .env.example para o banco de dados. No preview do sandbox, deixe DATABASE_URL não definido — @/lib/db usa automaticamente PGLite embarcado. Quando o aplicativo for implantado, a plataforma injeta DATABASE_URL (Neon); você não provisiona nem escreve isso manualmente.
| Var | Onde | Propósito |
|---|---|---|
DATABASE_URL | servidor | String de conexão Neon quando implantado (opcional — fallback para PGLite se não definido) |
Nunca codifique; nunca exponha variáveis não VITE_ ao cliente.
Banco de dados (apenas servidor)
@/lib/db exporta getSql() e dbSource: um driver Postgres padrão (node-postgres, pg) contra DATABASE_URL, ou um fallback PGLite local quando não definido. Mesma API em ambos os casos — um template marcado (e .query()) que resolve para rows[]. Chame APENAS de um handler createServerFn / carregador de servidor, nunca de um componente cliente. Defina o schema em migrations/, não inline.
import { createServerFn } from "@tanstack/react-start";
import { getSql } from "@/lib/db";
export const listPosts = createServerFn({ method: "GET" }).handler(async () => {
const sql = await getSql();
// Tipifique a forma da linha — o retorno de uma função de servidor deve ser comprovadamente serializável.
return sql<{ id: number; title: string }>`select id, title from posts order by id desc`;
// ou: return sql.query<{ id: number; title: string }>("select id, title from posts where id = $1", [id]);
});
Dados por usuário (apenas quando o aplicativo tiver login). Um driver normal tem acesso total ao banco de dados, então restrinja cada consulta ao usuário autenticado no lado do servidor — nunca confie em um id enviado pelo cliente. Use o authMiddleware pré-configurado para obter um context.userId verificado e, em seguida, filtre por ele. O padrão completo (middleware, chamada a partir do código cliente, semântica de fail-closed) está no 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`;
});
// mutações também devem escopar escritas: `... where id = ${id} and user_id = ${context.userId}`
Sem login (o padrão), NÃO use authMiddleware / requireUserId. O usuário de desenvolvimento para o qual eles caem é uma conveniência apenas para preview. Um aplicativo implantado tem VITE_AUTH_ENABLED definido pela plataforma, não por este workspace (hoje o implantador sempre o define como "true"), então, quando implantado, ambos rejeitam todos os visitantes — e um aplicativo sem auth não tem rota de login para eles se recuperarem. Um aplicativo apenas com banco de dados mantém suas linhas sem dono: sem coluna user_id, ou uma literal constante. Adicione o middleware como parte da ativação do login (as etapas de atualização do skill auth) e reescope ou remova essas linhas nesse momento.
Linhas sem dono são mundiais legíveis e mundiais graváveis através de suas funções de servidor públicas: nunca persista dados pessoais ou sensíveis (nomes, e-mails, texto livre sobre uma pessoa) neste modo, e omita mutações destrutivas em massa (deletar tudo, sobrescrever tudo) — se o aplicativo precisar delas, proponha login.
Migrations
Os arquivos migrations/*.sql são a única fonte do schema. Eles se aplicam ao Neon no deploy (npm run build executa db:migrate contra DATABASE_URL, então o Vercel implanta com o schema pronto) e ao preview PGLite automaticamente na inicialização, para que o desenvolvimento corresponda à produção.
Nenhum dos aplicadores desce em subdiretórios, então o schema do Better Auth em migrations/auth/0001_auth.sql não é aplicado a menos que o aplicativo ative o login e o copie para cima (não edite — veja o skill auth). Coloque o schema do seu aplicativo em NOVOS arquivos ordenados começando em 0002:
-- migrations/0002_schema.sql — exemplo para um aplicativo de tarefas; use as tabelas do SEU aplicativo
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 edite um arquivo já aplicado — ele é rastreado pelo nome em _migrations e não será reexecutado (adicione um novo arquivo em vez disso; novos arquivos se aplicam ao preview em execução na próxima requisição). Prefira statements idempotentes (… if not exists). Tabelas com dados por usuário devem ter uma coluna user_id text not null (TEXT, não UUID — o id do usuário de desenvolvimento do preview é a string 'dev-user').
Paridade preview ↔ produção
getSql() normaliza os tipos de resultado para que ambos os backends retornem formas idênticas e seguras para JSON: bigint/count(*) → number, date → string 'YYYY-MM-DD', interval → texto, numeric → string. Diferenças restantes a respeitar:
bigintacima de 2^53 perde precisão como número — converta com::textse precisar de inteiros enormes (contagens de linhas são seguras).- Preview DB está na memória: limpo na reinicialização do servidor de desenvolvimento, conexão única (sem contenção de bloqueio ou conflitos de escrita simultânea) e não carrega extensões — não use
create extension; mantenha-se no Postgres core. - O endpoint poolizado do Neon não mantém estado de sessão — não confie em
SET,LISTEN/NOTIFYou locks de sessão consultivos. - Mantenha colunas
user_idcomotext— preview usa'dev-user', produção usa ids text do Better Auth; uma colunauuidquebra inserções no preview. - Consultas Neon implantadas atravessam a rede (e podem cold-resume) — evite padrões de consulta N+1 que parecem gratuitos contra o banco de dados preview em processo.