Store and sync files alongside Postgres with branching

Helps set up and use Neon Object Storage, a preview feature (us-east-2 only) providing S3-compatible object storage that branches together with a Neon project - every branch gets its own isolated, copy-on-write storage state, so forking a branch instantly inherits the parent's buckets and objects without duplicating data, and writes on the child never touch the parent. Buckets are declared under preview.buckets in neon.ts, keyed by name, with two access modes: private (a credential required for every operation) or public_read (anonymous reads, authenticated writes). Provisioning follows the same infrastructure-as-code flow as other Neon services - neon config status/plan/apply (neon deploy is an alias) - and a fresh branch created via neon checkout when neon.ts is present comes up with its buckets already provisioned; checking out an existing branch does not reconcile it. Neon injects four AWS-standard env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL_S3, AWS_REGION) so AWS SDKs work with zero config, or parseEnv from @neon/env returns a typed env.storage namespace. The recommended access path is the Files SDK's neon adapter, a small unified API (upload, download, url, list, exists, copy, delete, signedUploadUrl) built on the AWS S3 client under the hood, configured for Neon automatically - swapping the adapter import (files-sdk/s3, files-sdk/r2, files-sdk/gcs) is the only change needed to target a different backend. The alternative is the raw AWS S3 client, which reads credentials from the same env chain but requires explicitly setting forcePathStyle: true, since Neon uses path-style addressing. The canonical pairing pattern: an agent generates a file, PutObjects it into a bucket, inserts a Postgres row referencing the object key (never the raw bytes), and presigns a URL on read - because the row and the object live on the same branch, they branch together and never drift. The neon CLI also has first-class bucket and object commands (neon bucket create|list|delete, neon bucket object put|get|list|delete) for scripting.

Use it when the user already runs Neon Postgres and wants files to stay in sync with database rows across dev, preview, staging, and production branches, wants safe throwaway preview/CI environments for file uploads without risking production data, or wants standard S3 tooling (AWS SDKs, boto3, AWS CLI, presigned URLs) without a proprietary client. If the user has no Neon project, isn't on Postgres, and just needs a standalone CDN-backed asset store with no branch-consistency requirement, a dedicated object store may fit better. The feature is preview-only, limited to new projects in us-east-2 - it cannot be enabled on existing projects.

Input is a file (Buffer, Uint8Array, Blob, File, ReadableStream, or string) plus a bucket and object key. Output is a stored object, a downloaded byte stream, or a presigned URL for sharing access without exposing credentials.

Uses the same Neon credential system as Functions and the AI Gateway, is S3-API-compatible (AWS SDKs, boto3, AWS CLI, presigned URLs all work), and is most simply accessed through the Files SDK's neon adapter or directly via @aws-sdk/client-s3.

Developers on Neon Postgres who need uploaded or generated files - images, documents, backups, agent-generated assets - to branch consistently alongside their database rows across dev, preview, and production environments.