neon-object-storage

intent

Neon Object Storage is S3-compatible object storage that branches with your Neon project: every branch gets its own isolated storage state, so files and database rows stay in sync across dev, preview, staging, and production. Use this skill when the user needs to store and serve files (images, uploads, generated assets, documents, backups) that must stay consistent with database state across branches, or when they already use Neon Postgres and want one backend, one credential system, and one set of branches instead of juggling a separate storage provider. Deliver a working bucket and upload/download flow, a branch-aware S3 client wired to the injected env vars, or a precise answer from the official Neon docs.

inputs

prerequisites

• Neon project must be new and located in us-east-2 region. Neon Object Storage is public beta and not available on existing projects or other regions.
• Neon CLI installed (npm install -g neondb or brew install neon).
• A neon.ts config file in the project root (see the neon skill for setup).
• Parent neon skill for Neon overview, getting started, and branch-first workflow. If not installed, fetch from https://neon.com/docs/ai/skills/neon/SKILL.md or install with npx skills add neondatabase/agent-skills --skill neon.

external connections

• Neon account and project: OAuth token stored in ~/.config/neon/credentials.json or NEON_API_KEY env var. Set up via neon auth or https://console.neon.tech.
• AWS SDK (peer dependency): The Files SDK or AWS S3 client requires @aws-sdk/client-s3, @aws-sdk/s3-presigned-post, and @aws-sdk/s3-request-presigner to be installed.
• Files SDK (optional but recommended): files-sdk package with the neon adapter for a simpler, unified storage API.

environment variables injected by Neon

When preview.buckets is declared in neon.ts, Neon injects AWS-standard S3 env vars. Pull them locally via neon env pull or neon-env run:

• AWS_ACCESS_KEY_ID: S3 Access Key ID (branch credential token id).
• AWS_SECRET_ACCESS_KEY: S3 Secret Access Key.
• AWS_ENDPOINT_URL_S3: Branch S3 endpoint URL.
• AWS_REGION: Region, e.g., us-east-2.

In Neon Functions, these are injected automatically. For typed, validated access, use parseEnv from @neon/env with your neon.ts config object to get an env.storage namespace.

procedure

1. verify region and project eligibility

Input: User's Neon project details. Steps:

• Confirm the Neon project is new (created after Neon Object Storage became available in beta) and located in us-east-2 region.
• If the project is existing or in a different region, stop and inform the user that Object Storage is not available and advise them to create a new us-east-2 project or wait for expanded availability.

Output: Confirmed project is eligible to proceed.

2. declare buckets in neon.ts

Input: User's desired bucket names, access modes (private or public_read). Steps:

• Open or create neon.ts in the project root.
• Add a preview.buckets block to the defineConfig object, keyed by bucket name. Set access: "public_read" for public-read buckets; omit the access key for private (default) buckets.
• Example:

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

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

Output: Updated neon.ts with bucket declarations.

3. provision buckets on the current branch

Input: Completed neon.ts with preview.buckets declared. Steps:

• Run neon deploy (alias for neon config apply) to create the declared buckets on the linked branch.
• Optionally, run neon config status to view the branch's live config or neon config plan to dry-run the diff.

Output: Buckets created on the branch; S3 credentials written to .env.local or pulled via neon env pull.

4. pull S3 credentials to environment

Input: Provisioned buckets on the branch. Steps:

• Run neon env pull to write the branch's S3 credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL_S3, AWS_REGION) into .env or .env.local.
• Or, without writing a file, inject at runtime via neon-env run -- <your dev command>.
• Verify the env vars are set: echo $AWS_ACCESS_KEY_ID.

Output: S3 credentials available in the environment.

5. install storage client libraries

Input: Project package.json. Steps:

• For Files SDK (recommended): npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner.
• For AWS S3 SDK only: npm install @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner.

Output: Dependencies installed; ready to import and use.

6a. implement upload/download with Files SDK (recommended path)

Input: Bucket name, file buffer/Blob/stream, optional bucket config. Steps:

• Import Files from files-sdk and the neon adapter.
• Instantiate a Files client with the neon adapter, passing only the bucket name (credentials and endpoint are read from AWS_* env vars).
• Call files.upload(key, body, options) to upload, files.download(key) to download, files.url(key, options) to generate presigned GET URLs, or other methods (list, exists, copy, delete, signedUploadUrl).
• Example:

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

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

await files.upload("generated/cat.jpg", fileBuffer, { contentType: "image/jpeg" });
const file = await files.download("generated/cat.jpg");
const url = await files.url("generated/cat.jpg", { expiresIn: 3600 });

Output: Files uploaded, downloaded, or presigned URLs generated.

6b. implement upload/download with AWS S3 client (alternative path)

Input: Bucket name, file buffer, S3 commands. Steps:

• Import S3Client from @aws-sdk/client-s3.
• Instantiate the client with forcePathStyle: true (required for Neon path-style addressing).
• Use command objects (PutObjectCommand, GetObjectCommand) with the client to upload, download, or manage objects.
• Use getSignedUrl from @aws-sdk/s3-request-presigner to generate presigned URLs.
• Example:

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

const s3 = new S3Client({ forcePathStyle: true });

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

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

const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: "images", Key: "generated/cat.jpg" }),
  { expiresIn: 3600 },
);

Output: Files uploaded, downloaded, or presigned URLs generated.

7. store object keys (not bytes) in the database

Input: Uploaded object key, Postgres connection. Steps:

• After upload succeeds, insert a row in Postgres with the object key (string, e.g., "generated/cat.jpg"), not the file bytes.
• On read, fetch the key from the row and generate a presigned URL via files.url() or getSignedUrl() to share without exposing credentials.
• This pattern keeps rows and files in sync because both live on the same branch.

Output: Row inserted with object key; presigned URL returned on read.

8. manage buckets and objects via CLI (optional)

Input: Bucket names, object keys. Steps:

• For scripting or one-off operations, use neon bucket create, neon bucket list, neon bucket delete.
• For objects, use neon bucket object put, neon bucket object get, neon bucket object list, neon bucket object delete.
• Example: neon bucket object put images generated/cat.jpg --file ./cat.jpg.

Output: Buckets and objects managed via CLI.

decision points

if the user's Neon project is existing or not in us-east-2, then stop setup. Neon Object Storage is available only on new projects in us-east-2. Advise the user to create a new project in that region or check the Neon changelog for expanded availability.

if the user wants a simple, unified storage API with minimal config, then use Files SDK with the neon adapter (step 6a). The adapter handles endpoint, region, and credential resolution from env vars automatically.

if the user already depends on the AWS SDK or prefers native S3 semantics, then use the AWS S3 client (step 6b). Remember to set forcePathStyle: true , Neon requires path-style addressing and will reject virtual-hosted-style requests.

if the user needs to share files without exposing S3 credentials, then generate presigned URLs via files.url() (Files SDK) or getSignedUrl() (AWS S3 client). Presigned URLs default to 1 hour expiry; customize via the expiresIn option (in seconds).

if the bucket is declared as public_read, then anonymous users can GET objects without a presigned URL, but PutObject and DeleteObject still require credentials. Private buckets require a credential for all operations.

if the user is deploying to a Neon Function, then do not call neon env pull in the function code. Credentials are injected automatically at runtime by the Neon platform.

if a presigned URL or S3 operation fails with a 403 Forbidden or credential error, then check that AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL_S3, and AWS_REGION are set and valid. Run neon env pull again to refresh them (credentials may have been rotated or the branch was created after a platform update).

if an S3 operation times out or returns a 503 Service Unavailable, then this is a transient network or Neon backend issue. Retry with exponential backoff (e.g., 100ms, 200ms, 400ms base with jitter). Do not assume the operation failed.

if the user wants to copy objects from parent to child on branch fork, then confirm that copy-on-write isolation works: child branch gets a read-only snapshot of parent objects at fork time. Writes on the child create new object versions that do not affect the parent.

if an neon checkout or neon deploy command is run but the bucket declarations in neon.ts were not applied, then this is expected. Checking out an existing branch does not reconcile its config. Run neon deploy or neon config apply to apply pending changes.

output contract

Success looks like:

• Bucket creation: neon config status shows the declared buckets under buckets: with their names, access modes, and creation timestamps.
• Env vars: echo $AWS_ACCESS_KEY_ID and other AWS_* vars are non-empty and present in the shell environment.
• Upload: files.upload() or s3.send(new PutObjectCommand(...)) completes without error and returns metadata (e.g., ETag, object size).
• Download: files.download() or s3.send(new GetObjectCommand(...)) returns a readable stream or buffer with the correct file content and MIME type.
• Presigned URL: files.url() or getSignedUrl() returns an HTTPS URL with a valid SigV4 signature, query params, and expiry timestamp. The URL can be shared and accessed without credentials.
• Database sync: A Postgres row contains the object key (string), and querying that key returns the presigned URL. No file bytes are stored in the database.
• Branch isolation: Forking a branch shows copy-on-write isolation: child branch inherits parent's buckets and objects at fork time; writes on the child do not affect the parent.

outcome signal

The user knows the skill worked when:

• They can run neon config status and see their declared buckets listed with metadata.
• They can upload a file (e.g., image, JSON, document) and see it appear in the bucket via neon bucket object list or the Files SDK files.list() method.
• They can download the file and verify its content matches the original.
• They can generate a presigned URL and share it (or curl it) without passing AWS credentials.
• They can insert a row in Postgres with the object key, then query the row and presign a URL for that object without round-tripping the file bytes through the database.
• They can fork a branch and see both the database rows and the objects replicate to the child branch with copy-on-write isolation.
• They can delete the child branch without affecting the parent's data or files.