neondatabase/neon-object-storage

PRIMERO: Usa el skill principal neon para obtener una visión general de Neon, cómo empezar, las mejores prácticas de desarrollo y más.

Si el skill neon no está instalado, obténlo desde https://neon.com/docs/ai/skills/neon/SKILL.md o instálalo con:

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

Neon Object Storage

Esta es una función en beta pública, actualmente disponible en us-east-2 y eu-central-1.

Neon Object Storage es un almacenamiento de objetos compatible con S3 que se ramifica junto con tus proyectos: cada rama obtiene su propio estado de almacenamiento aislado, por lo que los archivos y las filas de la base de datos se mantienen sincronizados en los entornos de desarrollo, previsualización, staging y producción.

Usa este skill para ayudar al usuario a almacenar y servir archivos que se ramifiquen junto con su base de datos. Entrega un bucket funcional y un flujo de subida/descarga, un cliente S3 consciente de las ramas conectado a las variables de entorno inyectadas, o una respuesta precisa de la documentación oficial de Neon.

Cuándo Usarlo

Recurre a Neon Object Storage para los archivos que una aplicación y sus usuarios producen: subidas, adjuntos, avatares, imágenes, documentos, activos generados, copias de seguridad. Es el lugar predeterminado para colocarlos cuando la aplicación ya está en Neon:

• Ya usan Lakebase Postgres y no quieren un segundo proveedor. Un backend, una factura, una CLI, un conjunto de ramas, en lugar de configurar y conectar cuentas separadas de AWS S3 / R2 / Supabase Storage. La misma credencial de Neon que respalda la base de datos respalda el almacenamiento.
• Los archivos deben permanecer sincronizados con la base de datos en todos los entornos. El almacenamiento se ramifica junto con tus datos de Postgres. Bifurca una rama y la hija hereda instantáneamente los buckets y objetos del padre en ese punto en el tiempo — copy-on-write, sin duplicar datos. Esto es lo que hace que los entornos de agente, desarrollo, previsualización y prueba sean perfectos: una rama de previsualización obtiene una instantánea coherente tanto de las filas como de los archivos que referencian, y las escrituras en la hija nunca afectan al padre.
• Quieren entornos seguros y desechables. Sube, sobrescribe y elimina archivos en una rama de previsualización/CI sin ningún riesgo para los datos de producción, y luego elimina la rama.
• Quieren herramientas S3 estándar. Está construido sobre semántica S3 y habla la API de S3, por lo que los SDK de AWS, boto3, la AWS CLI y las URL prefirmadas funcionan de manera confiable y familiar, sin necesidad de un cliente propietario.

Si los archivos en cuestión se envían con la propia aplicación (HTML, bundles JS, CSS, las imágenes en public/), eso es alojamiento web estático y pertenece a Vercel, Netlify o Cloudflare. Los activos públicos que se sirven desde un bucket necesitan un CDN delante de ellos (consulta Arquitectura: Dónde Encaja Object Storage).

Qué Hace

• Compatible con S3 — Funciona con los SDK de S3 existentes, boto3, la AWS CLI y URL prefirmadas. Solo direccionamiento path-style y SigV4.
• Se ramifica con tu base de datos — Cada rama de Neon obtiene su propio estado de almacenamiento aislado y copy-on-write. Bifurcar no copia datos.
• Dos modos de acceso — Los buckets private requieren una credencial para cada operación; los buckets public_read permiten lecturas anónimas con escrituras autenticadas.
• Un solo sistema de credenciales — El mismo sistema de credenciales de Neon utilizado por Functions y AI Gateway.

Disponibilidad

Verifica esta condición antes de configurar cualquier cosa: Neon Object Storage es una función en beta pública actualmente disponible en us-east-2 y eu-central-1. Confirma que el proyecto Neon del usuario esté en una de estas regiones antes de continuar.

Arquitectura: Dónde Encaja Object Storage

Neon (incluido Object Storage) son primitivas de backend, no alojamiento full-stack de aplicaciones. Object Storage contiene los archivos que la aplicación y sus usuarios producen: subidas, adjuntos, avatares, documentos, imágenes generadas, copias de seguridad, referenciados desde filas de Postgres en la misma rama. De esto se derivan dos límites:

• Pon un CDN delante de los activos públicos. Un objeto public_read se lee anónimamente en ${AWS_ENDPOINT_URL_S3}/<bucket>/<object-key> — el endpoint de almacenamiento de la rama, inyectado como variable de entorno (consulta Variables de Entorno). Para activos que el navegador carga en cada vista de página (avatares, imágenes de producto, etc.), usa ese endpoint como origen para un CDN de Cloudflare o Vercel, y establece Cache-Control en PutObject para que el edge sepa cuánto tiempo retener cada objeto. Un objeto en caché solo es tan fresco como su clave, así que escribe cada versión en una nueva clave (avatars/<user-id>/<uuid>.jpg) y vuelve a apuntar la clave almacenada en Postgres, en lugar de sobrescribir una clave y esperar el TTL. El endpoint está limitado a la rama, por lo que un CDN de producción apunta a la rama de producción mientras que las ramas de previsualización leen su propio endpoint directamente, sin compartir caché. Los buckets privados, en cambio, usan URL prefirmadas, que llevan su firma en la cadena de consulta.
• Aloja la aplicación en otro lugar. Todo lo que está en el repositorio (HTML, bundles JS, CSS, y las imágenes y fuentes en public/) pertenece a Vercel, Netlify o Cloudflare, junto con los documentos índice, fallbacks SPA y dominios personalizados. Neon no tiene un modo de sitio web para servirlos: PutBucketWebsite devuelve 501 Not Implemented.

Configuración

Object storage es parte del archivo de configuración de infraestructura como código neon.ts (consulta el skill neon para el flujo de trabajo branch-first, link/checkout, y los conceptos básicos de neon.ts). Declara los buckets bajo preview.buckets, con el nombre del bucket como clave:

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

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

Aprovisiona los buckets declarados en la rama vinculada:

neon deploy   # alias de `neon config apply`

Infraestructura de Neon como Código (neon.ts)

El bloque preview.buckets anterior es parte de neon.ts, el archivo de infraestructura como código de Neon — un solo archivo TypeScript declara tus buckets junto con cualquier otro servicio que la rama deba tener (consulta el skill neon para la referencia completa). Reconoce la declaración contra una rama al estilo Terraform:

neon config status   # imprime la configuración en vivo de la rama (qué buckets existen)
neon config plan     # diff de prueba de lo que apply cambiaría
neon config apply    # crea los buckets declarados (neon deploy es un alias)

Los buckets están limitados a la rama: cuando hay un neon.ts presente, neon checkout aplica la política al crear una rama, por lo que una rama nueva de previsualización/CI ya viene con sus buckets aprovisionados (y objetos heredados copy-on-write del padre). Al hacer checkout de una rama existente no se reconcilia — ejecuta neon deploy para aplicar cambios. El aprovisionamiento (config apply / deploy), link y checkout también obtienen las credenciales S3 de la rama en tu .env.local, por lo que el mismo paso de env pull que se muestra a continuación ocurre automáticamente en esos comandos.

Variables de Entorno

Cuando se declara preview.buckets, Neon inyecta variables de entorno S3 estándar de AWS para que los SDK de AWS funcionen desde el entorno sin configuración adicional. Dentro de una Neon Function desplegada se inyectan automáticamente; localmente, obténlas en disco (o inyéctalas en tiempo de ejecución) a través de la CLI:

neon env pull            # escribe las vars de la rama en .env (o .env.local)
# o, sin escribir un archivo, inyéctalo en tiempo de ejecución:
neon-env run -- <tu comando de desarrollo>

Variable	Significado
AWS_ACCESS_KEY_ID	ID de clave de acceso S3 (el token id de la credencial de la rama)
AWS_SECRET_ACCESS_KEY	Clave de acceso secreta S3
AWS_ENDPOINT_URL_S3	URL del endpoint S3 de la rama
AWS_REGION	Región, ej. us-east-2

Debido a que los nombres son estándar de AWS, el SDK de AWS recoge las credenciales, el endpoint y la región del entorno automáticamente. Las credenciales están limitadas a la rama y son válidas para esa rama y todos sus descendientes.

Para acceso tipificado y validado a estas credenciales en lugar de leer process.env directamente, pasa el mismo objeto de configuración neon.ts a parseEnv de @neon/env — devuelve un espacio de nombres env.storage (accessKeyId, secretAccessKey, endpoint, region) derivado de tu configuración. Consulta el skill neon.

Trabajar con Objetos: el Files SDK (Recomendado)

La forma más simple y portátil de leer y escribir objetos es el Files SDK con su adaptador neon — una API de almacenamiento unificada y pequeña (upload, download, url, list, exists, copy, delete, signedUploadUrl) sobre E/S estándar web. Utiliza el cliente S3 de AWS internamente, configurado apropiadamente para Neon, y etiqueta los errores como Neon error — por lo que no hay nada que configurar mal. Recurre a esto primero.

Instálalo junto con las dependencias pares del AWS S3 que el adaptador usa internamente:

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

El adaptador resuelve su endpoint, región y credenciales de las mismas variables de entorno AWS_* inyectadas — pasa solo el nombre del bucket:

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

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

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

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

// GET prefirmado — compartir sin exponer credenciales (por defecto caduca en 1h)
const url = await files.url("generated/cat.jpg", { expiresIn: 3600 });

// Además: files.exists(), files.list({ prefix }), files.copy(), files.delete(), files.signedUploadUrl()

Cambia la importación del adaptador (files-sdk/s3, files-sdk/r2, files-sdk/gcs, …) y el resto de tu código queda igual.

Trabajar con Objetos: el AWS S3 Client (Alternativa)

Neon habla directamente la API de S3, por lo que puedes bajar al SDK de AWS cuando prefieras el cliente nativo o ya dependas de él. Las credenciales, endpoint y región se leen de la cadena estándar de AWS, por lo que la única configuración que debes pasar es forcePathStyle: true — Neon requiere direccionamiento path-style, por lo que el cliente S3 debe establecerlo:

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

const s3 = new S3Client({
  forcePathStyle: true, // requerido: Neon usa direccionamiento path-style
});

Luego sube, descarga y prefirma con los objetos de comando crudos:

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

const BUCKET = "images";

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

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

// GET prefirmado — compartir sin exponer credenciales
const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
  { expiresIn: 3600 },
);

Emparejar Almacenamiento con la Base de Datos en una Rama

El patrón canónico: un agente genera una imagen → PutObject en el bucket images → se inserta una fila en Postgres → se devuelve una URL prefirmada en la lectura. Almacena la clave del bucket (no los bytes) en una columna de Postgres, y prefirma en la lectura. Debido a que tanto la fila como el objeto viven en la misma rama, se ramifican juntos y nunca se desvían.

Comandos CLI de Bucket y Objeto

neon también tiene comandos de bucket/objeto de primera clase (neon bucket create|list|delete, neon bucket object put|get|list|delete) para scripting y operaciones puntuales.

Logs de Rama Integrados

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

Storage es una de las dos fuentes que cubren los logs de rama hoy, junto con Neon Functions. Los logs están limitados a una sola rama, por lo que pasa --branch cuando el bucket que estás depurando no está en la rama en la que tienes checkout. Todo lo demás sobre los logs (la versión requerida de CLI, filtros, el SDK y la API de lectura compatible con Loki) está en la sección Observabilidad del skill principal neon.

Documentación de Neon

La documentación de Neon es la fuente de verdad y Object Storage está evolucionando rápidamente, por lo que siempre debes verificar contra la documentación oficial. Cualquier página de documentación se puede obtener como markdown añadiendo .md a la URL o solicitando Accept: text/markdown. Encuentra la página correcta desde el índice de documentación (https://neon.com/docs/llms.txt) y los anuncios del changelog.

Lectura 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 — Documentación del Files SDK (el adaptador neon)