Neon Object Storage

Il s'agit d'une fonction en bêta publique disponible uniquement dans us-east-2. Neon Object Storage est un stockage d'objets compatible S3 qui se décline par branche avec vos projets : chaque branche dispose de son propre état de stockage isolé, de sorte que les fichiers et les lignes de la base de données restent synchronisés entre les environnements de dev, preview, staging et production.

Utilisez cette skill pour aider l'utilisateur à stocker et servir des fichiers qui se déclineront avec sa base de données. Fournissez un bucket opérationnel et un flux d'upload/download, un client S3 conscient des branches connecté aux variables d'environnement injectées, ou une réponse précise tirée de la documentation officielle Neon.

When to Use

Exploitez Neon Object Storage lorsque l'utilisateur a besoin de stocker des fichiers (images, uploads, assets générés, documents, sauvegardes) et que l'une des conditions suivantes est vraie :

• Il utilise déjà Neon Postgres et ne veut pas d'un second fournisseur. Un backend, une facture, une CLI, un ensemble de branches — au lieu de mettre en place et de configurer un compte AWS S3 / R2 / Supabase Storage séparé. La même credential Neon qui soutient la base de données soutient le stockage.
• Les fichiers doivent rester synchronisés avec la base de données entre les environnements. Le stockage se décline en même temps que vos données Postgres. Forkez une branche et l'enfant hérite instantanément des buckets et objets du parent à ce moment précis — copie-à-l'écriture, donc aucune donnée n'est dupliquée. C'est ce qui rend les environnements d'agent, dev, preview et test transparents : une branche preview obtient un snapshot cohérent à la fois des lignes et des fichiers qu'elles référencent, et les écritures sur l'enfant ne touchent jamais le parent.
• Il veut des environnements sûrs et jetables. Uploadez, écrasez et supprimez des fichiers dans une branche preview/CI sans aucun risque pour les données de production, puis supprimez la branche.
• Il veut les outils S3 standards. Il est construit sur la sémantique S3 et parle l'API S3, donc les AWS SDKs, boto3, la AWS CLI et les URLs présignées fonctionnent tous — fiables et familiers, sans client propriétaire.

Si l'utilisateur n'a pas de projet Neon, n'est pas sur Postgres et a juste besoin d'un magasin d'assets CDN-backed autonome, un magasin d'objets dédié peut mieux convenir — mais dès que les fichiers cohérents par branche + les lignes importent, c'est la raison d'utiliser celui-ci.

What It Does

• Compatible S3 — Fonctionne avec les SDKs S3 existants, boto3, la AWS CLI et les URLs présignées. Adressage style chemin et SigV4 uniquement.
• Se décline avec votre base de données — Chaque branche Neon obtient son propre état de stockage isolé et copie-à-l'écriture. Forker ne copie aucune donnée.
• Deux modes d'accès — Les buckets private nécessitent une credential pour chaque opération ; les buckets public_read permettent les lectures anonymes avec écritures authentifiées.
• Un système de credential unique — Le même système de credential Neon utilisé par Functions et l'AI Gateway.

Setup

Le stockage d'objets fait partie de la config infrastructure-as-code neon.ts (voir la skill neon pour le workflow branch-first, link/checkout et les bases de neon.ts). Déclarez les buckets sous preview.buckets, indexés par nom de bucket :

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

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

Approvisionnez les buckets déclarés sur la branche liée :

neon deploy   # alias pour `neon config apply`

Neon Infrastructure as Code (neon.ts)

Le bloc preview.buckets ci-dessus fait partie de neon.ts, le fichier infrastructure-as-code de Neon — un seul fichier TypeScript déclare vos buckets à côté de chaque autre service que la branche devrait avoir (voir la skill neon pour la référence complète). Réconciliez la déclaration contre une branche à la manière de Terraform :

neon config status   # affiche la config live de la branche (quels buckets existent)
neon config plan     # dry-run diff de ce que apply changerait
neon config apply    # crée les buckets déclarés  (neon deploy est un alias)

Les buckets sont scoped à la branche : lorsqu'un neon.ts est présent, neon checkout applique la politique lors de la création d'une branche, donc une branche preview/CI fraîche se lève avec ses buckets déjà approvisionnés (et les objets copie-à-l'écriture hérités du parent). Checker out une branche existante ne la réconcilie pas — exécutez neon deploy pour appliquer les changements. L'approvisionnement (config apply / deploy), link et checkout tirent aussi les credentials S3 de la branche dans votre .env.local local, donc la même étape env pull montrée ci-dessous se fait pour vous sur ces commandes.

Pour un accès typé et validé aux credentials S3 injectées, passez le même objet config à parseEnv from @neon/env — il retourne un namespace env.storage (accessKeyId, secretAccessKey, endpoint, region) dérivé de votre neon.ts.

Environment variables

Lorsque preview.buckets est déclaré, Neon injecte les variables d'environnement S3 standards AWS de sorte que les AWS SDKs fonctionnent à partir de l'environnement sans configuration supplémentaire. À l'intérieur d'une Neon Function déployée, elles sont injectées automatiquement ; localement, tirez-les sur disque (ou injectez-les à l'exécution) via la CLI :

neon env pull            # écrit les variables de la branche dans .env (ou .env.local)
# ou, sans écrire de fichier, injectez à l'exécution :
neon-env run -- <your dev command>

Parce que les noms sont standards AWS, le AWS SDK récupère les credentials, endpoint et région de l'environnement automatiquement. Les credentials sont scoped à la branche et valides pour cette branche et tous ses descendants.

Working with objects: the Files SDK (recommended)

Le moyen le plus simple et le plus portable de lire et écrire des objets est le Files SDK avec son adaptateur neon — une petite API de stockage unifiée (upload, download, url, list, exists, copy, delete, signedUploadUrl) sur I/O web-standard. Il utilise le client AWS S3 sous le capot, configuré de manière appropriée pour Neon, et réétiquette les erreurs comme Neon error — donc il n'y a rien à mal configurer. Allez-y d'abord.

Installez-le à côté des dépendances pair AWS S3 que l'adaptateur utilise en interne :

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

L'adaptateur résout son endpoint, région et credentials à partir des mêmes variables d'environnement AWS_* injectées — ne passez que le nom du bucket :

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

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

// Upload — body peut être un 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 — partager sans exposer les credentials (defaults à 1h d'expiry)
const url = await files.url("generated/cat.jpg", { expiresIn: 3600 });

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

Échangez l'import d'adaptateur (files-sdk/s3, files-sdk/r2, files-sdk/gcs, …) et le reste de votre code est inchangé.

Working with objects: the AWS S3 client (alternative)

Neon parle l'API S3 directement, donc vous pouvez descendre au AWS SDK chaque fois que vous préférez le client natif ou dépendez déjà de lui. Les credentials, endpoint et région sont lus à partir de la chaîne d'environnement AWS standard, donc le seul paramètre que vous passez est forcePathStyle: true — Neon nécessite l'adressage style chemin, donc le client S3 doit le définir :

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

const s3 = new S3Client({
  forcePathStyle: true, // requis : Neon utilise l'adressage style chemin
});

Si vous préférez l'accès typé au lieu de lire process.env directement, parseEnv (from @neon/env) retourne un namespace validé env.storage (accessKeyId, secretAccessKey, endpoint, region) dérivé de votre neon.ts — voir la skill neon.

Puis uploadez, téléchargez et présignez avec les objets de commande bruts :

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 — partager sans exposer les credentials
const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
  { expiresIn: 3600 },
);

Le pattern canonique pour jumeler le stockage avec la base de données sur une branche : un agent génère une image → PutObject dans le bucket images → une ligne est insérée dans Postgres → une URL présignée est retournée à la lecture. Stockez la clé du bucket (pas les bytes) dans une colonne Postgres, et présignez à la lecture. Parce que la ligne et l'objet vivent sur la même branche, ils se déclinent ensemble et ne dérivent jamais.

neon a aussi des commandes bucket/objet de première classe (neon bucket create|list|delete, neon bucket object put|get|list|delete) pour les scripts et les opérations ponctuelles.

Availability

Neon Object Storage est une fonction en bêta publique disponible uniquement sur les nouveaux projets de la région us-east-2. Confirmez que le projet Neon de l'utilisateur est un nouveau projet dans us-east-2 avant de procéder ; il ne peut pas être activé sur les projets existants.

Neon Documentation

La documentation Neon est la source de vérité et Object Storage évolue rapidement, donc vérifiez toujours contre les docs officiels. N'importe quelle page de doc peut être récupérée en markdown en ajoutant .md à l'URL ou en demandant Accept: text/markdown. Trouvez la bonne page à partir de l'index des docs (https://neon.com/docs/llms.txt) et les annonces du changelog.

Further reading

• 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 — Files SDK docs (l'adaptateur neon)