본문으로 건너뛰기

영속성 마이그레이션

어댑터가 스키마를 소유합니다. TanStack AI는 테이블을 검사하지 않으므로 테이블 레이아웃과 스키마 변경 사항을 적용하는 방법을 직접 결정합니다. 해당 스토어를 읽거나 쓰는 코드를 배포하기 전에 변경 사항을 적용합니다.

로컬 개발을 위해 열 때 테이블 생성​

수동으로 만든 어댑터는 데이터베이스를 처음 열 때 테이블을 생성할 수 있습니다. Build your own adapter의 SQLite 예시는 migrate 플래그와 CREATE TABLE IF NOT EXISTS 뒤에 이를 수행하므로 멱등적입니다.

import { sqlitePersistence } from './sqlite-persistence'

const persistence = sqlitePersistence({
  url: 'file:.data/state.sqlite',
  migrate: true,
})

이는 로컬 개발과 테스트에 편리합니다. 프로덕션에서는 요청 시점의 마이그레이션을 피합니다.

프로덕션에서 마이그레이션 적용​

프로덕션에서는 첫 요청 시가 아니라 일반적인 배포 워크플로를 통해 스키마 변경을 실행합니다. 네 개 테이블(messages, runs, interrupts, metadata)의 DDL을 버전이 지정된 마이그레이션에 보관하고, 새 코드를 배포하기 전에 데이터베이스의 나머지 부분에 사용하는 것과 동일한 도구로 적용합니다.

ORM 또는 쿼리 빌더로 어댑터를 빌드한다면 해당 도구가 마이그레이션 저널을 관리하도록 합니다. Drizzle 스키마는 drizzle-kit을 사용하고, Prisma 모델 조각은 prisma migrate를 사용하며, 원시 SQL 어댑터는 일반 .sql 파일을 커밋합니다. @tanstack/ai-persistence의 어댑터 빌드 스킬에서 이러한 각 워크플로를 다룹니다.

기존 스키마는 자체 마이그레이션을 관리함​

이미 있는 테이블에 스토어 계약을 매핑한다면(자체 어댑터 빌드 참조), 해당 테이블은 애플리케이션 스키마의 일부이며 기존 마이그레이션 도구가 이미 관리합니다. 일반 마이그레이션에서 스토어에 필요한 열을 추가합니다. 스토어의 삽입이 계속 성공하도록 앱이 소유하는 추가 열은 nullable이거나 기본값을 갖도록 유지합니다.

업그레이드 원칙​

  1. 스토어 테이블의 DDL을 요청 핸들러 안에 직접 작성하지 말고 검토 가능한 마이그레이션에 보관합니다.
  2. 필요한 경우 프로덕션 상태를 백업합니다.
  3. 해당 마이그레이션에 의존하는 코드를 배포하기 전에 마이그레이션을 적용합니다.
  4. 롤백 및 부분 배포 동작을 명시적으로 유지합니다.