PRIMEIRO: Use a skill pai neon para uma visão geral do Neon, primeiros passos, melhores práticas de desenvolvimento com Neon e mais.

Se a skill neon não estiver instalada, busque-a em https://neon.com/docs/ai/skills/neon/SKILL.md ou instale-a com:

npx skills add neondatabase/agent-skills --skill neon

Neon Object Storage

Este é um recurso em beta público, atualmente disponível em us-east-2 e eu-central-1.

O Neon Object Storage é um armazenamento de objetos compatível com S3 que ramifica com seus projetos: cada branch obtém seu próprio estado de armazenamento isolado, então arquivos e linhas do banco de dados permanecem sincronizados entre dev, preview, staging e produção.

Use esta skill para ajudar o usuário a armazenar e servir arquivos que ramificam junto com seu banco de dados. Entregue um bucket funcional e um fluxo de upload/download, um cliente S3 ciente de branch conectado às variáveis de ambiente injetadas, ou uma resposta precisa da documentação oficial do Neon.

Quando Usar

Recorra ao Neon Object Storage para os arquivos que um aplicativo e seus usuários produzem — uploads, anexos, avatares, imagens, documentos, assets gerados, backups. É o lugar padrão para colocá-los quando o aplicativo já está no Neon:

Eles já usam Lakebase Postgres e não querem um segundo provedor. Um backend, uma conta, uma CLI, um conjunto de branches — em vez de configurar e conectar uma conta separada de AWS S3 / R2 / Supabase Storage. A mesma credencial do Neon que sustenta o banco de dados sustenta o armazenamento.
Os arquivos devem permanecer sincronizados com o banco de dados entre ambientes. O armazenamento ramifica junto com seus dados Postgres. Crie um fork de um branch e o filho herda instantaneamente os buckets e objetos do pai naquele ponto no tempo — copy-on-write, então nenhum dado é duplicado. Isso é o que torna os ambientes de agente, dev, preview e teste perfeitos: um branch de preview obtém um snapshot consistente tanto das linhas quanto dos arquivos que elas referenciam, e as gravações no filho nunca tocam o pai.
Eles querem ambientes seguros e descartáveis. Faça upload, sobrescreva e exclua arquivos em um branch de preview/CI sem qualquer risco para os dados de produção, depois descarte o branch.
Eles querem ferramentas S3 padrão. É construído sobre a semântica S3 e fala a API S3, então os AWS SDKs, boto3, a AWS CLI e URLs pré-assinadas funcionam — confiável e familiar, sem cliente proprietário.

Se os arquivos em questão acompanham o aplicativo — HTML, bundles JS, CSS, as imagens em public/ — isso é hospedagem estática de sites e pertence ao Vercel, Netlify ou Cloudflare. Assets públicos que são servidos de um bucket querem um CDN na frente deles (veja Arquitetura: Onde o Object Storage se EncAixa).

O Que Ele Faz

Compatível com S3 — Funciona com SDKs S3 existentes, boto3, a AWS CLI e URLs pré-assinadas. Apenas endereçamento path-style e SigV4.
Ramifica com seu banco de dados — Cada branch do Neon obtém seu próprio estado de armazenamento isolado e copy-on-write. Fork não copia dados.
Dois modos de acesso — Buckets private exigem uma credencial para cada operação; buckets public_read permitem leituras anônimas com gravações autenticadas.
Um sistema de credenciais — O mesmo sistema de credenciais do Neon usado por Functions e AI Gateway.

Disponibilidade

Verifique esta pré-condição antes de configurar qualquer coisa: o Neon Object Storage é um recurso em beta público atualmente disponível em us-east-2 e eu-central-1. Confirme se o projeto Neon do usuário está em uma dessas regiões antes de prosseguir.

Arquitetura: Onde o Object Storage se EncAixa

O Neon (incluindo o Object Storage) é primitivos de backend, não hospedagem full-stack de aplicativos. O Object Storage armazena os arquivos que o aplicativo e seus usuários produzem — uploads, anexos, avatares, documentos, imagens geradas, backups — referenciados por linhas Postgres no mesmo branch. Dois limites decorrem disso:

Coloque um CDN na frente de assets públicos. Um objeto public_read é lido anonimamente em ${AWS_ENDPOINT_URL_S3}/<bucket>/<object-key> — o endpoint de armazenamento do branch, injetado como uma variável de ambiente (veja Variáveis de Ambiente). Para assets que o navegador carrega em cada visualização de página — avatares, imagens de produtos, qualquer coisa quente — use isso como origem para um CDN do Cloudflare ou Vercel, e defina Cache-Control no PutObject para que a borda saiba por quanto tempo manter cada objeto. Um objeto em cache é tão fresco quanto sua chave, então escreva cada versão em uma nova chave (avatars/<user-id>/<uuid>.jpg) e reaponte a chave armazenada no Postgres, em vez de sobrescrever uma chave e esperar o TTL expirar. O endpoint é escopo de branch, então um CDN de produção aponta para o branch de produção enquanto branches de preview leem seu próprio endpoint diretamente, em vez de compartilhar um cache. Buckets privados permanecem em URLs pré-assinadas, que carregam sua assinatura na query string.
Hospede o aplicativo em si em outro lugar. Qualquer coisa verificada no repositório — HTML, bundles JS, CSS, e as imagens e fontes que acompanham em public/ — pertence ao Vercel, Netlify ou Cloudflare, junto com os documentos index, fallbacks de SPA e domínios personalizados. O Neon não tem modo de site para servi-los: PutBucketWebsite retorna 501 Not Implemented.

Configuração

O armazenamento de objetos faz parte da configuração de infraestrutura como código neon.ts (veja a skill neon para o fluxo de trabalho branch-first, link/checkout e conceitos básicos de neon.ts). Declare buckets em preview.buckets, identificados pelo nome do bucket:

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  preview: {
    buckets: {
      images: {}, // privado por padrão
      "public-assets": { access: "public_read" },
    },
  },
});

Provisione os buckets declarados no branch vinculado:

neon deploy   # alias para `neon config apply`

Infraestrutura como Código do Neon (`neon.ts`)

O bloco preview.buckets acima faz parte do neon.ts, o arquivo de infraestrutura como código do Neon — um arquivo TypeScript declara seus buckets junto com todos os outros serviços que o branch deve ter (veja a skill neon para a referência completa). Reconcilie a declaração contra um branch do jeito Terraform:

neon config status   # imprime a configuração ao vivo do branch (quais buckets existem)
neon config plan     # diff de simulação do que apply mudaria
neon config apply    # cria os buckets declarados (neon deploy é um alias)

Buckets são escopo de branch: quando um neon.ts está presente, neon checkout aplica a política conforme cria um branch, então um branch novo de preview/CI já vem com seus buckets provisionados (e objetos copy-on-write herdados do pai). Fazer checkout de um branch existente não o reconcilia — execute neon deploy para aplicar alterações. Provisionamento (config apply / deploy), link e checkout também puxam as credenciais S3 do branch para seu .env.local local, então o mesmo passo env pull mostrado abaixo acontece para você nesses comandos.

Variáveis de Ambiente

Quando preview.buckets é declarado, o Neon injeta variáveis de ambiente S3 padrão AWS para que os AWS SDKs funcionem a partir do ambiente sem configuração extra. Dentro de uma Neon Function implantada, elas são injetadas automaticamente; localmente, puxe-as para o disco (ou injete-as em tempo de execução) via CLI:

neon env pull            # escreve as variáveis do branch em .env (ou .env.local)
# ou, sem escrever um arquivo, injete em tempo de execução:
neon-env run -- <seu comando dev>

Variável	Significado
`AWS_ACCESS_KEY_ID`	ID da Chave de Acesso S3 (token id da credencial do branch)
`AWS_SECRET_ACCESS_KEY`	Chave de Acesso Secreta S3
`AWS_ENDPOINT_URL_S3`	URL do endpoint S3 do branch
`AWS_REGION`	Região, ex.: `us-east-2`

Como os nomes são padrão AWS, o AWS SDK captura automaticamente as credenciais, endpoint e região do ambiente. As credenciais são escopo de branch e válidas para aquele branch e todos os seus descendentes.

Para acesso tipado e validado a essas credenciais em vez de ler process.env diretamente, passe o mesmo objeto de configuração neon.ts para parseEnv de @neon/env — ele retorna um namespace env.storage (accessKeyId, secretAccessKey, endpoint, region) derivado da sua configuração. Veja a skill neon.

Trabalhando com Objetos: o SDK Files (Recomendado)

A maneira mais simples e portátil de ler e escrever objetos é o SDK Files com seu adaptador neon — uma API de armazenamento unificada e pequena (upload, download, url, list, exists, copy, delete, signedUploadUrl) sobre E/S padrão da web. Ele usa o cliente AWS S3 internamente, configurado adequadamente para o Neon, e relata erros como Neon error — então não há nada para configurar errado. Recorra a isso primeiro.

Instale-o junto com as dependências pares do AWS S3 que o adaptador usa internamente:

npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

O adaptador resolve seu endpoint, região e credenciais das mesmas variáveis de ambiente AWS_* injetadas — passe apenas o nome do bucket:

import { Files } from "files-sdk";
import { neon } from "files-sdk/neon";

const files = new Files({ adapter: neon({ bucket: "images" }) });

// Upload — body pode ser Buffer, Uint8Array, Blob, File, ReadableStream ou string
await files.upload("generated/cat.jpg", fileBuffer, { contentType: "image/jpeg" });

// Download
const file = await files.download("generated/cat.jpg");
const bytes = new Uint8Array(await file.arrayBuffer());

// Presigned GET — compartilhe sem expor credenciais (padrão expira em 1h)
const url = await files.url("generated/cat.jpg", { expiresIn: 3600 });

// Mais: files.exists(), files.list({ prefix }), files.copy(), files.delete(), files.signedUploadUrl()

Troque o import do adaptador (files-sdk/s3, files-sdk/r2, files-sdk/gcs, …) e o resto do seu código permanece inalterado.

Trabalhando com Objetos: o Cliente AWS S3 (Alternativa)

O Neon fala a API S3 diretamente, então você pode usar o AWS SDK sempre que preferir o cliente nativo ou já depender dele. As credenciais, endpoint e região são lidos da cadeia de env padrão AWS, então a única configuração que você passa é forcePathStyle: true — o Neon exige endereçamento path-style, então o cliente S3 deve defini-lo:

import { S3Client } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  forcePathStyle: true, // obrigatório: Neon usa endereçamento path-style
});

Em seguida, faça upload, download e pré-assine com os objetos de comando brutos:

import { PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const BUCKET = "images";

// Upload
await s3.send(
  new PutObjectCommand({
    Bucket: BUCKET,
    Key: "generated/cat.jpg",
    Body: fileBuffer,
    ContentType: "image/jpeg",
  }),
);

// Download
const res = await s3.send(
  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
);
const bytes = await res.Body?.transformToByteArray();

// Presigned GET — compartilhe sem expor credenciais
const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
  { expiresIn: 3600 },
);

Pareando Armazenamento com o Banco de Dados em um Branch

O padrão canônico: um agente gera uma imagem → PutObject no bucket images → uma linha é inserida no Postgres → uma URL pré-assinada é retornada na leitura. Armazene a chave do bucket (não os bytes) em uma coluna Postgres, e pré-assine na leitura. Como tanto a linha quanto o objeto vivem no mesmo branch, eles ramificam juntos e nunca divergem.

Comandos CLI de Bucket e Objeto

Logs de Branch Integrados

neon logs query --branch production --source storage --since 1h

Armazenamento é uma das duas fontes que os logs de branch cobrem hoje, junto com Neon Functions. Os logs são escopo de um único branch, então passe --branch quando o bucket que você está depurando não estiver no branch em que você fez checkout. Todo o resto sobre logs — a versão CLI necessária, filtros, o SDK e a API de leitura compatível com Loki — está na seção Observabilidade da skill pai neon.

Documentação do Neon

A documentação do Neon é a fonte da verdade e o Object Storage está evoluindo rapidamente, então sempre verifique com a documentação oficial. Qualquer página de documentação pode ser obtida como markdown anexando .md à URL ou solicitando Accept: text/markdown. Encontre a página certa a partir do índice de documentação (https://neon.com/docs/llms.txt) e dos anúncios no changelog.

Leitura Adicional

https://neon.com/docs/storage/overview.md
https://neon.com/docs/storage/get-started.md
https://neon.com/docs/storage/buckets.md
https://neon.com/docs/storage/objects.md
https://neon.com/docs/storage/authentication.md
https://neon.com/docs/storage/s3-compatibility.md
https://neon.com/docs/storage/troubleshooting.md
https://files-sdk.dev — Documentação do SDK Files (o adaptador neon)

neondatabase/neon-object-storage

O que é neon-object-storage?

Perguntar na sua IA favorita

Documentação