Communitygithub.com

Neon Serverless PostgreSQL Patterns

PostgreSQL serverless com branching, autoescala e driver compatível com edge.

O que é Neon Serverless PostgreSQL Patterns?

Este skill fornece padrões e práticas recomendadas para usar o driver @neondatabase/serverless, que permite acesso a bancos de dados PostgreSQL a partir de runtimes serverless e edge que não suportam conexões TCP tradicionais. Ele cobre dois transportes principais: a função HTTP `neon()` para consultas individuais rápidas (2-3x mais rápida que WebSocket) e as classes `Pool`/`Client` para transações interativas que exigem sessões. O skill enfatiza o uso de strings de conexão pooled (com sufixo -pooler) para workloads serverless, pois o PgBounger gerencia até 10.000 clientes concorrentes, enquanto conexões diretas são reservadas para migrações e recursos de sessão. Além disso, aborda branching de banco de dados com semântica copy-on-write para ambientes de dev e pré-visualização, gerenciamento de scale-to-zero com latência de cold start de 200-500ms, e uso de `sql.transaction()` para transações HTTP atômicas. O skill é útil para desenvolvedores que precisam de um banco de dados relacional elástico e econômico em plataformas serverless, com destaque para segurança contra SQL injection via tagged templates e boas práticas de fechamento de conexões em handlers de requisição.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-baas-neon

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Neon Serverless PostgreSQL Patterns faz?

Guia Rápido: Use @neondatabase/serverless para acesso a banco de dados edge/serverless. Prefira a função HTTP neon() para consultas individuais (mais rápida, sem estado) e Pool/Client para 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/Client com 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 pg padrã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:

  1. HTTP para velocidade, WebSocket para sessões -- A função neon() usa HTTP fetch (~3 viagens de ida e volta) para consultas individuais. Pool/Client usam WebSockets (~8 viagens de ida e volta) quando você precisa de sessões ou transações interativas. Escolha o transporte certo para o trabalho.
  2. 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.
  3. 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.
  4. 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.
  5. 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 pg padrã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 | Serializable
  • readOnly: booleano (padrão false)
  • deferrable: booleano (padrão false, efetivo apenas com readOnly: 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 (use ALTER ROLE ... SET como alternativa)
  • LISTEN / NOTIFY
  • WITH HOLD CURSOR
  • PREPARE / DEALLOCATE em 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]

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Habilidades Relacionadas