Armazenamento de Objetos Neon

Este é um recurso de pré-visualização e está disponível apenas em us-east-2. O Armazenamento de Objetos Neon é um armazenamento de objetos compatível com S3 que se ramifica com seus projetos: cada ramificação obtém seu próprio estado de armazenamento isolado, para que arquivos e linhas de banco de dados permaneçam sincronizados entre desenvolvimento, pré-visualização, staging e produção.

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

Quando Usar

Recorra ao Armazenamento de Objetos Neon quando o usuário precisar armazenar arquivos (imagens, uploads, ativos gerados, documentos, backups) e qualquer uma das seguintes condições for verdadeira:

• Eles já usam Neon Postgres e não querem um segundo provedor. Um backend, uma fatura, um CLI, um conjunto de ramificações — em vez de configurar e conectar uma conta separada de AWS S3 / R2 / Supabase Storage. A mesma credencial Neon que suporta o banco de dados suporta o armazenamento.
• Os arquivos devem permanecer sincronizados com o banco de dados entre os ambientes. O armazenamento se ramifica junto com seus dados Postgres. Ao criar um fork de uma ramificação, a filha herda instantaneamente os buckets e objetos da pai naquele momento — copy-on-write, para que nenhum dado seja duplicado. É isso que torna os ambientes de agente, desenvolvimento, pré-visualização e teste perfeitos: uma ramificação de pré-visualização obtém um snapshot consistente de ambas as linhas e os arquivos que elas referenciam, e as gravações na filha nunca afetam a pai.
• Eles querem ambientes seguros e descartáveis. Faça upload, substitua e exclua arquivos em uma ramificação de pré-visualização/CI sem nenhum risco para os dados de produção, e então exclua a ramificação.
• Eles querem ferramentas S3 padrão. Ele é construído sobre semânticas S3 e fala a API S3, então os SDKs da AWS, boto3, o AWS CLI e URLs pré-assinados funcionam — confiáveis e familiares, sem um cliente proprietário.

Se o usuário não tiver um projeto Neon, não estiver usando Postgres e apenas precisar de um armazenamento de ativos independente com suporte de CDN, um armazenamento de objetos dedicado pode ser mais adequado — mas no momento em que arquivos consistentes com ramificações + linhas importam, esta é a razão para usá-lo.

O Que Faz

• Compatível com S3 — Funciona com SDKs S3 existentes, boto3, o AWS CLI e URLs pré-assinados. Apenas endereçamento em estilo de caminho e SigV4.
• Ramifica com seu banco de dados — Cada ramificação Neon obtém seu próprio estado de armazenamento isolado e copy-on-write. A criação de 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 Neon usado por Funções e o AI Gateway.

Configuração

O armazenamento de objetos faz parte da configuração de infraestrutura como código neon.ts (veja a habilidade neon para o fluxo de trabalho "branch-first", link/checkout e noções básicas de neon.ts). Declare buckets sob preview.buckets, com chave pelo nome do bucket:

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

export default defineConfig({
  preview: {
    buckets: {
      images: {}, // private by default
      "public-assets": { access: "public_read" },
    },
  },
});

Provisão dos buckets declarados na ramificação vinculada:

neon deploy   # alias for `neon config apply`

Infraestrutura Neon como Código (neon.ts)

O bloco preview.buckets acima faz parte de neon.ts, o arquivo de infraestrutura como código do Neon — um único arquivo TypeScript declara seus buckets ao lado de todos os outros serviços que a ramificação deve ter (veja a habilidade neon para a referência completa). Reconcilie a declaração com uma ramificação da maneira Terraform:

neon config status   # print the branch's live config (which buckets exist)
neon config plan     # dry-run diff of what apply would change
neon config apply    # create the declared buckets  (neon deploy is an alias)

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

…