가장 먼저: 부모 neon 스킬을 사용하여 Neon 개요, 시작하기, 개발 모범 사례 등을 확인하세요.
neon 스킬이 설치되지 않은 경우 https://neon.com/docs/ai/skills/neon/SKILL.md 에서 가져오거나 다음 명령어로 설치할 수 있습니다:
npx skills add neondatabase/agent-skills --skill neon
Lakebase Postgres 브랜칭
결과: 생성된 Neon 브랜치 — 또는 생성을 진행할 수 없는 경우 명확하고 실행 가능한 다음 단계를 제시합니다. 올바른 브랜치 유형을 선택한 다음 CLI(또는 CLI를 사용할 수 없는 경우 MCP)를 사용하여 브랜치 생성을 실행합니다.
- 일반 브랜치: 실제 데이터로 현실적인 마이그레이션 및 쿼리 테스트를 수행합니다.
- 스키마 전용 브랜치 (Beta): 데이터 행은 복사하지 않고 구조만 필요한 민감한 데이터 워크플로우에 사용합니다.
브랜치 유형 결정
다음 결정 규칙을 먼저 사용합니다:
- 사용자가 프로덕션과 유사한 데이터로 복잡한 마이그레이션, 성능 또는 동작을 테스트하려는 경우 일반 브랜치를 선택합니다.
- 사용자가 민감한 데이터 복사를 피해야 하는 경우 스키마 전용 브랜치를 선택합니다.
요청이 모호한 경우 다음 질문 중 하나를 명확히 합니다: "테스트를 위해 실제 데이터가 필요합니까, 아니면 데이터가 민감하여 스키마 구조만 필요합니까?"
도구 선택: CLI 또는 MCP
Neon CLI와 Neon MCP 서버를 모두 지원하지만 기본적으로 CLI를 사용합니다. CLI를 사용할 수 없거나 환경에서 차단되었거나 인증할 수 없거나 사용자가 명시적으로 MCP를 요청하는 경우에만 MCP를 사용합니다.
선택 순서
- 먼저 CLI를 확인합니다:
neon --version을 실행하여 CLI가 설치되었는지 확인합니다.neon projects list를 실행하여 인증/컨텍스트를 확인합니다.
- CLI가 없는 경우 퀵스타트를 통해 설치를 안내합니다.
- CLI가 설치되었지만 인증되지 않은 경우
neon auth(또는 API 키 인증)를 통해 사용자를 안내한 후 계속 진행합니다. - CLI를 사용할 수 없는 경우 MCP로 전환합니다 — 환경에서 CLI에 접근할 수 없거나, 실행이 차단되었거나, 인증이 불가능한 경우 — 또는 사용자가 명시적으로 MCP를 요청하는 경우. Neon MCP 도구를 사용할 수 있고 인증되었는지 확인한 다음(예: 프로젝트 목록이 작동하는지 확인) 아래 MCP 브랜치 흐름을 따릅니다.
- 두 경로 모두 실패하면 Neon REST API를 사용합니다:
MCP 브랜치 흐름
- 데이터 민감도와 마이그레이션 테스트 목표에 따라 일반 브랜치와 스키마 전용 브랜치를 선택합니다.
- 브랜치 도구(예:
create_branch)를 사용하여 브랜치를 생성합니다. - 읽기 도구(예:
describe_branch)로 유효성을 검증합니다. - 마이그레이션 워크플로우의 경우 메인에 적용하기 전에 브랜치 기반 마이그레이션 흐름을 선호합니다.
일반 브랜치 생성 (실제 데이터 마이그레이션 테스트에 권장)
사용자에게 현실적인 테스트 조건이 필요할 때 사용합니다. 실제 프로덕션과 유사한 데이터는 시드 또는 데이터 마이그레이션 스크립트가 놓칠 수 있는 예외 상황을 드러낼 수 있으므로, 라이브 전환 전에 마이그레이션 문제를 발견하는 데 도움이 됩니다.
링크: https://neon.com/docs/introduction/branching.md
단계
-
먼저 도구 경로를 결정합니다(선택 순서 참조):
neon --version으로 CLI를 확인하고, CLI를 사용할 수 없는 경우에만 MCP로 대체합니다. -
프로젝트 컨텍스트가 설정되었는지 확인합니다(
neon set-context --project-id <your-project-id>또는 명령어에--project-id를 포함합니다). -
브랜치를 생성합니다:
neon branches create \ --name <branch-name> \ --parent <parent-branch-id-or-name> \ --expires-at 2026-12-15T18:02:16Z -
선택적으로 새 브랜치의 연결 문자열을 가져옵니다:
neon connection-string <branch-name>
스키마 전용 브랜치 생성 (Beta, 민감한 데이터)
사용자가 프로덕션 행을 테스트 브랜치로 복사하지 않아야 하는 경우 사용합니다.
링크: https://neon.com/docs/guides/branching-schema-only.md
단계
-
먼저 도구 경로를 결정합니다(선택 순서 참조):
neon --version으로 CLI를 확인하고, CLI를 사용할 수 없는 경우에만 MCP로 대체합니다. -
스키마 전용 브랜치를 생성합니다:
neon branches create \ --name <schema-only-branch-name> \ --parent <parent-branch-id-or-name> \ --schema-only \ --expires-at 2026-12-15T18:02:16Z여러 프로젝트가 있는 경우
--project-id를 포함합니다:neon branches create \ --name <schema-only-branch-name> \ --parent <parent-branch-id-or-name> \ --schema-only \ --project-id <your-project-id> \ --expires-at 2026-12-15T18:02:16Z
Beta 지원 안내 (필수)
스키마 전용 브랜칭은 Beta 상태입니다. 사용자가 예상치 못한 동작, 오류 또는 누락된 기능을 보고하는 경우:
- Neon Console에서 피드백을 공유하도록 요청합니다:
- Neon Discord에서 지원 대화를 열도록 권장합니다:
부모 브랜치에서 재설정
자식 브랜치가 변경되어 사용자가 부모 브랜치의 최신 스키마와 데이터로 깨끗하게 새로 고침을 원할 때 사용합니다.
링크: https://neon.com/docs/guides/reset-from-parent.md
기능 설명
- 자식 브랜치의 스키마와 데이터를 부모의 최신 상태로 완전히 대체합니다.
- 병합하지 않으며, 자식 브랜치의 로컬 변경 사항은 손실됩니다.
- 동일한 연결 세부 정보를 유지하지만, 재설정 중에 활성 연결이 잠시 중단됩니다.
권장 시기
- 개발 또는 스테이징 브랜치가 프로덕션보다 너무 뒤처져 있는 경우.
- 사용자가 깨끗한 부모 정렬 상태에서 새 기능을 시작하려는 경우.
- 팀이 일관된 테스트 기준을 위해 스테이징을 프로덕션에서 새로 고치려는 경우.
제약 조건 및 차단 요소
- 자식 브랜치만 재설정할 수 있습니다(루트 브랜치와 스키마 전용 루트 브랜치는 부모에서 재설정할 수 없음).
- 대상 브랜치에 자식이 있는 경우 해당 자식 브랜치가 제거될 때까지 재설정이 차단됩니다.
- 부모 브랜치가 스냅샷에서 복원된 후 최대 24시간 동안 부모에서 재설정을 사용하지 못할 수 있습니다.
- 부모에서 재설정은 항상 현재 부모 상태를 사용합니다. 특정 시점 복구가 필요한 경우 Instant restore를 사용하세요.
CLI 사용법
neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name>
프로젝트 컨텍스트가 아직 설정되지 않은 경우 프로젝트 ID를 포함합니다:
neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name> --project-id <project-id>
--preserve-under-name은 재설정 전 상태를 롤백용 백업 브랜치로 유지하지만, 나중에 정리해야 할 추가 브랜치가 하나 더 생깁니다.
--project-id를 반복하지 않도록 컨텍스트를 선택적으로 설정합니다:
neon set-context --project-id <project-id>
Console 및 API 사용법
- Console: 대상 자식 브랜치를 열고 Actions에서 부모에서 재설정(Reset from parent) 을 선택합니다.
- API: 브랜치의 복원 엔드포인트를 사용하고
source_branch_id를 부모 브랜치 ID로 설정합니다.
참고 사항 및 주의 사항
- 스키마 전용 브랜치는 구조 전용 복제 및 민감/규정 준수 데이터 제어를 위한 것입니다.
- 스키마 전용 브랜치는 독립적인 루트 브랜치이므로(부모 브랜치 및 공유 기록 없음) 부모에서 재설정이 적용되지 않습니다.
- 실제 행 모양, 볼륨 및 예외 상황에 의존하는 마이그레이션 테스트의 경우 일반 브랜치를 선호합니다.
- 루트 브랜치 허용 한도와 브랜치별 스토리지 제한으로 인해 사용자가 생성할 수 있는 스키마 전용 브랜치 수가 제한될 수 있습니다.
- 사용자가 확실하지 않은 경우 기본 권장 사항은 다음과 같습니다:
- 일반 브랜치: 마이그레이션 검증용.
- 스키마 전용 브랜치: 규정 준수 및 개인정보 보호 제약 조건용.
유용한 워크플로우 패턴
사용자가 단일 명령어가 아닌 프로세스 권장 사항을 요청하는 경우 다음을 제안합니다:
- PR당 하나의 브랜치: PR이 열릴 때 브랜치를 생성하고, 병합/종료될 때 삭제하여 마이그레이션 테스트를 격리합니다.
- 테스트 실행당 하나의 브랜치: 파이프라인 시작 시 브랜치를 만들고, 마이그레이션/테스트를 실행한 다음, 종료 시 삭제하여 결정론적 CI를 유지합니다.
- 개발자당 하나의 브랜치: 프로덕션과 유사한 형태의 격리된 개발 환경을 제공하고, 공유 테스트 데이터에서 팀 간 충돌을 방지합니다.
- PII 인식 브랜칭: 프로덕션에 민감한 데이터가 있는 경우 익명화된 브랜치에서 개발/PR 브랜치를 파생하거나 스키마 전용 브랜치를 사용합니다.
- 임시 수명 주기 관리: 브랜치 만료를 설정하고 정리를 자동화하여 오래된 브랜치가 불필요한 스토리지/기록 비용을 축적하지 않도록 합니다.
생성 후 환경 업데이트 프롬프트
브랜치 생성 후 사용자에게 새 브랜치를 가리키도록 로컬 환경 자격 증명을 업데이트할지 물어봅니다.
- 질문: "
.env의DATABASE_URL을 이 새 브랜치 연결 문자열로 업데이트할까요?" - 예: 요청된 env 파일/키에 새 브랜치 연결 문자열을 작성합니다.
- 아니요: 자격 증명을 변경하지 않고 수동 사용을 위해 연결 문자열을 공유합니다.
- 명시적 확인 없이 기존 env 키를 덮어쓰지 마십시오.
Neon Infrastructure as Code (neon.ts)
명령형으로(위의 CLI / MCP / API) 브랜치를 생성하는 것 외에도 neon.ts에서 새 브랜치가 받을 구성을 선언적으로 프로그래밍할 수 있습니다. 이는 Neon의 인프라스트럭처 코드 파일입니다(전체 참조는 neon 스킬 참조). branch 속성은 평가 중인 브랜치의 함수로 설정을 반환하므로, 프로젝트에서 생성된 모든 브랜치가 브랜치별 플래그 없이 일관된 수명 주기와 컴퓨팅 프로필을 갖게 됩니다.
npm i @neon/config
// neon.ts
import { defineConfig } from "@neon/config/v1";
export default defineConfig({
branch: (branch) => {
if (branch.exists) return {}; // 기존 브랜치는 조정하지 않음
if (branch.isDefault) return { protected: true };
if (branch.name.startsWith("preview/") || branch.name.startsWith("dev")) {
return {
parent: "main",
ttl: "7d", // 임시: 생성 후 7일 후 자동 만료 (최대 30일)
postgres: {
computeSettings: {
autoscalingLimitMinCu: 0.25, // 0으로 스케일 다운
autoscalingLimitMaxCu: 1, // 테스트용 브랜치를 저렴하게 유지
suspendTimeout: "5m",
},
},
};
}
return {};
},
});
클로저는 대상 브랜치의 읽기 전용 설명자(name, exists, isDefault, parentId 등)를 받고 적용할 튜닝(parent, ttl(자동 만료), protected, postgres.computeSettings)을 반환합니다. 이는 위의 임시 수명 주기 관리 및 PR별/테스트별 패턴에 대한 선언적 보완책입니다: 매번 neon branches create에 --expires-at을 기억하는 대신 TTL 및 컴퓨팅 프로필이 버전 제어에 저장되고 일치하는 모든 브랜치에 적용됩니다.
neon checkout은 브랜치를 생성할 때 이 정책을 적용하므로, 새 preview/* 또는 dev-* 브랜치는 이미 만료되고 0으로 스케일 다운된 상태로 나타납니다. 기존 브랜치를 체크아웃해도 조정되지 않습니다. 이미 존재하는 브랜치에 변경 사항을 적용하려면 neon deploy(neon config apply의 별칭)를 실행하세요.
CI/CD에서의 브랜칭
Neon 브랜치의 일반적인 CI/CD 사용 사례:
- PR별 미리보기 배포: PR이 열리면 브랜치를 만들고, 이에 대한 미리보기를 배포한 다음, 닫힐 때 삭제합니다. 각 PR은 격리된 데이터베이스 브랜치를 얻습니다. 브랜치의
DATABASE_URL을 배포된 앱에 주입하는 것은 호스팅 공급자에 따라 다릅니다. 테스트된 패턴은 preview-branches-with-cloudflare, preview-branches-with-vercel 또는 preview-branches-with-fly를 참조하세요. - CI에서 마이그레이션 테스트: 위험한 스키마 변경을 병합 전에 프로덕션과 유사한 데이터가 있는 브랜치에 대해 실행합니다.
- 스키마 차이 가시성: schema-diff GitHub Action을 사용하여 PR에 DB 계층 차이를 자동으로 주석 처리합니다.
예제
예제 1: 실제 데이터로 마이그레이션 테스트
사용자 입력: "위험한 마이그레이션을 프로덕션과 유사한 데이터로 테스트해야 합니다."
Agent 출력 형태:
- 일반 브랜치를 권장하고 이유를 설명합니다.
- 문서 링크 공유: https://neon.com/docs/introduction/branching
- 먼저 도구 경로를 확인합니다(
neon --version으로 CLI; CLI를 사용할 수 없는 경우에만 MCP). - 명령어 제공:
neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Zneon connection-string migration-test
예제 2: 민감한 데이터 개발 워크플로우
사용자 입력: "규정 준수 때문에 프로덕션 데이터를 복사할 수 없습니다."
Agent 출력 형태:
- 스키마 전용 브랜치를 권장하고 이유를 설명합니다.
- 문서 링크 공유: https://neon.com/docs/guides/branching-schema-only
- 먼저 도구 경로를 확인합니다(
neon --version으로 CLI; CLI를 사용할 수 없는 경우에만 MCP). - 명령어 제공:
neon branches create --name compliance-dev --parent main --schema-only --project-id <your-project-id> --expires-at 2026-12-15T18:02:16Z
- Beta 지원 경로 언급: