첫 번째: Neon 개요, Neon 시작하기, Neon 개발 모범 사례 등은 상위 neon 스킬을 사용하세요.

neon 스킬이 설치되어 있지 않으면 https://neon.com/docs/ai/skills/neon/SKILL.md 에서 가져오거나 다음 명령어로 설치하세요:

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

Neon Object Storage

이는 공개 베타 기능이며, 현재 us-east-2 및 eu-central-1에서 사용 가능합니다.

Neon Object Storage는 프로젝트와 함께 브랜치되는 S3 호환 객체 스토리지입니다. 모든 브랜치는 자체 격리된 스토리지 상태를 가지므로, 파일과 데이터베이스 행이 개발, 프리뷰, 스테이징, 프로덕션 환경에서 동기화 상태를 유지합니다.

이 스킬을 사용하여 사용자가 데이터베이스와 함께 브랜치되는 파일을 저장하고 제공할 수 있도록 도와주세요. 작동하는 버킷과 업로드/다운로드 흐름, 주입된 환경 변수에 연결된 브랜치 인식 S3 클라이언트, 또는 공식 Neon 문서의 정확한 답변을 제공하세요.

사용 시기

Neon Object Storage는 앱과 사용자가 생성하는 파일(업로드, 첨부 파일, 아바타, 이미지, 문서, 생성된 자산, 백업)에 사용하세요. 앱이 이미 Neon을 사용 중이라면 기본 저장소로 사용하기에 적합합니다:

이미 Lakebase Postgres를 사용 중이며 두 번째 제공업체를 원하지 않습니다. 하나의 백엔드, 하나의 청구서, 하나의 CLI, 하나의 브랜치 세트 — 별도의 AWS S3 / R2 / Supabase Storage 계정을 설정하고 연결할 필요가 없습니다. 데이터베이스를 지원하는 동일한 Neon 자격 증명이 스토리지도 지원합니다.
파일은 데이터베이스와 환경 간에 동기화 상태를 유지해야 합니다. 스토리지는 Postgres 데이터와 함께 브랜치됩니다. 브랜치를 포크하면 하위 브랜치가 해당 시점의 상위 버킷과 객체를 즉시 상속받습니다(쓰기 시 복사, 데이터 중복 없음). 이는 에이전트, 개발, 프리뷰, 테스트 환경을 원활하게 만듭니다. 프리뷰 브랜치는 행과 참조하는 파일 모두의 일관된 스냅샷을 얻으며, 하위 브랜치의 쓰기는 상위 브랜치에 영향을 주지 않습니다.
안전하고 일회용 환경을 원합니다. 프리뷰/CI 브랜치에서 프로덕션 데이터에 대한 위험 없이 파일을 업로드, 덮어쓰기, 삭제한 다음 브랜치를 삭제할 수 있습니다.
표준 S3 도구를 원합니다. S3 의미 체계를 기반으로 구축되었으며 S3 API를 사용하므로 AWS SDK, boto3, AWS CLI, 사전 서명된 URL이 모두 작동합니다. 안정적이고 익숙하며 독점 클라이언트가 필요하지 않습니다.

파일이 앱 자체와 함께 제공되는 경우(HTML, JS 번들, CSS, public/ 디렉토리의 이미지) 정적 웹 호스팅에 해당하며 Vercel, Netlify 또는 Cloudflare에 속합니다. 버킷에서 제공되는 공개 자산은 앞에 CDN이 필요합니다(아키텍처: Object Storage의 위치 참조).

기능

S3 호환 — 기존 S3 SDK, boto3, AWS CLI, 사전 서명된 URL과 함께 작동합니다. 경로 스타일 주소 지정 및 SigV4만 지원합니다.
데이터베이스와 함께 브랜치 — 모든 Neon 브랜치는 자체 격리된 쓰기 시 복사 스토리지 상태를 얻습니다. 포크해도 데이터가 복사되지 않습니다.
두 가지 액세스 모드 — private 버킷은 모든 작업에 자격 증명이 필요합니다. public_read 버킷은 인증된 쓰기와 함께 익명 읽기를 허용합니다.
하나의 자격 증명 시스템 — Functions 및 AI Gateway에서 사용하는 동일한 Neon 자격 증명 시스템입니다.

가용성

무엇이든 설정하기 전에 이 전제 조건을 확인하세요: Neon Object Storage는 공개 베타 기능이며 현재 us-east-2 및 eu-central-1에서 사용 가능합니다. 사용자의 Neon 프로젝트가 이 리전 중 하나에 있는지 확인한 후 진행하세요.

아키텍처: Object Storage의 위치

Neon(Object Storage 포함)은 풀스택 앱 호스팅이 아닌 백엔드 프리미티브입니다. Object Storage는 앱과 사용자가 생성하는 파일(업로드, 첨부 파일, 아바타, 문서, 생성된 이미지, 백업)을 저장하며, 동일한 브랜치의 Postgres 행에서 키가 지정됩니다. 다음 두 가지 경계가 따릅니다:

공개 자산 앞에 CDN을 배치하세요. public_read 객체는 ${AWS_ENDPOINT_URL_S3}/<bucket>/<object-key>에서 익명으로 읽힙니다(브랜치의 스토리지 엔드포인트는 환경 변수로 주입됨, 환경 변수 참조). 브라우저가 페이지를 볼 때마다 로드하는 자산(아바타, 제품 이미지, 인기 있는 모든 것)의 경우 이를 Cloudflare 또는 Vercel CDN의 오리진으로 사용하고 PutObject에 Cache-Control을 설정하여 엣지가 각 객체를 얼마나 오래 보관할지 알 수 있도록 하세요. 캐시된 객체는 키만큼만 신선하므로 각 버전을 새 키(avatars/<user-id>/<uuid>.jpg)에 쓰고 Postgres에 저장된 키를 다시 가리키며, 하나의 키를 덮어쓰고 TTL이 만료될 때까지 기다리지 마세요. 엔드포인트는 브랜치 범위이므로 프로덕션 CDN은 프로덕션 브랜치를 가리키고 프리뷰 브랜치는 캐시를 공유하지 않고 자체 엔드포인트를 직접 읽습니다. 비공개 버킷은 대신 쿼리 문자열에 서명을 전달하는 사전 서명된 URL을 사용합니다.
앱 자체는 다른 곳에 호스팅하세요. 리포지토리에 체크인된 모든 것(HTML, JS 번들, CSS, public/에 제공되는 이미지 및 글꼴)은 인덱스 문서, SPA 폴백, 사용자 정의 도메인과 함께 Vercel, Netlify 또는 Cloudflare에 속합니다. Neon에는 이를 제공할 웹사이트 모드가 없습니다. PutBucketWebsite는 501 Not Implemented를 반환합니다.

설정

Object Storage는 neon.ts 인프라-코드 설정의 일부입니다(브랜치 우선 워크플로, link/checkout, neon.ts 기본 사항은 neon 스킬 참조). preview.buckets 아래에 버킷 이름을 키로 선언하세요:

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

export default defineConfig({
  preview: {
    buckets: {
      images: {}, // 기본적으로 비공개
      "public-assets": { access: "public_read" },
    },
  },
});

연결된 브랜치에 선언된 버킷을 프로비저닝하세요:

neon deploy   # `neon config apply`의 별칭

Neon Infrastructure as Code (`neon.ts`)

위의 preview.buckets 블록은 neon.ts의 일부입니다. 이 단일 TypeScript 파일은 브랜치가 가져야 할 다른 모든 서비스와 함께 버킷을 선언합니다(전체 참조는 neon 스킬 참조). Terraform 방식으로 브랜치에 대해 선언을 조정하세요:

neon config status   # 브랜치의 라이브 설정 출력(존재하는 버킷)
neon config plan     # apply가 변경할 사항의 dry-run diff
neon config apply    # 선언된 버킷 생성(neon deploy는 별칭)

버킷은 브랜치 범위입니다. neon.ts가 있으면 neon checkout이 브랜치를 생성할 때 정책을 적용하므로 새 프리뷰/CI 브랜치가 이미 프로비저닝된 버킷(및 상위에서 상속된 쓰기 시 복사 객체)과 함께 생성됩니다. 기존 브랜치를 체크아웃해도 조정되지 않습니다. 변경 사항을 적용하려면 neon deploy를 실행하세요. 프로비저닝(config apply/deploy), link, checkout은 또한 브랜치의 S3 자격 증명을 로컬 .env.local로 가져오므로 아래 표시된 env pull 단계가 해당 명령에서 자동으로 수행됩니다.

환경 변수

preview.buckets가 선언되면 Neon은 AWS 표준 S3 환경 변수를 주입하여 AWS SDK가 추가 구성 없이 환경에서 작동하도록 합니다. 배포된 Neon Function 내부에서는 자동으로 주입되며, 로컬에서는 CLI를 통해 디스크로 가져오거나(또는 런타임에 주입) 할 수 있습니다:

neon env pull            # 브랜치의 변수를 .env(또는 .env.local)에 씁니다
# 또는 파일을 쓰지 않고 런타임에 주입:
neon-env run -- <dev 명령어>

변수	의미
`AWS_ACCESS_KEY_ID`	S3 액세스 키 ID (브랜치 자격 증명의 토큰 ID)
`AWS_SECRET_ACCESS_KEY`	S3 시크릿 액세스 키
`AWS_ENDPOINT_URL_S3`	브랜치 S3 엔드포인트 URL
`AWS_REGION`	리전, 예: `us-east-2`

이름이 AWS 표준이므로 AWS SDK는 환경에서 자격 증명, 엔드포인트, 리전을 자동으로 읽습니다. 자격 증명은 브랜치 범위이며 해당 브랜치와 모든 하위 브랜치에 유효합니다.

process.env를 직접 읽는 대신 타입이 지정되고 검증된 액세스를 위해 동일한 neon.ts 설정 객체를 @neon/env의 parseEnv에 전달하세요. 이는 설정에서 파생된 env.storage 네임스페이스(accessKeyId, secretAccessKey, endpoint, region)를 반환합니다. neon 스킬을 참조하세요.

객체 작업: Files SDK (권장)

객체를 읽고 쓰는 가장 간단하고 이식성 있는 방법은 Files SDK와 neon 어댑터를 사용하는 것입니다. 이는 웹 표준 I/O를 통한 작고 통일된 스토리지 API(upload, download, url, list, exists, copy, delete, signedUploadUrl)입니다. 내부적으로 Neon에 맞게 구성된 AWS S3 클라이언트를 사용하며 오류를 Neon error로 다시 레이블링하므로 잘못 구성할 것이 없습니다. 먼저 이 방법을 사용하세요.

어댑터가 내부적으로 사용하는 AWS S3 피어 종속성과 함께 설치하세요:

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

어댑터는 동일한 주입된 AWS_* 환경 변수에서 엔드포인트, 리전, 자격 증명을 확인합니다. 버킷 이름만 전달하세요:

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

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

// 업로드 — body는 Buffer, Uint8Array, Blob, File, ReadableStream 또는 문자열일 수 있습니다
await files.upload("generated/cat.jpg", fileBuffer, { contentType: "image/jpeg" });

// 다운로드
const file = await files.download("generated/cat.jpg");
const bytes = new Uint8Array(await file.arrayBuffer());

// 사전 서명된 GET — 자격 증명 노출 없이 공유(기본 1시간 만료)
const url = await files.url("generated/cat.jpg", { expiresIn: 3600 });

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

어댑터 임포트(files-sdk/s3, files-sdk/r2, files-sdk/gcs, …)를 바꾸면 나머지 코드는 변경되지 않습니다.

객체 작업: AWS S3 클라이언트 (대안)

Neon은 S3 API를 직접 사용하므로 네이티브 클라이언트를 선호하거나 이미 의존하는 경우 AWS SDK로 내려갈 수 있습니다. 자격 증명, 엔드포인트, 리전은 표준 AWS 환경 체인에서 읽히므로 전달하는 유일한 설정은 forcePathStyle: true입니다. Neon은 경로 스타일 주소 지정을 요구하므로 S3 클라이언트는 반드시 이를 설정해야 합니다:

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

const s3 = new S3Client({
  forcePathStyle: true, // 필수: Neon은 경로 스타일 주소 지정 사용
});

그런 다음 원시 명령 객체로 업로드, 다운로드, 사전 서명:

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

const BUCKET = "images";

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

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

// 사전 서명된 GET — 자격 증명 노출 없이 공유
const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
  { expiresIn: 3600 },
);

브랜치에서 스토리지와 데이터베이스 페어링

표준 패턴: 에이전트가 이미지 생성 → PutObject로 images 버킷에 저장 → Postgres에 행 삽입 → 읽을 때 사전 서명된 URL 반환. Postgres 열에 버킷 키(바이트가 아님)를 저장하고 읽을 때 사전 서명하세요. 행과 객체가 동일한 브랜치에 있으므로 함께 브랜치되고 드리프트되지 않습니다.

CLI 버킷 및 객체 명령

내장 브랜치 로그

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

스토리지는 오늘날 브랜치 로그가 다루는 두 가지 소스 중 하나이며(Neon Functions와 함께). 로그는 단일 브랜치 범위이므로 디버깅 중인 버킷이 체크아웃된 브랜치가 아닌 경우 --branch를 전달하세요. 로그에 대한 다른 모든 것(필요한 CLI 버전, 필터, SDK, Loki 호환 읽기 API)은 상위 neon 스킬의 관찰 가능성 섹션에 있습니다.

Neon 문서

Neon 문서는 공식 정보이며 Object Storage는 빠르게 진화하고 있으므로 항상 공식 문서와 확인하세요. 모든 문서 페이지는 URL에 .md를 추가하거나 Accept: text/markdown을 요청하여 마크다운으로 가져올 수 있습니다. 문서 인덱스(https://neon.com/docs/llms.txt) 및 변경 로그 공지에서 올바른 페이지를 찾으세요.

neondatabase/neon-object-storage

neon-object-storage란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서