Postgres Serverless com Neon e JavaScript: API sem Servidor com Banco Real
O problema que ninguém te conta sobre Postgres + serverless
Uma função serverless nasce, executa e morre. Um Postgres espera conexões persistentes, com handshake TCP, negociação TLS e autenticação. Cada cold start de uma função abre uma conexão nova. Com 200 invocações simultâneas, são 200 conexões. O max_connections padrão do Postgres é 100.
O resultado: FATAL: too many connections for role. A função retorna 500, o usuário vê erro, e o time descobre que "serverless + Postgres" não é só trocar a string de conexão.
O Neon resolve isso com um proxy WebSocket que multiplexa conexões no lado do servidor, expondo um endpoint HTTP para queries e um driver compatível com o protocolo Postgres. A função serverless não precisa manter socket TCP aberto: ela faz uma requisição HTTP, o proxy do Neon gerencia o pool real contra o Postgres.
Este post mostra como montar essa stack do zero: criar o banco no Neon, conectar via @neondatabase/serverless, executar queries parametrizadas, tratar erros e evitar os anti-patterns que transformam essa combinação em dor de cabeça.
Neon vs. Supabase vs. PlanetScale: quando usar cada um
Antes de escrever código, a decisão de qual banco serverless usar precisa de critérios explícitos.
| Critério | Neon | Supabase | PlanetScale |
|---|---|---|---|
| Engine | Postgres (fork com separação storage/compute) | Postgres (RDS-like, gerenciado) | MySQL (Vitess) |
| Protocolo serverless | HTTP nativo + WebSocket | Precisa de connection pooler externo (PgBouncer embutido) | HTTP nativo |
| Branching de banco | Sim, copy-on-write instantâneo | Não nativo | Sim |
| Cold start do banco | ~500ms (auto-suspend/resume) | Sempre ligado (ou paga por pausa) | Sempre ligado |
| Free tier | 0.5 GB storage, compute gratuito com auto-suspend | 500 MB, projeto sempre ativo | Descontinuou free tier em 2024 |
| Compatibilidade SQL | Postgres completo (extensões, CTEs, JSON operators) | Postgres completo | MySQL com limitações do Vitess (sem FK em alguns casos) |
Se você precisa de Postgres real com extensões (pgvector, PostGIS, pg_trgm), Neon ou Supabase. Se o projeto é serverless com cold starts frequentes e você quer pagar zero em dev/staging, Neon leva vantagem pelo branching e pelo driver HTTP nativo.
Configurando o Neon e obtendo a connection string
Crie um projeto no console do Neon (console.neon.tech). O que interessa é a connection string no formato:
# Formato da connection string do Neon
# O endpoint .neon.tech já aponta para o proxy que gerencia conexões
postgres://[user]:[password]@[endpoint-id].us-east-2.aws.neon.tech/[dbname]?sslmode=require
Guarde essa string como variável de ambiente. Nunca no código.
# .env (local) ou variável no provider serverless (Vercel, Cloudflare, AWS Lambda)
DATABASE_URL="postgres://app_user:senha_forte@ep-cool-rain-123456.us-east-2.aws.neon.tech/mydb?sslmode=require"
O driver @neondatabase/serverless: como funciona por baixo
O pacote @neondatabase/serverless não é um wrapper genérico. Ele implementa duas formas de comunicação:
-
HTTP query (
neon()): envia SQL como POST HTTP para o proxy do Neon. Sem socket, sem handshake Postgres. Latência de uma requisição HTTP. Ideal para funções serverless com execução curta. -
WebSocket (
Pool/Client): abre WebSocket para o proxy, que traduz para o protocolo Postgres. Útil quando você precisa de transações multi-statement ou prepared statements.
A regra: use HTTP para queries simples (SELECT, INSERT, UPDATE isolados). Use WebSocket quando precisar de BEGIN/COMMIT explícito.
// instalar: npm install @neondatabase/serverless
import { neon } from "@neondatabase/serverless";
// neon() retorna uma tagged template function
// Cada chamada é uma requisição HTTP independente, sem pool
const sql = neon(process.env.DATABASE_URL);
const users = await sql`SELECT id, email, created_at FROM users WHERE active = true`;
// users é um array de objetos: [{ id: 1, email: "...
---
Leia o artigo completo em [https://www.vivodecodigo.com.br/backend/postgres-serverless-neon-api-javascript](https://www.vivodecodigo.com.br/backend/postgres-serverless-neon-api-javascript)