supabase 딥다이브
— 데이터베이스 하나를 개발 플랫폼으로 만드는 설계

1프로젝트 한줄 요약

Supabase를 한 문장으로 말하면 PostgreSQL 데이터베이스를 웹·모바일·AI 앱에서 바로 쓰도록 주변 기능을 묶은 플랫폼입니다. 데이터는 PostgreSQL에 저장하고, PostgREST는 테이블·뷰·함수를 HTTP API로 노출합니다. Auth는 로그인과 토큰을 담당하고, Storage와 Realtime은 파일과 실시간 연결을 맡습니다.

이 저장소에서 배울 핵심은 데이터베이스를 만드는 법보다, 데이터베이스 주변의 도구들을 일관된 개발 경험으로 연결하는 법입니다. apps/studio에는 관리 화면이, packages/pg-meta에는 데이터베이스 구조를 읽는 SQL 조립기가, docker에는 서비스들을 연결하는 설정이 있습니다.

제품 전체와 이 저장소의 범위를 구분하기

README.md는 제품 전체의 기능을 소개합니다. 반면 루트 package.json의 작업 대상은 pnpm과 Turborepo로 관리하는 앱·패키지입니다. 따라서 GitHub의 주 언어가 TypeScript라는 사실을 PostgreSQL이나 모든 서비스의 구현 언어로 확대하면 안 됩니다.

2왜 주목받는가

2026-10-23 GitHub Trending Daily에서 6위에 선정됐고, 같은 날짜 기준 스타는 113,641개입니다. 이 수치는 관심의 크기를 보여주지만 그날의 순위 상승 원인을 설명하지는 않습니다. 여기서는 저장소에 포함된 앱과 코드에서 읽을 수 있는 장점을 살펴봅니다.

저장소에 포함된 지식 기반 앱

커밋 2f548a69에는 Knowledge Base 앱이 포함돼 있습니다. 오류 해결과 다른 플랫폼에서의 이전 안내를 모은 지식 기반입니다. apps/kb/package.json에는 Astro 의존성과 콘텐츠 생성 스크립트가 있습니다. 이 앱의 존재만으로 트렌딩 순위의 원인을 설명할 수는 없습니다. Knowledge Base 구현과 콘텐츠.

개발자가 관심을 가질 만한 세 가지 이유

다른 선택지와 비교하면 어디가 다른가

비교 범위는 데이터 접근 모델입니다. Firebase 전체를 문서형 데이터베이스 하나로 규정하지 않습니다. Firestore의 문서·컬렉션 모델은 저장소의 Firebase 비교 문서, SQL 연결 구성은 docker/docker-compose.yml을 기준으로 설명합니다. 성능·가격의 우열을 측정한 비교는 아닙니다.

Supabase의 장점은 SQL을 감추는 데 있지 않고, SQL과 권한 모델을 유지하면서 앱 개발에 필요한 연결 작업을 줄이는 데 있습니다.

3기술 스택 전체 지도

버전의 기준은 커밋 2f548a69입니다. package.json의 catalog:는 중앙 버전표를 가리키며, 실제 범위는 pnpm-workspace.yaml에서 찾습니다. 설치 해석 결과는 pnpm-lock.yaml의 catalogs.default에 기록돼 있습니다.

프론트엔드: Studio와 문서·지식 기반

apps/lite-studio는 별도의 경량 앱입니다. apps/lite-studio/package.json에는 react-router: ^7.17.0과 vite: ^8.0.0이 선언돼 있습니다. 같은 모노레포라고 모든 앱이 Next.js로 실행되는 것은 아닙니다.

백엔드: Docker가 조합하는 여러 서비스

다음은 docker/docker-compose.yml의 이미지 태그입니다. 패키지 버전이나 제품 전체 릴리스 번호와 다른 축입니다. 각 엔진의 내부 소스가 이 저장소에 전부 들어 있다는 뜻도 아닙니다.

Storage의 기본 설정은 STORAGE_BACKEND: file, 파일 크기 제한은 52428800바이트, 즉 50 MiB입니다. README의 S3 중심 설명과 달리 기본 Compose는 로컬 파일 저장을 사용하며, S3 계열 구성은 별도 덮어쓰기 파일로 선택합니다. 이런 차이가 설정 파일을 읽어야 하는 이유입니다.

docker/README.md의 구성 소개에는 Logflare와 Vector도 등장합니다. 실제 기본 Compose에는 없으며 docker/docker-compose.logs.yml로 추가합니다. 이때 Logflare 이미지 태그는 1.50.15이고 Studio의 ENABLED_FEATURES_LOGS_ALL이 true로 바뀝니다.

인프라·빌드: 버전을 묶고 작업 순서를 관리한다

Dockerfile은 의존성 가지치기, 설치, 프레임워크별 빌드, 실행 산출물 복사를 단계로 나눕니다. 최종 서버 포트는 3000입니다. STUDIO_FRAMEWORK 선택은 이미지 빌드 시점에 적용됩니다. 실행 중인 이미지에서 환경 변수만 바꿔 두 프레임워크를 즉시 전환하는 구조가 아닙니다.

.github/workflows/typecheck.yml은 잠금 파일 고정 설치 후 같은 작업 안에서 타입 검사와 린트를 병렬 단계로 수행합니다. .github/workflows/studio-unit-tests.yml은 관련 경로 변경을 필터링하고, .github/workflows/studio-lint-ratchet.yml은 선택한 규칙의 위반 수 증가를 막습니다. 기존 경고를 한 번에 없애기 어려운 큰 프로젝트의 점진적 품질 관리 사례입니다.

Python과 Rust는 어디에 있는가

examples/ai/image_search/pyproject.toml은 Python ^3.11, sentence-transformers ^2.7.0, vecs ^0.2.4를 선언합니다. examples/edge-functions/supabase/functions/wasm-modules/add-wasm/Cargo.toml은 Rust 2021 edition, cdylib, wasm-bindgen 0.2를 사용합니다. 둘 다 예제의 의존성입니다. 추적 파일에서 go.mod는 발견되지 않았습니다.

기술 스택을 읽을 때는 웹앱의 패키지, 서비스의 이미지 태그, 예제의 도구 버전을 각각의 범위 안에서 해석해야 합니다.

4아키텍처 심화 분석

아래 도식은 docker/docker-compose.yml과 게이트웨이 설정을 바탕으로 단순화한 자체 호스팅 구조입니다. 각 선이 별도의 네트워크 호출이나 데이터 접근 경계를 뜻합니다. 클라우드의 모든 내부 제어 계층을 묘사한 그림은 아닙니다.

GraphQL 경로는 게이트웨이에서 /rpc/graphql로 바뀌어 PostgREST로 전달됩니다. docker/volumes/api/envoy/lds.template.yaml의 graphql-v1-protected 경로에서 이 연결을 읽을 수 있습니다. GraphQL 전용 서버가 무조건 하나 더 떠 있는 구조로 상상하지 않아도 됩니다.

패턴 1. 입구는 통합하고 책임은 서비스별로 나눈다

API 게이트웨이 패턴은 외부 주소 체계와 내부 서비스 배치를 분리합니다. docker/volumes/api/envoy/lds.template.yaml에는 경로 조건, 대상 cluster, 접두 경로 변환이 있고, docker/volumes/api/envoy/cds.yaml에는 대상 호스트·포트·연결 제한·상태 검사가 있습니다.

# docker/volumes/api/envoy/lds.template.yaml 중 경로 구조 발췌
match:
  prefix: /rest/v1/
route:
  cluster: rest
  prefix_rewrite: /

# docker/volumes/api/envoy/cds.yaml의 rest 대상: rest:3000
# 외부 /rest/v1/todos 요청은 내부 /todos로 전달된다.

Envoy의 경로 설정은 WebSocket 업그레이드를 허용하고 Realtime 경로를 /socket/ 쪽으로 보냅니다. 프록시가 단순히 문자열만 바꾸는 것이 아니라 각 서비스의 통신 방식까지 연결한다는 점을 배울 수 있습니다.

관리용 SQL 경로는 일반 데이터 API와 다르다

apps/studio/data/sql/execute-sql-mutation.ts의 executeSql()은 공통 조회 전송 경계입니다. 프로젝트 식별자를 검사하고, SQL 크기를 0.98 * MB와 비교하며, 연결 정보와 요청 옵션을 붙입니다.

자체 호스팅 서버 진입점은 apps/studio/pages/api/platform/pg-meta/[ref]/query/index.ts의 handlePost()입니다. 이어지는 apps/studio/lib/api/self-hosted/query.ts의 executeQuery()는 assertSelfHosted()를 호출하고, 연결 문자열을 암호화한 헤더와 함께 pg-meta로 보냅니다.

apps/studio/data/fetchers.ts의 createClient<paths>()는 OpenAPI 타입을 사용합니다. constructHeaders()는 요청 ID와 인증 헤더를 구성하고, pgMetaGuard()는 플랫폼 환경에서 필요한 연결 헤더를 검사합니다. 호출마다 이 처리를 복제하지 않도록 한곳에 모은 설계입니다.

패턴 2. 조회 함수와 화면의 캐시 생명주기를 분리한다

apps/studio/data/database/schemas-query.ts에는 getSchemas(), useSchemasQuery(), invalidateSchemasQuery(), prefetchSchemas()가 함께 있습니다. 하나의 자원을 가져오는 방법을 정의하고, 화면·사전 조회·갱신이 그 정의를 재사용합니다.

// apps/studio/data/database/keys.ts의 키 구조
const key = ['projects', projectRef, 'schemas'] as const

// apps/studio/data/database/schemas-query.ts의 핵심 옵션을 줄여 쓴 학습용 예
useQuery({
  queryKey: databaseKeys.schemas(projectRef),
  queryFn: ({ signal }) =>
    getSchemas({ projectRef, connectionString }, signal),
  enabled: enabled && typeof projectRef !== 'undefined',
})

키에 projectRef가 있으므로 서로 다른 프로젝트의 스키마 목록이 같은 캐시 자리에 들어가지 않습니다. AbortSignal을 전달하는 흐름은 필요 없어진 요청을 취소할 통로를 만들고, enabled는 프로젝트가 정해지기 전의 조회를 막습니다.

여기서 한 단계 더 읽어야 합니다. Schema와 SchemasData는 Zod 스키마로부터 타입을 추론하지만, 이 파일의 getSchemas()는 응답에 zod.parse()를 호출하지 않습니다. 실제 처리는 Array.isArray(result) 검사입니다. 타입 선언이 있다는 사실과 모든 응답 필드가 런타임에 검증된다는 주장은 다릅니다.

패턴 3. SQL의 신뢰 경계를 타입으로 표시한다

packages/pg-meta/src/pg-format/index.ts는 일반 문자열과 안전하게 조립할 SQL 조각을 구분합니다. SafeSqlFragment는 문자열에 식별용 타입 표식을 더한 브랜드 타입입니다. 표식은 컴파일 시점의 규칙이며, 별도의 암호학적 검증 값이 아닙니다.

// 타입 구조와 사용법을 보여주는 학습용 예
type SafeSqlFragment = string & {
  readonly __safeSqlFragmentBrand: never
}

const table = ident('user notes')
const owner = literal("O'Reilly")
const sql = safeSql`select * from ${table} where owner = ${owner}`

// 결과: select * from "user notes" where owner = 'O''Reilly'
// safeSql`select * from ${userInput}`
// 일반 string을 그대로 끼우면 타입 규칙에 어긋난다.

실제 safeSql() 구현은 문자열을 이어 붙입니다. 이 함수 자체가 모든 입력을 정제하는 것은 아닙니다. ident()·literal()로 의미에 맞게 변환한 뒤 조합하는 규칙이 중요하며, rawSql()이나 강제 타입 단언을 남용하면 보호를 우회할 수 있습니다.

packages/pg-meta/README.md는 SQL 조각을 매개변수화됐다고 소개하지만, 여기서 본 조립기는 주로 값을 이스케이프한 SQL 문자열을 만듭니다. 일반적인 $1 자리표시자와 값 배열을 전송하는 준비된 쿼리와 동일한 구현이라고 설명하면 부정확합니다. 서버 executeQuery()가 별도 parameters 옵션을 지원하는 점과도 구분해야 합니다.

패턴 4. 성능 요구사항을 실행 계획의 규칙으로 만든다

packages/pg-meta/src/sql/studio/table-editor/table.ts의 getTableEditorSql({ id })는 테이블 정보를 여러 CTE로 묶습니다. base_table_info는 c.oid, primary_keys와 index_cols는 i.indrelid를 요청한 테이블 ID로 제한합니다.

-- getTableEditorSql()의 필터 구조를 줄인 예
with base_table_info as (
  select c.oid, c.relname
  from pg_class c
  where c.oid = 12345
), primary_keys as (
  select i.indrelid
  from pg_index i
  where i.indisprimary and i.indrelid = 12345
)
select * from base_table_info;

테이블 하나를 열 때마다 전체 데이터베이스의 인덱스·제약 조건을 모두 훑으면, 사용자 테이블 수가 많아질수록 관리 화면도 느려집니다. 그래서 결과 값만 맞는지 검사하는 테스트에 더해 어떤 경로로 읽는지를 검사합니다.

packages/pg-meta/test/db/plan-guard.ts의 explainAnalyze()는 EXPLAIN (ANALYZE, FORMAT JSON)을 사용합니다. collectSeqScans()는 계획 트리의 Seq Scan 노드별 관계 이름을 모으고, assertPlanWithinBudget()는 허용 목록·노드 수·실행 시간을 검사합니다. 기본 시간 예산은 1000ms입니다.

packages/pg-meta/test/sql/studio/catalog-plan-guard.test.ts는 합성 카탈로그를 만들고 이 규칙을 적용합니다. 예를 들어 테이블 편집기 예산은 역방향 외래 키 조회의 구조적 이유를 적고 pg_constraint의 Seq Scan 노드를 최대 2개 허용합니다. ‘순차 탐색은 전부 나쁘다’가 아니라, 불가피한 탐색의 이유와 한도를 코드에 남깁니다.

Studio의 executeSql()에도 선택적 preflightCheck가 있습니다. 예상 비용이 200_000 이상이면 차단합니다. 사전 검사 응답의 오류 필드는 무시하지만, 네트워크 예외 등을 잡는 처리는 없습니다. PostgreSQL의 예상 비용은 밀리초가 아니며, 이 선택적 장치를 데이터베이스 전체의 보안·부하 보장으로 해석해서는 안 됩니다.

좋은 추상화는 세부 사항을 지우는 것이 아니라, 요청·권한·SQL·성능의 경계를 읽을 수 있는 위치에 모아 둡니다.

5디렉토리 구조 해부

루트의 supabase/는 Supabase 제품 전체의 모든 서버 코드라는 뜻이 아닙니다. 이 모노레포에서 사용하는 로컬 프로젝트 설정, 함수, 마이그레이션이 모여 있습니다. 한편 docker/는 배포 구성이고, packages/pg-meta는 SQL 생성 라이브러리입니다. 폴더가 다루는 책임을 먼저 구분하면 탐색 범위를 크게 줄일 수 있습니다.

6학습 포인트 (기술별)

TypeScript: ‘문자열’보다 좁은 의미를 모델링하기

SafeSqlFragment와 UntrustedSqlFragment는 같은 문자열도 출처와 허용 동작에 따라 다르게 취급하는 예입니다. 또 apps/studio/data/query-sources/query-source-registry.ts는 _tag: 'database' | 'logs'로 데이터 원본을 구분합니다. 각 SQL 방언과 전송 경계를 잘못 섞지 않도록 유니온 타입을 사용합니다.

연습: 문자열 하나로 표현하던 값을 ‘사용자가 작성한 SQL’과 ‘외부에서 들어온 SQL’로 나누어 종이에 타입을 설계해 보세요. 어떤 함수가 표시만 허용하고 어떤 함수가 실행을 허용해야 하는지 화살표로 표시하면 타입의 목적을 이해할 수 있습니다.

React와 TanStack Query: 서버 상태와 화면 상태를 분리하기

스키마 목록은 서버에서 받은 상태이고, 펼쳐 둔 메뉴는 화면 상태입니다. 둘을 같은 방식으로 관리할 필요는 없습니다. useSchemasQuery()는 조회 키·활성 조건·취소 신호를 묶어 서버 상태를 다룹니다. getSchemas()를 별도 함수로 둬 React 바깥의 사전 조회에서도 재사용합니다.

연습: ‘프로젝트 A의 테이블 목록’과 ‘프로젝트 B의 테이블 목록’의 캐시 키를 각각 써 보세요. 테이블을 만든 뒤 어느 접두 키를 무효화해야 하는지 설명하면, 단순한 데이터 가져오기를 넘어 캐시 설계를 연습하게 됩니다.

PostgreSQL과 RLS: 인증과 행 단위 허용 조건 나누기

examples/todo-list/nextjs-todo-list/supabase/migrations/20230712094349_init.sql은 todos.user_id를 auth.users에 연결하고 RLS를 켭니다. 조회 정책은 auth.uid() = user_id입니다. ‘로그인했는가’와 ‘이 행의 주인인가’를 다른 질문으로 다루는 기초 예제입니다.

연습: 사용자 A와 B가 각각 한 행을 가진 표를 만들고, A의 요청에 정책 조건을 대입해 보세요. 일반 역할에서는 정책이 적용되지만 슈퍼유저와 BYPASSRLS 역할은 우회하며, 소유자도 보통 예외입니다. 이는 PostgreSQL 공식 행 보안 문서의 규칙입니다.

분산 시스템: 함수 실행과 실패 처리를 분리하기

docker/volumes/functions/main/index.ts는 VERIFY_JWT가 true이고 OPTIONS가 아닌 요청의 JWT를 검증합니다. 함수별 디렉토리를 찾은 뒤 EdgeRuntime.userWorkers.create()로 작업자를 생성합니다. isValidHybridJWT()는 토큰 헤더의 알고리즘에 따라 HS256과 ES256·RS256의 검증 경로를 나눕니다. 헤더를 읽는 것 자체는 검증이 아니며, 실제 서명 검사는 jose.jwtVerify()에서 수행합니다.

이 함수 라우터의 제한값은 memoryLimitMb = 150, workerTimeoutMs = 400_000, 요청 부재 제한 60_000ms입니다. Compose는 요청 유휴 제한을 150000ms로 설정합니다. 각 값이 제한하는 대상이 다르며, 호스팅 상품 전체에 일괄 적용되는 보장으로 읽으면 안 됩니다.

연습: resolveRuntimeError()의 오류 종류를 ‘시작 실패 / 자원 부족 / 유휴 시간 초과 / 실행 오류’로 분류해 보세요. 재시도는 WorkerAlreadyRetired에만 적용되고 최초 시도 외 최대 3회입니다. 이미 실행된 임의 요청을 모두 재시도하는 정책과 무엇이 다른지 설명하세요.

벡터 검색: 임베딩과 거리 연산을 SQL로 연결하기

examples/ai/edge-functions/supabase/migrations/20240408072601_embeddings.sql은 vector(384) 열과 hnsw 인덱스, vector_ip_ops 연산자 클래스를 정의합니다. 이어지는 examples/ai/edge-functions/supabase/migrations/20240410031515_vector-search.sql의 query_embeddings()는 <#> 연산자로 음의 내적을 계산하고 정렬합니다.

연습: 왜 임계값에 음수가 붙는지, 왜 모델이 만드는 벡터의 차원이 열의 384와 맞아야 하는지 설명해 보세요. 예제 주석의 코사인 유사도와 내적의 결과 동등성은 벡터가 정규화됐다는 전제를 갖습니다. 모든 모델 출력에 무조건 성립하는 설명으로 외우지 마세요.

CI와 테스트: 결과·실행 계획·배포 조합을 따로 확인하기

.github/workflows/pg-meta-tests.yml은 SQL 패키지 변경 시 테스트를 실행합니다. .github/workflows/self-host-tests-smoke.yml은 default, logs, kong, rustfs, kong-rustfs, pgbouncer 조합을 행렬로 검사합니다. 한 가지 기본 구성만 통과해서는 선택 구성을 보장할 수 없다는 판단이 드러납니다.

연습: 함수 하나의 결과 검사, SQL 실행 계획 검사, 여러 서비스의 상태 검사가 각각 잡을 수 있는 오류를 한 개씩 적어 보세요. 비용이 다른 검사를 같은 수준으로 반복하기보다 위험이 있는 경계에 맞추어 배치하는 연습입니다.

기술을 배웠는지 확인하는 가장 좋은 질문은 ‘이 도구가 어떤 상태와 권한의 경계를 책임지는가’를 자기 말로 설명할 수 있는가입니다.

7하드웨어 / 시스템 요구사항

공식 자체 호스팅 안내의 수치는 apps/docs/content/guides/self-hosting/docker.mdx의 시스템 요구사항 표에서 확인할 수 있습니다. 전체 구성요소를 실행할 때의 기준이며, 특정 앱의 동시 접속자 수나 응답 시간을 보증하는 수치는 아닙니다.

같은 안내는 불필요한 서비스를 제거하면 자원 요구량을 줄일 수 있고, 로그·분석 서비스를 추가하면 더 많은 자원이 필요하다고 설명합니다. 데이터량·인덱스·업로드 파일·백업은 계속 디스크를 차지하므로, 초기 컨테이너가 실행되는 것과 장기 운영에 충분한 것은 다릅니다.

학습 방식별 준비 범위

개발 PC의 여유 메모리로는 16 GB 이상을 잡으면 브라우저·편집기·빌드·컨테이너를 함께 다루기 편할 수 있습니다. 이는 공식 최소 사양이 아닌 학습 환경을 위한 여유치 제안입니다. 실제 CI도 Studio 단위 테스트에 약 3 GB, 타입 검사와 일부 빌드에 약 4 GB의 Node 힙 상한을 둡니다. 힙 상한은 전체 프로세스 메모리와 같지 않습니다.

포트와 저장 공간을 읽는 법

• Studio 소스 개발 서버는 기본 8082, Studio Docker 이미지의 서버는 3000입니다.
• 자체 호스팅 게이트웨이의 기본 공개 포트는 8000입니다. 내부 서비스의 같은 숫자 포트와 구분하세요.
• Supavisor는 환경 변수로 지정한 포트를 내부 5432와 6543에 연결합니다. 세션·트랜잭션 풀링의 용도를 따로 읽어야 합니다.
• DB 데이터, Storage 파일 볼륨, 함수 캐시, 로그는 수명이 다릅니다. 컨테이너를 지우는 작업과 영속 데이터를 지우는 작업도 다릅니다.

시스템 요구사항은 제품 이름 하나에 붙는 숫자가 아니라, 실제로 실행할 서비스와 보관할 데이터의 합으로 결정됩니다.

8직접 해볼 수 있는 실습 과제

아래 과제는 서버를 설치하거나 저장소 코드를 실행하지 않아도 진행할 수 있습니다. 명령은 저장소 루트를 기준으로 파일을 검색하거나 읽습니다. 완성 기준은 ‘파일을 열었다’가 아니라 입력·출력·권한·실패 조건을 설명할 결과물입니다.

# 경로와 호출 위치만 찾아 읽는다.
rg -n 'prefix: /rest/v1/|cluster: rest|prefix_rewrite:' \
  docker/volumes/api/envoy/lds.template.yaml
rg -n 'getSchemas|useSchemasQuery|executeSql' \
  apps/studio/data/database/schemas-query.ts
sed -n '1,110p' \
  'apps/studio/pages/api/platform/pg-meta/[ref]/query/index.ts'

심화 질문: 테이블 이름을 literal()로 처리하면 왜 원하는 쿼리가 되지 않을까요? 이름과 값을 안전하게 표현하는 방법은 서로 대체할 수 없습니다. 안전성뿐 아니라 SQL 문법상 의미도 맞아야 합니다.

-- 원본 예제를 설명하기 위한 별도의 정책 설계 예
-- 테이블 접근 권한이 있다는 전제에서 정책을 판정한다.
alter table public.todos enable row level security;

create policy own_todos_select on public.todos
for select to authenticated
using ((select auth.uid()) = user_id);

create policy own_todos_update on public.todos
for update to authenticated
using ((select auth.uid()) = user_id)
with check ((select auth.uid()) = user_id);

여기서 USING은 수정 전의 행을 고르고, WITH CHECK는 수정 후의 행을 검사합니다. 원본 예제의 UPDATE 정책은 USING만 적습니다. WITH CHECK를 생략하면 USING 조건을 수정 후 행의 검사에도 재사용하므로 곧바로 취약점이라고 단정하면 안 됩니다. 위 예는 두 의도를 명시적으로 보여줍니다.

추가 질문: A가 자기 행의 user_id를 B로 바꾸려 하면 어떤 조건이 막을까요? UPDATE에는 행을 볼 수 있는 SELECT 정책도 함께 고려해야 합니다. 관리자 역할로 확인한 결과는 일반 사용자 정책의 검증을 대신하지 못합니다.

['projects', 'A', 'schemas']
['projects', 'B', 'schemas']
['projects', 'A', 'table-columns', 'public', 'todos']
['projects', 'A', 'table-columns', 'public', 'profiles']
// A의 스키마 조회만 갱신할 때의 기준 키는 무엇일까?

// 실행하지 않고 검토하는 테스트 예산 설계 예
{
  allowedSeqScans: {
    pg_constraint: {
      max: 2,
      reason: '역방향 외래 키 탐색에 필요한 구조적 스캔',
    },
  },
  maxExecutionTimeMs: 1000,
}

EXPLAIN ANALYZE는 쿼리를 실제 실행한다는 점도 답안에 포함하세요. 합성 카탈로그의 기본 테이블 수는 packages/pg-meta/test/db/stress-catalog.ts에서 2000입니다. 이 크기에서 만든 예산은 모든 운영 환경의 성능 보증과 다릅니다.

실습의 목표는 큰 서비스를 켜는 데서 끝나지 않고, 요청 한 건의 데이터·권한·캐시·비용을 끝까지 설명하는 것입니다.

9관련 기술 심화 학습 로드맵

HTML·JavaScript의 기본 문법을 알고 있다는 전제로 6주 흐름을 제안합니다. 모든 패키지를 같은 깊이로 공부하기보다, 작은 요청 한 건을 이해한 뒤 그 주변으로 범위를 넓혀 가세요. 각 주의 결과물은 다음 주의 질문을 만드는 재료입니다.

그다음에는 관심사에 따라 갈라진다

• 프론트엔드: apps/studio/pages/와 apps/studio/routes/의 연결을 비교하며 점진적 프레임워크 전환을 배웁니다. 기능과 실행 환경을 한 번에 교체하지 않는 방법을 설명해 보세요.
• 백엔드·데이터: RLS 정책에서 출발해 인덱스·쿼리 계획·동시성·트랜잭션 격리 수준으로 확장합니다. 화면의 편리함을 데이터베이스 비용으로 환산하는 능력을 키웁니다.
• 인프라: 기본 Compose와 선택 덮어쓰기 파일을 비교하고, 장애 복구·백업 복원·관측 데이터의 흐름을 설계합니다. 상태 검사 통과와 업무 기능 정상의 차이도 살펴봅니다.
• AI 앱: 벡터 차원·거리 연산·HNSW를 익힌 뒤 검색 결과에 사용자 권한이 어떻게 적용돼야 하는지 설계합니다. 벡터 검색과 접근 제어를 별개의 책임으로 놓치지 마세요.

공부의 순서는 제품 기능 목록보다 데이터 한 건의 이동 경로를 기준으로 잡을 때 서로 다른 기술을 연결하기 쉽습니다.

10핵심 키워드 사전

11참고 링크

공식 저장소와 제품 문서

• supabase/supabase 공식 저장소 — 제품 개요와 모노레포의 출발점
• 분석 기준 커밋의 전체 트리 — 이 글의 파일 경로 기준
• Supabase 공식 문서 — 제품별 사용법과 개념
• Docker 자체 호스팅 안내 — 자원 요구사항과 구성 방식
• Supabase RLS 안내 — 사용자 식별과 행 정책의 연결
• Knowledge Base 앱 — 오류 해결·이전 안내와 Astro 구현
• 릴리스 v1.26.08 — 2026-08-07 릴리스 정보

본문에서 따라간 핵심 구현

• pnpm-workspace.yaml · pnpm-lock.yaml — 중앙 버전과 실제 잠금 결과
• apps/studio/data/database/schemas-query.ts — 조회 함수·훅·무효화·사전 조회
• apps/studio/data/sql/execute-sql-mutation.ts — SQL 전송과 선택적 비용 검사
• apps/studio/data/fetchers.ts — 타입 있는 HTTP 클라이언트와 공통 처리
• apps/studio/lib/api/self-hosted/query.ts — 자체 호스팅 서버의 pg-meta 연결
• packages/pg-meta/src/pg-format/index.ts — SQL 조각 타입·식별자·리터럴 처리
• packages/pg-meta/src/sql/studio/table-editor/table.ts — 테이블 카탈로그 조회
• packages/pg-meta/test/db/plan-guard.ts — 실행 계획의 탐색·시간 예산 검사
• docker/docker-compose.yml · Envoy 경로 설정 — 서비스 이미지와 요청 분배
• docker/volumes/functions/main/index.ts — JWT 검증·작업자 생성·실패 분류
• apps/studio/scripts/dispatch.js · apps/studio/Dockerfile — 병행 실행 환경과 빌드 단계

관련 기술의 원문

• PostgreSQL 행 보안 정책 — 정책 조건과 우회 역할의 정확한 규칙
• PostgreSQL EXPLAIN 안내 — 계획과 실제 측정의 차이
• PostgREST API 문서 — 테이블·뷰·함수의 API 매핑
• TanStack Query의 조회 키 — 캐시 주소 설계
• pgvector 공식 저장소 — 벡터 연산자와 인덱스
• supabase-js 공식 저장소 — 클라이언트 SDK의 내부 구현
• Auth · Realtime · Storage · postgres-meta — 각 서비스의 별도 소스

현재 상태 (2026-10-23 확인)

줄 수는 추적된 일반 파일을 확장자별로 묶고 물리적 줄을 센 대략적인 규모입니다. 주석·빈 줄·테스트·예제·생성 파일을 포함하며, 마지막 개행이 없는 행도 한 줄로 셌습니다. JavaScript 계열은 .js·.jsx·.mjs·.cjs의 합입니다. 이미지·잠금 파일의 모든 형식을 소스 줄 수에 섞지는 않았습니다. 서비스별 별도 저장소의 코드는 이 수치에 포함되지 않습니다.