PlanetScale 완벽 가이드 — 서버리스 MySQL·브랜칭·Deploy Request

· 50분 읽기 · 수정 중급 tutorial
PlanetScale 완벽 가이드 — 서버리스 MySQL·브랜칭·Deploy Request

이 글의 핵심

PlanetScale는 Vitess 위에서 MySQL 프로토콜을 제공하는 관리형 데이터베이스로, Git처럼 데이터베이스 브랜치와 Deploy Request로 스키마를 안전하게 배포합니다. 서버리스 런타임·ORM과의 연동, Boost 캐시, 운영 시 알아야 할 제약까지 한 번에 정리합니다.

이 글의 핵심

PlanetScale은 Vitess를 기반으로 한 MySQL 호환 관리형 데이터베이스 서비스입니다. 단순히 “호스팅된 MySQL”이 아니라, 데이터베이스 브랜치와 Deploy Request(DR) 를 통해 스키마 변경을 코드 리뷰와 유사한 절차로 옮기고, 운영 환경에서의 온라인 스키마 변경 부담을 줄이도록 설계된 제품입니다.

이 글에서는 다음을 순서대로 다룹니다.

  • PlanetScale가 무엇을 표준 MySQL과 다르게 제공하는지(개념 정리)
  • 브랜칭·Deploy Request 로 프로덕션 스키마를 바꾸는 실무 흐름
  • 커넥션 문자열, 서버리스 드라이버, Boost(쿼리 캐시) 의 역할과 한계
  • 확장/축소(expand/contract) 등 스키마 변경 전략
  • Prisma, Drizzle 과의 통합 시 자주 막히는 지점
  • 성능, 가격·제한 및 공식 문서를 함께 봐야 하는 이유

참고: 가격·제한·기능은 시기에 따라 변동됩니다. 운영 결정 전에 반드시 PlanetScale 공식 문서·가격 페이지를 확인하시기 바랍니다.

1. PlanetScale의 핵심 개념

1-1. Vitess와 MySQL “호환”의 의미

PlanetScale의 저장 계층은 Vitess 클러스터 위에서 동작합니다. Vitess는 원래 YouTube 규모에서 검증된 MySQL 샤딩·연결 프록시로 알려져 있으며, 여러 MySQL 인스턴스를 하나의 논리적 클러스터처럼 다루는 기술입니다.

애플리케이션 관점에서는 MySQL 프로토콜과 익숙한 SQL을 사용하므로, 기존 mysql2, Prisma(MySQL), Drizzle(mysql2/planetscale) 등을 그대로 가져오는 경우가 많습니다. 다만 운영 규약은 일반 단일 인스턴스 MySQL과 다릅니다. 예를 들어 스키마 변경은 콘솔에서 임의로 직접 실행하기보다 브랜치에서 검증 → Deploy Request로 병합하는 흐름이 권장됩니다.

1-2. “서버리스 MySQL”이라는 표현을 어떻게 이해할까

PlanetScale 자체가 “쿼리 한 번마다 인스턴스가 새로 뜨는” 형태의 순수 서버리스는 아닙니다. 다만 연결 수가 급변하는 서버리스 함수 환경과 잘 맞도록, HTTP 기반 드라이버(@planetscale/database) 와 TLS가 기본인 연결 등을 통해 연결·배포 모델을 단순화한 측면이 큽니다.

실무에서는 다음처럼 구분하면 혼란이 줄어듭니다.

  • 런타임이 서버리스(Lambda, Vercel Functions, Cloudflare Workers 등)인지
  • DB 연결을 장기 TCP 풀로 유지할 수 있는지

Workers처럼 TCP가 제한적인 환경에서는 HTTP 드라이버가 중요하고, 장기 실행 서버에서는 mysql2 + 커넥션 풀이 여전히 유효합니다. PlanetScale는 이 두 경우를 모두 염두에 둔 연결 URL·드라이버 선택지를 제공합니다.

1-3. 스키마 변경과 “배포”의 분리

전통적인 MySQL 운영에서는 ALTER TABLE이 프로덕션 테이블 잠금·재구축 비용으로 이어질 수 있습니다. PlanetScale는 이런 변경을 Vitess의 온라인 스키마 변경 메커니즘과 함께, 브랜치에서 먼저 적용·검증하도록 유도합니다.

즉, 애플리케이션 배포(컨테이너·함수 배포)와 데이터베이스 스키마 배포를 같은 파이프라인에 묶기보다, 스키마는 DR로 승인·적용하는 문화에 가깝습니다. 이 점이 팀의 DevOps 성숙도와 맞는지 초기에 합의하는 것이 좋습니다.

1-4. 알아두면 좋은 제품 철학(현실적인 기대치)

  • 스키마 변경 가시성: 브랜치·DR 덕분에 “누가 언제 어떤 DDL을 넣었는지” 추적이 쉬워질 수 있습니다.
  • 운영 추상화: 샤딩·라우팅 등은 Vitess가 담당하지만, 애플리케이션 설계·인덱스·쿼리 품질은 여전히 팀의 책임입니다.
  • 다른 매니지드 DB와의 비교: 트랜잭션 요구사항, 감사 로그, 특정 MySQL 플러그인 의존성 등은 사전 검증이 필요합니다.

2. 브랜칭(Branching)과 Deploy Request

2-1. 데이터베이스 브랜치란

프로덕션 브랜치는 실제 서비스 트래픽이 붙는 스키마·데이터 상태입니다. 개발 브랜치는 여기서 복제·분기되어, 스키마 변경과 시드 데이터 실험을 안전하게 반복할 수 있습니다.

Git 브랜치와 유사하게 “메인에 직접 커밋하지 않는다”는 감각으로 접근하면 팀 온보딩이 수월합니다. 다만 데이터베이스이므로 개인정보·대용량 복제 비용 같은 현실 제약도 함께 고려해야 합니다.

2-2. Deploy Request(DR) 워크플로

일반적인 흐름은 다음과 같습니다.

  1. 개발 브랜치에서 마이그레이션 SQL 또는 ORM 생성물로 스키마를 변경한다.
  2. 애플리케이션 코드와 함께 스테이징에서 호환성을 검증한다(특히 확장/축소 패턴).
  3. Deploy Request를 열어 변경 요약·리뷰를 남긴다.
  4. 승인 후 프로덕션 브랜치에 병합(배포) 한다.

이 과정에서 중요한 실무 포인트는 다음과 같습니다.

  • 애플리케이션 배포 순서: “스키마를 먼저 확장(expand)하고, 코드를 배포하고, 사용 종료 후 축소(contract)” 같은 호환성 있는 롤아웃이 없으면 순간적 오류가 납니다.
  • 롤백: 애플리케이션 롤백과 스키마 롤백은 속도와 위험이 다릅니다. DR 메시지에 의도·영향 범위·모니터링 지표를 남기는 습관이 중요합니다.

2-3. CLI(pscale)와 자동화

많은 팀이 CI 파이프라인에서 브랜치 생성·DR 생성을 자동화합니다. 이때 브랜치 이름 규칙, 권한 있는 토큰 보관, 프로덕션 병합 승인 게이트(수동 승인)를 어디에 둘지가 핵심입니다.

CLI 사용 여부와 무관하게, “스키마 변경 = 릴리스” 라는 인식을 팀 규약으로 두면 장애 대응이 쉬워집니다.

3. Connection Strings와 Boost

3-1. 연결 문자열의 역할

PlanetScale 콘솔에서 발급하는 연결 정보는 보통 호스트, 사용자, 비밀번호, 데이터베이스 이름, 그리고 TLS 관련 설정을 포함합니다. MySQL 생태계 도구는 DATABASE_URL 형태로 이를 한 줄에 담는 경우가 많습니다.

실무에서 흔한 실수는 다음과 같습니다.

  • 환경별 URL 혼동: 프로덕션 URL을 로컬에 복사해 데이터를 망가뜨리는 사고
  • 서버리스에서의 연결 폭증: 함수 동시 실행 수만큼 연결이 늘어나 한도에 도달
  • 지역 불일치: 애플리케이션 리전과 DB 리전이 멀면 왕복 지연이 지배적

3-2. 서버리스 드라이버: @planetscale/database

Edge·서버리스 런타임에서는 TCP 기반 풀링이 제한될 수 있어, HTTP 기반 클라이언트가 선택지가 됩니다. 대표적으로 공식 패키지 @planetscale/database 를 사용합니다.

// Edge/서버리스에서 흔한 패턴: 환경 변수 URL로 연결
import { connect } from '@planetscale/database';

const conn = connect({
  url: process.env.DATABASE_URL,
});

export async function listPosts() {
  const result = await conn.execute(
    'SELECT id, title FROM posts WHERE published = ? LIMIT ?',
    [true, 10],
  );
  return result.rows;
}

위 코드는 파라미터 바인딩을 사용해 SQL 인젝션 위험을 줄이는 예시입니다. 서버리스에서는 쿼리당 지연과 동시 실행 수가 비용·체감 성능에 직결되므로, N+1 쿼리 패턴을 특히 경계해야 합니다.

3-3. 장기 실행 서버에서의 mysql2

Node.js 서버처럼 프로세스가 오래 살아 있는 경우 mysql2 와 커넥션 풀이 여전히 효율적일 수 있습니다. 이 경우에도 PlanetScale는 TLS·인증 방식을 맞춰야 하며, 풀 크기는 DB와 애플리케이션 양쪽 제한을 함께 봐야 합니다.

3-4. Boost: “자동 무효화되는 쿼리 캐시”에 가깝다

Boost는 특정 쿼리의 결과를 빠른 메모리 계층에 캐시해 응답 시간을 줄이려는 기능으로 이해할 수 있습니다. 문서화된 사용 패턴에 따르면, 자주 읽히고 스키마와의 일관성이 허용 범위 내인 읽기 쿼리 후보를 다룹니다.

Boost를 논할 때 주의할 점은 다음과 같습니다.

  • 범용 애플리케이션 캐시 대체: 사용자 세션, 복잡한 비즈니스 규칙, 임의 키 기반 캐시까지 모두 Redis처럼 취급하면 안 됩니다.
  • 일관성 창: 캐시 계열 기능은 일반적으로 아주 짧은 지연이 허용되는 읽기에 적합합니다. 금융·재고처럼 강한 일관성이 필요하면 설계를 재검토합니다.
  • 관측 가능성: 느린 쿼리 후보를 Query Insights 등과 연계해 판단하는 흐름이 문서에 자주 등장합니다.

Boost 활성화·세션 변수 설정은 시기·플랜·문서 기준이므로, 도입 전에 공식 문서의 최신 절차를 따르는 것이 안전합니다.

4. 스키마 변경 전략

4-1. 왜 “한 방에 ALTER”가 위험한가

프로덕션에서 스키마와 코드 배포가 어긋나면, 대표적으로 다음이 발생합니다.

  • 알 수 없는 컬럼을 읽거나 쓰려다 실패
  • NOT NULL 제약 추가 순간 기존 코드가 삽입 실패
  • 인덱스 추가로 쓰기·읽기 부하 패턴이 변해 지연 증가

PlanetScale·Vitess가 온라인 변경을 돕더라도, 애플리케이션 호환성은 별개 문제입니다.

4-2. 확장/축소(Expand/Contract) 패턴

가장 보편적인 안전 패턴은 다음과 같습니다.

  1. 확장(Expand): 새 컬럼·새 테이블·새 인덱스를 기존 코드와 호환되게 추가합니다. 기본값·NULL 허용·듀얼 라이트(있다면) 등을 검토합니다.
  2. 이행(Migrate): 백필(backfill) 작업으로 데이터를 채웁니다. 대용량이면 배치 크기·스로틀링이 필요합니다.
  3. 전환(Switch): 애플리케이션을 새 스키마를 사용하도록 배포합니다.
  4. 축소(Contract): 더 이상 쓰이지 않는 컬럼·인덱스를 제거합니다.

이 흐름은 PlanetScale뿐 아니라 대규모 MySQL 운영에서도 표준에 가깝습니다. PlanetScale의 DR은 이 패턴을 리뷰 가능한 단위로 쪼개 기록하기 좋습니다.

4-3. 인덱스 전략

스키마 변경에서 성능 이슈의 상당수는 인덱스 부재·과다에서 옵니다. 다음을 습관화합니다.

  • WHERE·JOIN·ORDER BY에 맞는 복합 인덱스 설계
  • 카디널리티가 낮은 컬럼만으로 인덱스를 만들어 이득이 없는 경우
  • 쓰기 증가와 읽기 이득의 트레이드오프

PlanetScale 콘솔의 인사이트 도구와 함께, 애플리케이션 로그의 슬로우 쿼리를 교차 검증하는 것이 좋습니다.

4-4. 팀 규약으로 정하면 좋은 것

  • 마이그레이션 파일 네이밍·리뷰어 지정
  • DR 설명에 영향 테이블·예상 소요·롤백 계획 포함
  • 데이터 백필 작업의 idempotency(멱등성) 요구

5. Prisma 통합

Prisma는 MySQL 프로바이더로 PlanetScale에 연결할 수 있습니다. 다만 팀이 브랜치 기반 스키마 워크플로를 쓰는 경우, “로컬에서 migrate 한 번으로 끝”이 아니라 PlanetScale 브랜치에 맞춘 URL과 배포 파이프라인을 함께 설계해야 합니다.

5-1. directUrl이 자주 등장하는 이유

서버리스 런타임에서는 마이그레이션용 직접 연결과 런타임 쿼리용 연결을 분리하는 패턴이 문서에 자주 나옵니다. 개념적으로는 “배포/마이그레이션은 안정적인 경로로, 서비스 트래픽은 환경에 맞는 경로로”라고 이해하면 됩니다.

// schema.prisma 예시 — 팀 환경에 맞게 조정 필요
datasource db {
  provider  = "mysql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

directUrl의 실제 필요 여부·값은 Prisma 버전·배포 환경·PlanetScale 연결 방식에 따라 달라집니다. 도입 시점의 Prisma 공식 PlanetScale 가이드를 기준으로 삼는 것이 안전합니다.

5-2. 운영 체크리스트

  • 프로덕션 스키마 변경은 사람의 승인·DR 정책과 맞는가
  • 시드/테스트 데이터가 브랜치에 섞이지 않는가
  • 롤백 시 애플리케이션 버전과 스키마 버전의 조합이 안전한가

Prisma는 생산성이 높지만, PlanetScale의 스키마 운영 철학과 충돌하지 않게 릴리스 규약을 먼저 잡는 것이 중요합니다.

6. Drizzle 통합

Drizzle은 가볍고 SQL에 가까운 ORM으로 알려져 있으며, PlanetScale와 함께할 때는 보통 drizzle-orm 과 @planetscale/database 조합을 검토합니다.

6-1. PlanetScale 서버리스 드라이버 예시

// 개념 예시 — 프로젝트의 빌드·번들 환경에 맞게 조정
import { drizzle } from 'drizzle-orm/planetscale-serverless';
import { connect } from '@planetscale/database';
import * as schema from './schema';

const client = connect({ url: process.env.DATABASE_URL });

export const db = drizzle(client, { schema });

Drizzle의 강점은 스키마를 TypeScript로 명시하고, SQL과의 거리를 팀 취향에 맞게 조절할 수 있다는 점입니다. PlanetScale와의 조합에서는 쿼리 수·트랜잭션 범위를 특히 명확히 하는 편이 운영에 유리합니다.

6-2. mysql2 경로

장기 실행 서버에서는 mysql2 기반 Drizzle 드라이버를 선택할 수도 있습니다. 이 경우 핵심은 풀 설정과 타임아웃, TLS입니다.

7. 성능 최적화

7-1. 지연의 원인을 나누어 본다

PlanetScale를 도입해도 다음은 여전히 지배적입니다.

  • 애플리케이션 ↔ DB 왕복 횟수(N+1)
  • 불필요한 SELECT *
  • 대용량 정렬·조인 without proper indexes

따라서 성능 작업의 첫 단계는 관측입니다. APM, DB 인사이트, 로그의 슬로우 쿼리를 같은 시간축에서 보는 것이 좋습니다.

7-2. 연결·동시성

서버리스에서는 동시성 × 쿼리 수가 곧 비용과 한도 압력이 됩니다. 캐시 계층(애플리케이션 캐시·CDN·읽기 패턴)과 배치 처리를 함께 설계합니다.

7-3. Boost의 위치

Boost는 “느린 읽기 쿼리를 빠르게”에 초점이 맞춰진 경우가 많습니다. 도입한다면 정확성 요구사항과 무효화 지연 허용 범위를 명시하고, 대표 쿼리부터 좁혀 적용하는 것이 리스크가 적습니다.

7-4. 읽기 지역·아키텍처

글로벌 서비스라면 사용자 ↔ 앱 ↔ DB의 지리적 거리를 줄이는 아키텍처가 필요합니다. PlanetScale의 리전·복제 관련 옵션은 플랜과 시기에 따라 다르므로, 성능 목표를 수치로 정한 뒤 공식 문서와 대조하는 방식이 안전합니다.

8. 가격과 제한사항

8-1. 가격을 볼 때 함께 봐야 할 축

관리형 DB 비용은 단순 월 고정료뿐 아니라 다음이 합쳐집니다.

  • 저장 용량 증가
  • 읽기/쓰기 또는 처리량 기반 과금 항목
  • 추가 기능(인사이트, 보안, 지원 수준)

PlanetScale는 시기별로 무료 한도·플랜 구조가 바뀐 바 있으므로, 이 글에 숫자를 고정해 적지 않습니다. 대신 팀은 분기마다 공식 가격표를 리뷰하는 루틴을 두는 것이 좋습니다.

8-2. 제한·주의사항(일반적인 관점)

아래는 “반드시 해당한다”가 아니라 검증이 필요한 대표 축입니다.

  • 특정 MySQL 확장·플러그인 의존 여부
  • 트랜잭션 격리 수준 요구
  • 대용량 배치·장시간 DDL 운영 방식
  • 규제·데이터 상주 요구

이 항목들은 제품 업데이트에 민감하므로, PoC 체크리스트로 문서화하는 것이 좋습니다.

9. 정리

PlanetScale는 MySQL 친숙함과 Vitess의 운영 추상화, 그리고 브랜칭·Deploy Request라는 스키마 배포 경험을 묶어 “서버리스 시대의 MySQL 운영”에 가깝게 만드는 제품입니다. 성공적인 도입은 드라이버 선택만이 아니라 스키마 변경 규약, 확장/축소 패턴, 관측 가능성, 비용 구조 이해가 함께 갖춰질 때 가능합니다.

마지막으로, 이 글의 예시 코드는 개념 이해를 위한 최소 샘플입니다. 실제 프로젝트에서는 비밀 관리, 에러 처리, 관측 로그, 마이그레이션 자동화를 팀 표준에 맞게 확장해야 합니다.

부록: 빠른 체크리스트

  • 프로덕션 URL과 개발 URL이 분리되어 있는가
  • 스키마 변경은 DR·리뷰 절차가 있는가
  • 서버리스에서 N+1이 없는가
  • 인덱스와 슬로우 쿼리가 주기적으로 검토되는가
  • 가격·한도·플랜 변경을 분기별로 확인하는가

본 문서는 기술 설명 목적으로 작성되었으며, 특정 플랜·기능·가격을 보장하지 않습니다. 최신 정보는 PlanetScale 공식 문서를 따르시기 바랍니다.