Postgres Requisitável

Quando Usar

Use esta habilidade quando precisar provisionar bancos de dados Postgres temporários instantâneos via Postgres Requisitável (neon.new) sem login, cadastro ou cartão de crédito. Suporta API REST, CLI e SDK. Use quando os usuários pedirem um ambiente Postgres rápido, um DATABASE_URL descartável para prototipagem/testes, ou "apenas me dê um DB...

Bancos de dados Postgres instantâneos para desenvolvimento local, demonstrações, prototipagem e ambientes de teste. Nenhuma conta é necessária. Os bancos de dados expiram após 72 horas, a menos que sejam reivindicados para uma conta Neon.

Início Rápido

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

Analise connection_string e claim_url da resposta JSON. Escreva connection_string no .env do projeto como DATABASE_URL.

Para outros métodos (CLI, SDK, plugin Vite), veja Qual Método? abaixo.

Qual Método?

• API REST: Retorna JSON estruturado. Nenhuma dependência de tempo de execução além de curl. Preferível quando o agente precisa de saída e tratamento de erros previsíveis.
• CLI (npx neon-new@latest --yes): Provisiona e escreve .env em um único comando. Conveniente quando o Node.js está disponível e o usuário deseja uma configuração simples.
• SDK (neon-new/sdk): Provisionamento de scripts ou programático em Node.js.
• Plugin Vite (vite-plugin-neon-new): Provisiona automaticamente em vite dev se DATABASE_URL estiver faltando. Use quando o usuário tiver um projeto Vite.
• Navegador: O usuário não pode executar CLI ou API. Direcione para https://neon.new.

API REST

URL Base: https://neon.new/api/v1

Criar um banco de dados

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

O connection_string retornado pela API é um URL de conexão agrupada. Para uma conexão direta (não agrupada) (por exemplo, migrações Prisma), remova -pooler do nome do host. A CLI escreve URLs agrupados e diretos automaticamente.

Resposta:

{
  "id": "019beb39-37fb-709d-87ac-7ad6198b89f7",
  "status": "UNCLAIMED",
  "neon_project_id": "gentle-scene-06438508",
  "connection_string": "postgresql://...",
  "claim_url": "https://neon.new/claim/019beb39-...",
  "expires_at": "2026-01-26T14:19:14.580Z",
  "created_at": "2026-01-23T14:19:14.580Z",
  "updated_at": "2026-01-23T14:19:14.580Z"
}

Verificar status

curl -s "https://neon.new/api/v1/database/{id}"

Retorna a mesma forma de resposta. Transições de status: UNCLAIMED -> CLAIMING -> CLAIMED. Após o banco de dados ser reivindicado, connection_string retorna null.

Respostas de erro

CLI

npx neon-new@latest --yes

Provisiona um banco de dados e escreve a string de conexão em .env em uma única etapa. Sempre use @latest e --yes (pula prompts interativos que parariam o agente).

Verificação pré-execução

Verifique se DATABASE_URL (ou a chave escolhida) já existe no .env de destino. A CLI sai sem provisionar se encontrar a chave.

Se a chave existir, ofereça ao usuário três opções:

1. Remova ou comente a linha existente e execute novamente.
2. Use --env para escrever em um arquivo diferente (por exemplo, --env .env.local).
3. Use --key para escrever sob um nome de variável diferente.

Obtenha confirmação antes de prosseguir.

Opções

| Opção | Alias | Descrição | Padrão |

…