Communitygithub.com

Adrian7373/semantic-video-pipeline

Prisma Composer 앱(서비스, 모듈)을 배포 또는 관리할 때 사용합니다. 로컬 실행, 구성된 서비스 테스트, 환경 설정/해체를 지원합니다.

semantic-video-pipeline란 무엇인가요?

이 스킬은 Prisma Composer(@prisma/composer)를 기반으로 구축된 애플리케이션을 배포, 관리 및 로컬 개발하는 방법을 설명합니다. 서비스(compute()), 리소스(rawPostgres(), bucket()), 모듈(module()) 등 노드 유형을 통해 애플리케이션을 선언적으로 구성하며, 타입이 지정된 포트를 통해 연결됩니다. `prisma deploy`와 `prisma dev` 명령어를 사용하며, 환경 해체와 로그는 @prisma/composer/control 패키지의 destroy 및 log 작업을 통해 스크립트로 처리합니다. 이 스킬은 Prisma Cloud 배포 대상을 가정하며, `prisma.config.ts` 파일에서 composer 설정을 지정하고, 데이터베이스 마이그레이션은 `contract.prisma` 파일을 통해 관리합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Adrian7373/semantic-video-pipeline/tree/HEAD/packages/database/.agents/skills/prisma-composer-core-concepts

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

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Prisma Composer 핵심 개념

Prisma App은 TypeScript로 작성된 타입 선언의 트리이며, prisma CLI에 전달됩니다. CLI에는 prisma deploy와 prisma dev라는 두 가지 Composer 명령이 있습니다. 환경 해체와 로그는 명령어가 아니라 @prisma/composer/control의 destroy 및 log 작업이며, 스크립트에서 호출됩니다. 이 파일은 구조, 계층, 관계 및 워크플로우를 다룹니다: 코드나 CLI의 도움말 출력에서 관찰할 수 없는 개념들입니다. CLI 참조가 아닙니다. 각 명령의 플래그는 추론하지 말고 prisma <command> --help를 통해 확인하세요. Prisma 플랫폼은 빠르게 변화하므로, 이 파일을 안정적인 개념적 핵심으로 취급하고 최신의 전체 문서는 https://www.prisma.io/docs에서 확인하세요. 작동하는 코드는 prisma/composer 저장소의 examples/를 참조하세요.

두 가지 원칙이 모든 것을 지배하며 필수입니다 (docs/design/01-principles/):

  1. 코드는 환경을 절대 읽지 않습니다. 종속성, 구성, 자격 증명, 포트는 모두 서비스 노드를 통해 타입이 지정되어 전달됩니다. process.env는 해결책이 아닙니다.
  2. Composer는 코드를 번들링하거나 변환하지 않습니다. 자신의 번들러로 빌드합니다. 프레임워크는 결정적 단계를 통해 빌드된 출력을 조립하여 구성된 배포 대상에 전달합니다.

선언은 데이터입니다

작성하는 모든 것은 선언입니다: 애플리케이션의 일부를 설명하는 일반 데이터이며, 가져올 때 아무것도 실행하지 않습니다. 세 가지 노드 종류가 있습니다:

종류선언 방법목적
서비스compute()코드의 실행 단위; 원자적이며, Composer는 포트만 봅니다
리소스rawPostgres(), bucket()상태를 가진 관리형 종속성
모듈module()그룹화 경계; 자체 코드를 실행하지 않으며, 타입이 지정된 포트를 노출합니다

노드는 포트를 통해 연결됩니다: deps는 노드가 필요로 하는 것을 선언하고, expose는 제공하는 것을 선언합니다. 연결은 Module의 빌더 내에서 provision()을 통해 이루어지며, CLI에 전달되는 루트 Module이 App입니다:

// module.ts
import { module } from '@prisma/composer';

export default module('store', ({ provision }) => {
  const catalog = provision(catalogModule);
  provision(storefrontService, { deps: { catalog: catalog.rpc } });
});

포트는 타입이 지정되어 있으므로 컴파일러가 모든 연결을 검증합니다. 잘못된 생산자에 연결된 종속성, 누락된 RPC 핸들러, 잘못된 형태의 리터럴 입력 값: 이 모든 것은 배포가 아닌 tsc에서 실패합니다. 환경 바인딩 입력이 예외입니다: 해당 값은 배포 시에만 존재하므로, 시크릿 바인딩 불일치 및 누락된 플랫폼 변수는 대신 초기 배포 시간 거부로 표면화됩니다 (아래 두 채널 참조). 타입 검사, 빌드, 배포 순서로 진행하세요. 연결이 올바른지 확인하기 위해 클라우드를 사용하지 마세요.

Composer 자체는 대상에 독립적입니다: @prisma/composer는 작성, 테스트 및 CLI를 포함하며, 어떤 플랫폼에도 결합되지 않습니다. 배포 대상은 배포 구성에 등록된 확장입니다. @prisma/composer-prisma-cloud는 Prisma Cloud 대상이며, 이 스킬의 배포 섹션에서 가정하는 대상입니다. 루트 내보내기는 compute, rawPostgres, bucket, envSecret, envParam입니다. ORM 어휘 (postgres, dataContract)는 /orm 하위 경로에 있으며, 공유 /cron, /storage, /streams, /auth, /email 모듈과 함께 있습니다. 기본 Prisma Cloud 앱에 필요한 유일한 두 Composer 패키지이며, 아무것도 자동으로 설치하지 않습니다: 새 프로젝트는 둘 다 없이 시작하므로, 먼저 두 패키지를 종속성으로 추가하세요. 확장은 이들과 함께 자체 prisma-composer-* 패키지를 추가합니다. 직접 기능을 구현하기 전에 기존 Module을 구성하세요. 하나를 연결하는 것은 몇 줄이면 됩니다.

진입 그래프 내에서 (module.ts에서 도달 가능한 모든 것), 명시적인 .ts 확장자를 가진 상대 경로 가져오기를 사용하세요 (./service.ts, tsconfig에 allowImportingTsExtensions 설정): 이 형식은 모든 곳에서 확인됩니다. prisma deploy와 prisma dev는 또한 ./service.js와 확장자 없는 ./service를 .ts 소스에 매핑하지만, 다른 도구는 그렇지 않을 수 있습니다.

서비스 노드가 유일한 통로입니다

런타임 코드는 가져오는 서비스 선언으로부터 모든 것을 받습니다:

  1. service.load(): 종속성 (타입이 지정된 RPC 클라이언트, 데이터베이스 바인딩).
  2. service.input(): 하나의 스키마 유효성 검사 객체로 전체 입력; 자격 증명은 SecretString 상자로 숨겨집니다.
  3. service.port(): 바인딩할 예약된 포트 (기본값 3000).

서비스 선언은 순수 데이터입니다. 서버 진입점은 빌드가 생성하고 플랫폼이 부팅하는 것입니다:

// service.ts
export default compute({
  name: 'auth',
  deps: { db: rawPostgres() },
  build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
  expose: { rpc: authContract },
});

// server.ts
const { db } = service.load(); // { url }: 직접 클라이언트를 구성합니다
const handler = serve(service, {
  rpc: { verify: async ({ token }) => ({ ok: token.length > 0 }) },
});
Bun.serve({ port: service.port(), hostname: '0.0.0.0', fetch: handler });

소비자는 deps: { auth: rpc(authContract) }를 선언하고 load()에서 타입이 지정된 클라이언트를 받습니다.

두 채널: 종속성과 입력

값이...선언제공읽기
다른 노드에 의해 생성됨deps: { db: rawPostgres() }provision()에서 연결load()
다른 모든 것 (구성 또는 자격 증명)input 스키마의 한 필드provision()에서 바인딩: 리터럴, envParam(), 또는 envSecret()input()

서비스는 전체 들어오는 구성을, 일반 값과 자격 증명을 함께, 하나의 표준 스키마로 선언합니다. 자격 증명은 @prisma/composer/arktype의 secretString()으로 타입이 지정된 필드입니다. 조건부 법적성 ("청구가 켜져 있지 않으면 Stripe 키 없음")은 일반 스키마 유니온입니다. provision()에서의 바인딩은 스키마의 형태를 반영합니다. envSecret('NAME')은 플랫폼 변수를 이름 지으며 값을 전달하지 않습니다.

문제가 되는 규칙:

  1. 비밀성은 검증을 통해 강제됩니다. 스키마가 SecretString을 예상하는 곳에 리터럴이 바인딩되면 배포가 실패합니다. envSecret이 일반 문자열 필드에 바인딩되어도 동일하게 실패합니다.
  2. envParam 값은 원시 문자열로 도착합니다. 문자열 필드에 바인딩하세요. 스테이지의 플랫폼 변수가 저장소입니다. 배포 셸은 누락된 이름만 시드합니다 (둘 다 없으면 변수 이름을 지정하여 배포가 조기에 실패합니다). 플랫폼 값을 변경하려면 재배포가 필요합니다.
  3. 부재는 스키마의 결정에 달려 있습니다. 설정되지 않았거나 비어 있는 변수에 바인딩된 환경 변수 필드는 키 생략으로 확인되며, 이는 스키마가 허용하는 경우에만 합법적입니다 (선택적 필드, 유니온 분기). 배포 보고서는 직렬화된 입력 문서를 출력하고 (시크릿은 {"$secret":"VAR"} 포인터로 표시) 부재로 확인된 모든 키를 표시합니다.
  4. 예약된 port는 스키마 외부에 있습니다. service.port()를 통해 읽고, process.env를 사용하지 마세요. 프레임워크는 또한 Next.js 독립형을 위해 PORT를 내보내며, Next.js가 자체적으로 바인딩합니다.
  5. Module은 플랫폼 이름을 배우지 않고 시크릿 필요성을 전달합니다. Module 경계에 secrets: { signingKey: secret() }을 선언하고 전달된 참조를 바인딩 리프로 전달합니다. 부모가 실제 소스를 바인딩합니다.
  6. input.apiKey.expose()는 시크릿 값에 접근하는 유일한 방법입니다. 상자는 다른 모든 곳에서 (로그, JSON, 오류) 숨깁니다.

계약 및 RPC

계약은 서비스가 통신하는 타입이 지정된 인터페이스입니다. 소유한 서비스와 함께 존재하며, 표준 스키마 유효성 검사기로 타입이 지정됩니다. 제공자 (serve(), 컴파일 시 계약의 모든 메서드를 포함)와 소비자 (rpc(contract)) 모두 동일한 값을 참조합니다. 호출은 HTTP를 통해 RPC로 전달됩니다. 두 가지 동작이 자동으로 제공되며 다시 구현해서는 안 됩니다:

  1. 서비스 키. 배포 시 Composer는 소비자->제공자 바인딩별로 고유하고 추측할 수 없는 키를 생성합니다. serve()는 핸들러가 실행되기 전에 이외의 요청에 401을 반환합니다. 코드에서 이를 선언하지 않습니다. 결과: 자체 서비스 간 인증을 구축하지 말고, 배포된 /rpc/<method>를 curl로 확인하지 마세요. 연결되지 않은 호출자는 항상 401을 받으며, 이는 잘못된 배포처럼 보이지만 그렇지 않습니다. 소비자를 통해 디버깅하거나, 아무것도 강제되지 않는 로컬에서 디버깅하세요. 키는 바인딩별로 (하나가 유출되어 다른 소비자를 가장할 수 없음), 서비스 범위로 (유효한 키는 모든 메서드에 도달; 서비스를 분할하여 별도로 게이트), 바인딩을 제거하거나 스택을 파괴하고 재배포하여 회전하며, 수동 편집하지 않는 배포 소유 COMPOSER_* 변수에 저장됩니다.
  2. 멱등성 및 재시도. 모든 생성된 클라이언트 호출은 Idempotency-Key를 전달합니다. 드롭된 호출은 백오프로 재시도되며, serve()는 키당 한 번 호출을 실행하고, 늦은 재시도에는 완료된 답변을 재생합니다. 따라서 모든 메서드는 안전하게 재시도 가능하며 어떤 계약도 이에 대해 선언하지 않습니다 ("이것이 멱등성인가" 플래그는 없습니다. 만들지 마세요). 핸들러는 선택적 세 번째 인수 (input, deps, ctx)를 취하고 ctx.idempotencyKey (string | undefined)를 읽을 수 있으며, 이는 하나의 인스턴스 메모리를 넘어 정확히 한 번의 실행이 필요한 경우에 유용합니다. 대부분은 필요하지 않습니다. 로컬 및 테스트에서는 아무것도 프로비저닝되지 않으므로, serve()는 모든 호출을 통과시킵니다. 테스트 입력에 키를 제공하지 마세요.

빌드는 직접 합니다

빌드는 직접 하고, 프레임워크가 조립합니다. 일반 서버 프로세스의 경우 entry는 단일 자체 포함 ESM 파일을 가리켜야 합니다: 런타임 내장 (bun, bun:*, node:*)을 제외한 모든 것이 인라인됩니다. 배포는 해당 파일 하나를 복사하며 node_modules를 절대 전송하지 않으므로, 인라인되지 않은 것은 배포 시가 아닌 부팅 시 실패합니다. 문제가 되는 규칙:

  1. 하나의 패키지에 두 개의 서비스는 두 개의 별도 빌드를 의미합니다. 각 진입점당 하나씩입니다. 단일 다중 진입점 빌드는 공유 코드를 청크로 분할하지만, 어느 출력에도 포함되지 않습니다.
  2. 디렉토리 빌드는 dir + entry를 사용합니다. (dir은 서비스 모듈에 상대적, entry는 dir 내부의 파일; ../는 오류입니다). 트리는 그대로 복사되므로, 서버는 작업 디렉토리가 아닌 import.meta.url에 대해 형제를 확인해야 합니다. 트리에는 심볼릭 링크가 없어야 합니다: 패키저가 이를 거부하고 링크를 지정하며 조립이 실패합니다.
  3. Next.js: output: 'standalone'을 사용한 next build가 전체 빌드입니다. nextjs({ module, appDir })는 앱 루트를 지정합니다. load()를 호출하는 페이지나 작업은 export const dynamic = 'force-dynamic'이 필요합니다. 런타임 환경이 빌드 시 존재하지 않고 Next가 사전 렌더링된 라우트에 대해 런타임 env를 무시하기 때문입니다.
  4. deploy 또는 dev 전에 항상 빌드하세요. 어느 것도 자동으로 빌드하지 않습니다.

배포 구성은 prisma.config.ts의 composer 섹션이며, 다른 것은 없습니다. 확장 (prismaCloud(), nodeBuild(), 앱에 Next.js 서비스가 있는 경우 nextjsBuild())과 배포 상태 백엔드 (prismaState())를 등록합니다:

// prisma.config.ts
import { defineConfig as composer } from '@prisma/composer/config';
import { nodeBuild } from '@prisma/composer/node/control';
import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';
import { definePrismaConfig } from 'prisma/config';

export default definePrismaConfig({
  composer: composer({ extensions: [prismaCloud(), nodeBuild()], state: prismaState() }),
});

명령은 실행되는 디렉토리에서 prisma.config.ts를 찾아 저장소 루트까지 올라갑니다. composer를 선언하는 가장 가까운 파일이 우선하며, 해당 섹션 전체가 사용되고 키별로 병합되지 않습니다. extensions와 state만 허용됩니다. 다른 키는 오류입니다. 앱 코드는 파일을 가져오지 않습니다.

별도의 prisma-composer.config.ts는 더 이상 읽히지 않으며, 이전 설정은 조용히 무시되지 않고 거부됩니다: 로드된 prisma.config.ts가 composer 섹션을 선언하지 않으면 CONFIG.SECTION_MISSING, 섹션에 여전히 configPath가 있으면 CONFIG.FIELD_RETIRED, prisma-composer.config.*가 선언하는 prisma.config.ts 옆에 있으면 CONFIG.FILE_RETIRED. 모두 CLI의 CLI.CONFIG_SECTION_INVALID 아래에 있습니다. 세 가지 모두에 대한 해결책은 이전 파일의 extensions와 state를 섹션으로 이동하고 이전 파일을 삭제하는 것입니다. @prisma/composer-cli/family는 더 이상 ComposerSection을 내보내지 않습니다. 섹션의 타입은 @prisma/composer/config의 PrismaAppConfig입니다.

데이터베이스 및 마이그레이션

두 종류의 Postgres 종속성:

  1. rawPostgres(): 바인딩은 { url }이며 앱이 자체 클라이언트를 소유합니다.
  2. postgres(...): Prisma-ORM-타입 데이터베이스입니다. 바인딩은 { url, client }입니다. 원시 연결 URL과 데이터 계약에서 Composer가 지연 생성하는 타입 클라이언트입니다. 따라서 쿼리는 binding.client를 통해 이루어지며 컴파일 시 확인됩니다. postgres와 dataContract 모두 @prisma/composer-prisma-cloud/orm에서 가져옵니다. 패키지 루트가 아닙니다. 하나의 dataContract로 래핑된 값은 종속성 끝 (deps: { db: postgres(catalogData) })과 리소스 끝 모두에서 참조되며, 리소스 끝은 또한 배포의 마이그레이션 단계가 내보낸 contract.json을 다시 로드하고 migrations/를 찾을 수 있도록 prisma.config.ts 경로를 지정합니다.

배포는 재생 전용입니다. migrations/ 아래에 커밋된 마이그레이션을 적용하며 스키마를 직접 생성하지 않습니다. 새 데이터베이스의 첫 번째 스키마를 포함한 모든 스키마 변경은 다음 루프를 따릅니다:

  1. contract.prisma를 편집합니다.
  2. prisma contract emit이 contract.json + contract.d.ts를 재생성합니다.
  3. prisma migration plan --name <slug>가 마이그레이션을 작성합니다 (빈 그래프에서 이것은 기준선을 작성합니다).
  4. 변경 사항과 함께 migrations/를 커밋한 다음 배포합니다. 새 데이터베이스는 처음부터 전체 경로를 재생합니다.

데이터베이스를 사용하는 모든 서비스는 마이그레이션이 완료된 후에만 배포됩니다. 마이그레이션 실패는 새 코드가 전송되지 않음을 의미합니다. 새 배포가 라이브될 때까지 이전 코드가 새 스키마에 대해 서비스되므로, 각 마이그레이션은 대체하는 코드와 호환되도록 유지하세요.

작성된 경로가 대상 계약에 도달하지 않으면, 배포 (및 오래된 로컬 데이터베이스에 대한 dev)는 MIGRATION_PATH_NO로 거부됩니다.

[다음 내용은 번역을 위해 잘렸습니다]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬