O que Neon Serverless PostgreSQL Patterns faz?
Guia Rápido: Use
@neondatabase/serverlesspara acesso a banco de dados edge/serverless. Prefira a função HTTPneon()para consultas individuais (mais rápida, sem estado) ePool/Clientpara transações interativas. Use strings de conexão pooled (sufixo-pooler) para workloads serverless, conexões diretas apenas para migrações. Faça branch do seu banco de dados para ambientes de dev/pré-visualização usando semântica copy-on-write. Sempre lide com cold starts de scale-to-zero (200-500ms de ativação).
<critical_requirements>
CRÍTICO: Antes de Usar Este Skill
Todo código deve seguir as convenções do projeto em CLAUDE.md (kebab-case, named exports, ordenação de imports,
import type, constantes nomeadas)
(Você DEVE usar a função neon() HTTP para consultas individuais em runtimes edge/serverless -- é 2-3x mais rápida que WebSocket para operações de ida única)
(Você DEVE fechar conexões Pool/Client dentro do mesmo handler de requisição em ambientes serverless -- conexões WebSocket não podem sobreviver a uma única requisição)
(Você DEVE usar strings de conexão pooled (sufixo -pooler) para workloads serverless -- conexões diretas esgotam os slots de conexão limitados)
(Você DEVE lidar com a latência de ativação scale-to-zero (200-500ms) com timeouts de conexão e lógica de retry apropriados)
(Você DEVE usar sql.unsafe() apenas para strings confiáveis e sabidamente seguras, como nomes de tabelas/colunas -- nunca para entrada do usuário)
</critical_requirements>
Detecção automática: Neon, @neondatabase/serverless, neon(), neonConfig, neon serverless driver, neon database, neon branch, neonctl, neon connection pooling, neon scale-to-zero, neon autoscaling, neon postgres, ep-*-pooler
Quando usar:
- Consultar Postgres a partir de funções edge/serverless (runtimes edge, plataformas serverless)
- Configurar strings de conexão (pooled vs direta) para diferentes workloads
- Criar branches de banco de dados para ambientes dev, pré-visualização ou CI
- Gerenciar comportamento de scale-to-zero e otimização de cold start
- Executar transações em contextos serverless (lote HTTP ou WebSocket)
- Gerenciamento programático de branches via API Neon ou CLI neonctl
Principais padrões abordados:
- Consultas HTTP
neon()com SQL tagged templates e fragmentos componíveis - Conexões WebSocket
Pool/Clientcom gerenciamento de ciclo de vida adequado - Strings de conexão pooled (
-pooler) vs diretas e quando usar cada uma - Branching de banco de dados (branches dev, branches de pré-visualização de PR, branches apenas de esquema)
- Comportamento de scale-to-zero, mitigação de cold start e autoescala
sql.transaction()para transações HTTP não interativas- API Neon e CLI neonctl para gerenciamento programático de branches
Quando NÃO usar:
- Conexões de servidor tradicionais de longa duração (use o driver
pgpadrão com TCP) - Padrões específicos de ORMs complexos (use o skill do seu próprio ORM)
- Sintaxe geral de consulta PostgreSQL (use um skill de SQL/Postgres)
Recursos detalhados:
- Para frameworks de decisão e tabelas de consulta rápida, veja reference.md
Driver e Consultas:
- examples/core.md -- Configuração do driver, consultas HTTP, conexões WebSocket, transações
Branching e Operações:
- examples/branching.md -- Branches dev, pré-visualizações de PR, CLI neonctl, API Neon, workflows CI/CD
Filosofia
O Neon separa armazenamento e computação para PostgreSQL, permitindo recursos serverless impossíveis com Postgres tradicional: scale-to-zero, branching instantâneo e autoescala. O driver @neondatabase/serverless substitui TCP por HTTP e WebSockets, tornando o Postgres acessível a partir de runtimes edge que não possuem suporte a TCP.
Princípios centrais:
- HTTP para velocidade, WebSocket para sessões -- A função
neon()usa HTTP fetch (~3 viagens de ida e volta) para consultas individuais.Pool/Clientusam WebSockets (~8 viagens de ida e volta) quando você precisa de sessões ou transações interativas. Escolha o transporte certo para o trabalho. - Pooled por padrão -- Conexões pooled roteiam através do PgBouncer (modo transação), lidando com até 10.000 clientes concorrentes. Conexões diretas são limitadas pelo tamanho da computação (100-4.000) e devem ser usadas apenas para migrações ou recursos que exigem estado de sessão.
- Branches são baratos -- Copy-on-write significa que um branch de um banco de dados de 500 GB não aloca armazenamento extra até que os dados divirjam. Use branches livremente para dev, pré-visualização, teste e CI.
- Scale-to-zero é o padrão -- Computações são suspensas após 5 minutos de inatividade. Cold starts levam 200-500ms. Projete para isso com timeouts, retries e pooling de conexão.
- Segurança contra SQL injection embutida -- A função tagged template parametriza automaticamente. Desde v1.0, chamar
neon()como uma função normal é um erro de tipo, prevenindo injeção acidental.
Quando usar o driver serverless Neon:
- Funções edge/serverless que não podem abrir conexões TCP
- Aplicações que se beneficiam de branching de banco de dados (ambientes de pré-visualização por PR)
- Workloads sensíveis a custo que se beneficiam de scale-to-zero
- Aplicativos serverless de alta concorrência que precisam de pooling de conexão
Quando NÃO usar:
- Processos de servidor de longa duração com conexões persistentes (use o
pgpadrão sobre TCP) - Workloads que exigem recursos de nível de sessão através do PgBouncer (LISTEN/NOTIFY, SET, tabelas temporárias)
- Bancos de dados maiores que 16 CU que precisam de computação sempre ativa (scale-to-zero não disponível acima de 16 CU)
Padrões Centrais
Padrão 1: Consultas HTTP com neon()
A função neon() cria uma função de consulta baseada em HTTP usando SQL tagged templates. É o caminho mais rápido para consultas individuais e não interativas.
import { neon } from "@neondatabase/serverless";
const DATABASE_URL = process.env.DATABASE_URL!;
const sql = neon(DATABASE_URL);
// Tagged template -- parâmetros são auto-parametrizados (seguro contra injeção)
const userId = "abc-123";
const posts =
await sql`SELECT id, title FROM posts WHERE author_id = ${userId}`;
Por que é bom: Tagged template auto-parametriza valores prevenindo SQL injection, HTTP é ~3 viagens de ida e volta vs ~8 para WebSocket, sem estado (nenhuma conexão para gerenciar)
// RUIM: Chamar neon() como uma função normal (erro de tipo desde v1.0+)
const sql = neon(DATABASE_URL);
const result = await sql(`SELECT * FROM posts WHERE id = ${id}`); // ERRO DE TIPO + risco de SQL injection
Por que é ruim: Desde v1.0, chamar a função de consulta como uma função normal (não um tagged template) é um erro de tempo de execução e de tipo -- isso foi alterado especificamente para prevenir SQL injection de interpolação de strings
sql.query() para SQL Dinâmico
Quando a string de consulta está em uma variável (não um template literal), use o método .query() com placeholders numerados:
const q = "SELECT * FROM posts WHERE id = $1 AND status = $2";
const posts = await sql.query(q, [postId, "published"]);
Quando usar: Strings SQL dinâmicas construídas em tempo de execução, ou consultas armazenadas em variáveis. Parâmetros ainda são parametrizados com segurança via $1, $2, etc.
Padrão 2: Fragmentos de Consulta Componíveis
Consultas de template suportam composição com numeração automática de parâmetros entre fragmentos.
import { neon } from "@neondatabase/serverless";
const sql = neon(DATABASE_URL);
// Construir consultas a partir de fragmentos reutilizáveis
const whereClause = sql`WHERE status = ${"active"} AND role = ${"admin"}`;
const orderClause = sql`ORDER BY created_at DESC`;
const PAGE_SIZE = 20;
const limitClause = sql`LIMIT ${PAGE_SIZE}`;
const users =
await sql`SELECT id, name, email FROM users ${whereClause} ${orderClause} ${limitClause}`;
Por que é bom: Parâmetros são renumerados automaticamente entre fragmentos compostos, constante nomeada para tamanho de página, fragmentos são reutilizáveis entre consultas
Nomes Dinâmicos de Tabela/Coluna com sql.unsafe()
// SOMENTE para valores confiáveis e sabidamente seguros -- nunca entrada do usuário
const TABLE_NAME = "posts";
const results =
await sql`SELECT * FROM ${sql.unsafe(TABLE_NAME)} WHERE id = ${postId}`;
Quando usar: Apenas quando você precisa interpolar identificadores confiáveis (nomes de tabela, nomes de coluna) que não podem ser parametrizados em SQL. Nunca passe valores fornecidos pelo usuário para sql.unsafe().
Padrão 3: Transações HTTP com sql.transaction()
Execute múltiplas consultas atomicamente via HTTP sem precisar de uma conexão WebSocket.
import { neon } from "@neondatabase/serverless";
const sql = neon(DATABASE_URL);
// Forma de array -- todas as consultas executam em uma única viagem HTTP de ida e volta
const [posts, totalCount] = await sql.transaction([
sql`SELECT id, title FROM posts ORDER BY created_at DESC LIMIT 10`,
sql`SELECT count(*) FROM posts`,
]);
// Forma de função com opções de transação
const [, transferResult] = await sql.transaction(
(txn) => [
txn`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`,
txn`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`,
],
{ isolationLevel: "Serializable" },
);
Por que é bom: Execução atômica sem overhead de WebSocket, forma de array é concisa para lotes somente leitura, forma de função suporta opções de transação, nível de isolamento controla garantias de consistência
// RUIM: Executar consultas relacionadas como requisições HTTP separadas
const posts = await sql`SELECT * FROM posts WHERE author_id = ${authorId}`;
const author = await sql`SELECT * FROM users WHERE id = ${authorId}`;
// Duas viagens HTTP separadas, não atômicas, possíveis condições de corrida
Por que é ruim: Chamadas HTTP separadas não são atômicas, os dados podem mudar entre consultas, o dobro da latência de rede
Opções de Transação
isolationLevel:ReadUncommitted|ReadCommitted|RepeatableRead|SerializablereadOnly: booleano (padrãofalse)deferrable: booleano (padrãofalse, efetivo apenas comreadOnly: true+Serializable)
Padrão 4: Conexões WebSocket com Pool/Client
Use Pool e Client para transações interativas ou compatibilidade com a API node-postgres. Em ambientes serverless, as conexões devem ser criadas e fechadas dentro de um único handler de requisição.
import { Pool } from "@neondatabase/serverless";
export async function handleRequest(request: Request): Promise<Response> {
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
try {
// ... consultas ...
} finally {
await pool.end(); // SEMPRE fechar dentro da mesma requisição
}
}
Regra chave: Crie Pool dentro do handler, feche com pool.end() em finally. Um Pool global vaza conexões WebSocket entre invocações serverless.
Veja examples/core.md -- Padrões 5-7 para pools com escopo de requisição, transações interativas e configuração WebSocket Node.js.
Padrão 5: Configuração de String de Conexão
O Neon fornece dois formatos de string de conexão: pooled (via PgBouncer) e direta.
# Conexão pooled (nota: sufixo -pooler no ID do endpoint)
# Use para: funções serverless, aplicativos web, workloads de alta concorrência
DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require
# Conexão direta (sem sufixo -pooler)
# Use para: migrações, pg_dump, LISTEN/NOTIFY, recursos de nível de sessão
DIRECT_DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require
Por que é bom: Pooled lida com até 10.000 clientes concorrentes via PgBouncer em modo transação, direta fornece recursos completos de sessão para tarefas de administração, variáveis de ambiente separadas tornam a distinção explícita
Limitações do Modo Transação PgBouncer
A conexão pooled executa PgBouncer em modo transação, o que significa que as conexões retornam ao pool após cada transação. Isso proíbe:
- Instruções
SET/RESET(useALTER ROLE ... SETcomo alternativa) LISTEN/NOTIFYWITH HOLD CURSORPREPARE/DEALLOCATEem nível SQL (instruções preparadas em nível de protocolo de até 1.000 são suportadas)- Tabelas temporárias com
PRESERVE/DELETE ROWS - Locks de sessão em nível de sessão
Padrão 6: Tratamento de Cold Start e Scale-to-Zero
As computações Neon suspendem automaticamente após 5 minutos de inatividade (padrão). Cold starts levam 200-500ms. Projete para isso com timeouts e lógica de retry apropriados.
const CONNECTION_TIMEOUT_MS = 10_000;
const sql = neon(process.env.DATABASE_URL!, {
fetchOptions: { signal: AbortSignal.timeout(CONNECTION_TIMEOUT_MS) },
});
Regra chave: Defina timeouts explícitos (10-15s) para acomodar a latência de cold start. Use retries com backoff exponencial para confiabilidade.
Veja examples/core.md -- Padrão 8 para configuração completa de timeout e padrões de retry.
Fatos sobre Scale-to-Zero
- Suspensão automática padrão: 5 minutos de inatividade
- Latência de cold start: ~200-500ms (varia por região e tamanho da computação)
- Disponível apenas para computações de até 16 CU (computações maiores permanecem sempre ativas)
- Planos pagos podem ajustar o timeout de suspensão (até 7 dias) ou desabilitar completamente
- Assinantes de replicação lógica ativa impedem a suspensão
Padrão 7: Branching de Banco de Dados
Os branches Neon usam semântica copy-on-write -- criar um branch de um banco de dados de 500 GB é instantâneo e não aloca armazenamento extra até que os dados divirjam.
# Instalar neonctl
npm install -g neonctl
# Criar um branch dev a partir do main
neonctl branches create --name dev-alice --project-id <id-do-projeto>
# Criar um branch com expiração automática (para CI/pré-visualização)
neonctl branches create --name preview/pr-42 --project-id <id-do-projeto> --expires-at "2025-04-01T00:00:00Z"
# Criar um branch apenas de esquema (nenhum dado copiado -- para ambientes sensíveis)
neonctl branches create --name ci-test --schema-only --project-id <id-do-projeto>
# Redefinir um branch dev para corresponder à produção atual
neonctl branches reset dev-alice --parent --project-id <id-do-projeto>
# Excluir um branch
neonctl branches delete preview/pr-42 --project-id <id-do-projeto>
Por que é bom: Branches nomeados mapeiam para o fluxo de trabalho git, expiração TTL limpa automaticamente branches de CI, branching apenas de esquema protege dados sensíveis, reset sincroniza dev com produção sem recriar
...
[truncado para tradução]