withcoral/coral 딥다이브
— 흩어진 API·파일·서비스를 "전부 SQL 테이블"로 둔갑시켜 에이전트에게 쥐여 주는 로컬 쿼리 엔진

1프로젝트 한 줄 요약

withcoral/coral은 내 컴퓨터에서 도는 로컬 우선(local-first) SQL 런타임이다. GitHub API, 로컬 CSV/Parquet 파일, 다른 MCP 서버 같은 서로 다른 데이터 소스를 전부 "테이블"처럼 보이게 감싼 뒤, 평범한 SQL로 질의하게 해 준다. 예컨대 SELECT * FROM github.issues WHERE repo='coral' 한 줄이 실제로는 GitHub REST API 호출로 바뀌어 실행된다.

가장 먼저 풀어야 할 오해 — coral은 데이터를 저장하는 새 데이터베이스가 아니다. Postgres나 MySQL처럼 데이터를 안에 쌓아 두는 게 아니라, 이미 다른 곳(웹 API·파일·서비스)에 사는 데이터를 그 자리에서 SQL로 질의한다. 이렇게 "여러 이질적 소스를 옮기지 않고 한 창구로 질의하는" 기술을 데이터 페더레이션(data federation)이라 부른다. coral은 그 엔진을 Apache DataFusion(러스트로 짠 SQL 쿼리 엔진) 위에 자체 커넥터를 얹어 구현했다.

2왜 지금 주목받는가

coral이 트렌딩에 오른 이유는 "또 하나의 쿼리 엔진"이어서가 아니다. AI 에이전트가 데이터를 다루는 방식의 고질병을 정면으로 겨냥했기 때문이다. 지금 에이전트는 여러 API를 쓰려면 소스마다 툴을 갈아 끼우고, 인증·페이지네이션·재시도 로직을 매번 새로 짜고, 서로 다른 JSON을 힘겹게 이어 붙인다. 이 과정에서 툴 호출이 폭증하고, 토큰이 낭비되고, 크로스 소스(소스 간) 추론은 깨지기 쉽다. coral은 이 모든 걸 단일 SQL 인터페이스로 대체하겠다고 나선다.

주목 포인트 1 — "에이전트에게 데이터를 주는 법"을 SQL로 표준화

AI 에이전트 생태계의 뜨거운 병목은 "모델은 똑똑한데 내 데이터·서비스에 닿기가 번거롭다"는 것이다. MCP(Model Context Protocol)가 그 통로를 표준화했지만, 여전히 툴마다 응답 모양이 제각각이라 에이전트가 여러 소스를 엮으려면 글루 코드가 필요하다. coral은 "모든 소스를 SQL 테이블로" 통일해, 에이전트가 데이터 모델 하나(관계형 테이블)와 언어 하나(SQL)만 알면 되게 만든다. "에이전트 시대의 데이터 접근 계층"이라는 서사가 트렌딩의 동력이다.

주목 포인트 2 — "코드가 할 일은 코드에게" 넘기는 설계

coral의 흥미로운 지점은 필터링·조인·집계처럼 답이 정해진 데이터 작업을 LLM이 아니라 검증된 쿼리 엔진(DataFusion)에 맡긴다는 점이다. 에이전트는 "무엇을 원하는지"를 SQL로 표현만 하고, "어떻게 효율적으로 가져올지"(어떤 필터를 API로 밀어 넣고, 어떤 순서로 조인할지)는 옵티마이저가 결정한다. LLM에게 수백 줄 JSON을 읽혀 헤매게 하는 대신, 정확하고 값싼 부품에 계산을 위임하는 태도다.

주목 포인트 3 — "한 코어, 여러 얼굴"의 실전 패키징

coral은 사실 MCP 서버이자, CLI이자, 로컬 gRPC 서버이자, 데스크톱 앱(Electron)이자, 웹 UI(React)다. 같은 러스트 엔진을 여러 진입점으로 노출한다 — 에이전트는 coral mcp-stdio로, 사람은 터미널이나 reef 데스크톱 앱으로. 9개 크레이트로 나뉜 러스트 워크스페이스 안에, DataFusion 커스텀 확장·gRPC·MCP 서버·봉투 암호화·OpenTelemetry까지 요즘 백엔드 인프라 기술이 밀집해 있어 학습 표본으로도 훌륭하다.

3기술 스택 전체 지도

coral은 Rust로 짠 대규모 워크스페이스다(러스트 edition 2024, 빌드에 rustc 1.95 필요). 코드의 압도적 다수가 .rs(344개 파일, 154,259줄)이고, 프론트엔드(TypeScript/React)는 apps/ 아래 별도로 산다. 특기할 점 하나 — 워크스페이스 전역 린트가 unsafe_code = "forbid"다. unsafe 러스트를 아예 금지하고 unwrap()·인덱싱·panic까지 경고로 잡는, 안전성을 최우선으로 둔 코드베이스다. 스택을 ① 쿼리 엔진, ② 데이터 소스 접근, ③ 전송·서버, ④ 보안·자격증명, ⑤ 관측·CLI로 나눠 지도를 그려 보자.

① 쿼리 엔진 — coral의 심장

② 데이터 소스 접근 — API·파일·MCP

③ 전송 · 서버 — 한 코어를 여러 창구로

④ 보안 · 자격증명 — "키는 로컬을 떠나지 않는다"

데이터 소스 인증정보(API 키·토큰)를 다루는 만큼 보안이 두껍다. 저장 방식은 두 가지 — OS 키체인(keyring-core + macOS/Windows/libsecret 백엔드) 또는 AES-256-GCM 봉투 암호화 파일(ring 0.17로 암호화, zeroize로 메모리에서 즉시 소거). OAuth(device_code·PKCE)·헤더 인증·PAT를 지원하고, 자격증명은 환경변수나 대화형 프롬프트로만 주입되며 로컬을 떠나지 않는다.

⑤ 관측 · CLI · 프론트엔드

관측성은 opentelemetry 0.31 풀스택 + tracing(W3C trace-context)으로 쿼리 실행을 추적한다. CLI는 clap 4.5(derive + env), dialoguer, crossterm. 프론트엔드는 apps/reef(React 19 + React Router 7 + react-aria)와 apps/desktop(Electron 42 + electron-vite, reef를 감싸고 coral 바이너리를 사이드카로 구동), 문서는 apps/docs(Mintlify)로 나뉜다.

9개 러스트 크레이트 = 책임 분리의 교과서

4아키텍처 심화 분석

coral의 핵심 질문은 하나다 — "SQL over anything"을 대체 어떻게 구현하나?" 답은 이렇다. 각 데이터 소스를 선언적 YAML 스펙으로 기술하면, coral-spec이 검증하고, coral-engine이 백엔드(HTTP/파일/MCP)별로 DataFusion TableProvider로 컴파일해 카탈로그에 등록한다. 그 뒤 SessionContext에서 SQL을 실행하면, 엔진이 각 테이블의 provider를 호출해 실제 데이터를 끌어온다. 전체 지도를 먼저 그리자.

핵심 설계 ① — 3개 백엔드로 "무엇이든 테이블로": 커넥터 추상화

coral의 확장점은 3개 백엔드다(crates/coral-engine/src/backends/). 소스 스펙이 어떤 종류냐에 따라 RuntimeSourceComponent enum으로 갈라져, 각자 DataFusion에 등록될 테이블로 컴파일된다.

// crates/coral-engine/src/backends/mod.rs — 백엔드 디스패치
match component {
    RuntimeSourceComponent::Http(manifest) => http::compile_manifest(manifest, request),
    RuntimeSourceComponent::File(manifest) => file::compile_manifest(manifest, request),
    RuntimeSourceComponent::Mcp(manifest)  => mcp::compile_manifest(manifest, request),
}

핵심 설계 ② — HTTP 백엔드: SQL을 "API 호출"로 번역하는 pushdown

가장 흥미로운 부분이다. SELECT title FROM github.issues WHERE owner='withcoral'이라는 SQL이, 실제로는 GET /repos/.../issues?owner=withcoral 같은 API 호출로 바뀐다. 이걸 predicate pushdown(술어 밀어넣기)이라 한다 — 필터 조건을 엔진이 로컬에서 거르는 대신 데이터 소스 쪽으로 밀어 보내 애초에 적게 가져오는 최적화다. DataFusion의 TableProvider 트레이트가 이 훅을 제공한다.

// backends/http/provider.rs — HttpSourceTableProvider: TableProvider
fn supports_filters_pushdown(&self, filters: &[&Expr])
    -> Result<Vec<TableProviderFilterPushDown>>
{
    // 이 API가 쿼리 파라미터로 받아 줄 수 있는 필터를 골라낸다
    let active_request = self.table.resolve_request(&filter_value_keys);
    let consumed = self.backend.request_filter_names(active_request);
    Ok(classify_filter_pushdown_for_consumed(filters, self.table.filters(), &consumed))
}

async fn scan(&self, _state, projection, filters, limit)
    -> Result<Arc<dyn ExecutionPlan>>
{
    // 필수 필터가 없으면 에러(예: 검색 API에 q 누락)
    // consumed 필터 → API 파라미터, 나머지(residual)는 DataFusion이 로컬 적용
    http_json_exec(HttpJsonExecRequest { /* projection, limit, … */ })
}

즉 WHERE 절 중 API가 소화할 수 있는 조건은 파라미터로 pushdown되고, 나머지 조건은 결과를 받아 온 뒤 엔진이 로컬에서 마저 거른다(residual filter). SELECT한 컬럼만 projection으로 좁혀 응답을 줄인다. 이게 "API 트래픽·토큰 절감"의 실제 원리다.

핵심 설계 ③ — 소스 스펙: 코드 대신 "선언적 YAML"로 커넥터를 만든다

새 API를 붙이는 데 러스트 코드를 짤 필요가 없다. YAML 한 장에 "이 API의 이 경로가 이 테이블이고, 이 필터를 받고, 응답의 이 JSON 경로가 이 컬럼"이라고 선언하면 커넥터가 된다(coral-spec이 검증). 아래는 실제 sources/core/github/manifest.yaml의 축약이다.

# sources/core/github/manifest.yaml (dsl_version 3, backend: http)
name: github
base_url: "{{input.GITHUB_API_BASE}}"
auth:
  type: HeaderAuth
  headers:
    - { name: Authorization, template: "Bearer {{input.GITHUB_TOKEN}}" }
tables:
  - name: accepted_assignments
    filters: [{ name: assignment_id, required: true }]
    request: { method: GET, path: /assignments/{{filter.assignment_id}}/accepted }
    pagination: { mode: page, page_param: page, page_size: { query_param: per_page, max: 100 } }
    columns:
      - name: classroom_id
        type: Int64
        expr: { kind: path, path: [assignment, classroom, id] }   # 중첩 JSON → 컬럼
functions:
  - name: search_code                     # SQL 테이블 함수로 노출
    request: { method: GET, path: /search/code }

여기서 배울 설계는 페이지네이션·인증·중첩 JSON 매핑을 전부 "데이터"로 기술했다는 점이다. pagination 블록을 엔진이 읽고 알아서 여러 페이지를 넘겨 가며 모으고, expr: {kind: path, ...}로 깊은 JSON을 평평한 컬럼으로 편다. functions:는 SELECT * FROM search_code(q => 'rust')처럼 SQL 테이블 함수가 된다. 커뮤니티가 이미 181개 소스 스펙을 기여했고(번들 코어 26개), OpenAPI 명세를 import해 자동 생성하는 경로(coral-spec/src/v4/surfaces/openapi/)도 있다.

핵심 설계 ④ — 크로스 소스 JOIN: "dependent join" 커스텀 옵티마이저

coral에서 가장 고급인 부분이다. github.issues와 linear.tickets를 JOIN한다고 하자. 순진하게 하면 양쪽을 통째로 가져와 로컬에서 붙여야 한다. coral은 한쪽(resolver)에서 나온 값들을 다른 소스 API의 필터로 바인딩해 필요한 것만 호출하는 dependent join(의존 조인)을 구현했다. DataFusion의 확장 API 두 개를 직접 구현한다.

주목할 만한 성숙함 — 이 규칙은 변환이 불리할 때의 폴백 사유를 taxonomy로 분류한다(NonEqui=등가조인 아님, NonHttpProvider, CostUnfavourable=비용상 불리, MissingRequired=필수 필터 없음 등). 즉 "무조건 pushdown"이 아니라 이득이 될 때만 하고, 아니면 일반 조인으로 되돌린다. 쿼리 옵티마이저를 직접 확장하는 실전 예제로서 학습 가치가 크다.

핵심 설계 ⑤ — 읽기 전용 강제: 안전이 기본값

coral은 read layer(읽기 계층)로 설계됐다. 쿼리 실행 경로(runtime/query.rs)에서 DataFusion의 SQLOptions로 DML/DDL(INSERT·UPDATE·DELETE·CREATE 등)을 원천 차단한다. 에이전트가 실수로(혹은 프롬프트 인젝션으로) 데이터를 바꾸려 해도 SQL 레벨에서 막힌다. 결과는 Arrow RecordBatch로 만들어져 Arrow IPC로 클라이언트에 스트리밍된다. "에이전트에게 데이터를 열되, 망가뜨릴 권한은 주지 않는다"는 원칙이 코드로 박혀 있다.

5디렉토리 구조 해부

저장소를 열면 압도되기 쉽다(파일 1,647개, 러스트만 15만 줄). 하지만 뼈대는 단순하다 — crates/가 러스트 엔진 두뇌, sources/가 "어떤 API를 테이블로 쓸지"의 카탈로그, apps/가 사람이 쓰는 UI다. 엔진을 이해하려면 coral-engine부터, 커넥터를 이해하려면 sources/부터 보면 된다.

읽는 순서는 이렇다. ① README.md + AGENTS.md(크레이트 경계 규칙) → ② sources/core/github/manifest.yaml(소스가 어떻게 선언되는지) → ③ crates/coral-engine/src/backends/mod.rs(백엔드 디스패치) → ④ backends/http/provider.rs(SQL→API pushdown의 실제) → ⑤ runtime/dependent_join/(크로스 소스 JOIN) → ⑥ crates/coral-mcp/(에이전트가 마주하는 툴 8개). 엔진의 심장은 coral-engine, 커넥터의 문법은 sources/, 에이전트 접점은 coral-mcp — 이 세 곳만 훑어도 전체 그림이 잡힌다.

6학습 포인트

coral이 학습 표본으로 훌륭한 이유는 DataFusion 확장, 데이터 페더레이션, 쿼리 옵티마이저 커스터마이징, 선언적 커넥터 DSL, MCP 서버, 봉투 암호화, 멀티크레이트 워크스페이스 설계가 한 저장소에 모여 있기 때문이다. 관심사별로 배울 것을 짚어 보자.

① DataFusion을 "확장하는" 법 — 라이브러리로 DB를 짓기

backends/http/provider.rs는 DataFusion TableProvider를 직접 구현하는 실전 레퍼런스다. "데이터를 어디서 어떻게 읽어올지"를 엔진에 꽂는 법, supports_filters_pushdown/scan으로 술어·투영·리밋 pushdown을 설계하는 법을 볼 수 있다. "쿼리 엔진을 통째로 만들지 않고, 검증된 엔진에 내 데이터 소스만 얹는" 현대적 접근의 교재다.

② 쿼리 옵티마이저를 직접 확장하기

runtime/dependent_join/는 커스텀 OptimizerRule + UserDefinedLogicalNodeCore로 쿼리 계획을 재작성하는 드문 실전 예제다. "언제 이 최적화가 이득인가"를 비용 기반으로 판단하고, 불리하면 폴백하는 taxonomy 설계까지 담겨 있다. 데이터베이스 내부(옵티마이저)가 어떻게 동작하는지 코드로 배우고 싶은 사람에게 최고의 자료다.

③ "선언적 커넥터"라는 발상

sources/ + coral-spec은 API 통합을 코드가 아니라 데이터(YAML)로 기술하는 법을 보여 준다. 페이지네이션·인증·중첩 JSON 매핑·테이블 함수를 선언으로 표현하고, OpenAPI 명세를 import해 커넥터를 자동 생성하는 파이프라인(coral-spec/src/v4/surfaces/openapi/)까지. "N개 API를 어떻게 확장 가능하게 통합하나"의 아키텍처 답안이다.

④ 에이전트 표면(MCP)을 SQL로 설계하기

coral-mcp는 rmcp(공식 러스트 MCP SDK)로 서버를 짜는 레퍼런스다. 노출 툴이 흥미롭다 — sql(읽기 전용 쿼리 배치), search, list_catalog·describe_table·list_columns(디스커버리), start_task/end_task, feedback. "에이전트가 스스로 스키마를 탐색해 좋은 SQL을 쓰도록" 유도하는 discovery-first 워크플로를 배운다.

⑤ 러스트 멀티크레이트 워크스페이스 + 보안 설계

9개 크레이트로 책임을 가른 구조(엔진/앱/스펙/전송/MCP/CLI…)와 AGENTS.md에 명문화된 크레이트 소유권 규칙은 대규모 러스트 프로젝트의 경계 설계 교재다. 여기에 unsafe_code = "forbid" 정책, AES-256-GCM 봉투 암호화 자격증명(ring+zeroize), OS 키체인 연동까지 — 실무 보안 패턴이 함께 담겨 있다.

7시스템 · 실행 요구사항

coral은 클라우드 인프라가 필요 없다. 실행 파일 하나로 도는 로컬 도구이고, 무거운 모델을 돌리지 않으므로 특별한 GPU나 고사양이 필요 없다. 소스에서 빌드하려면 러스트 툴체인이, 그냥 쓰려면 프리빌트 바이너리만 있으면 된다.

설치 · 에이전트 연결 명령

# 설치 (macOS 예시)
brew install withcoral/tap/coral

# MCP 서버로 에이전트에 연결 (Claude Code 예시)
claude mcp add coral -- coral mcp-stdio
#   Codex · Cursor 등 MCP 지원 에이전트에 동일 방식으로 등록

# 에이전트용 스킬 설치 (범용)
npx skills add withcoral/skills

# 소스(커넥터) 추가 후 SQL로 질의 — SQL은 사람/LLM이 작성
#   예) SELECT number, title FROM github.issues WHERE state = 'open' LIMIT 20

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

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

10핵심 키워드 사전

11참고 링크

경쟁 · 유사 도구 대비 위치

저장소 · 제품
· GitHub: github.com/withcoral/coral (Apache-2.0 · v0.6.0 · 최신 커밋 2026-07-17, PR #1799)
· 조직/제품: withcoral.com
· 토대: Apache DataFusion · 가장 가까운 대안: Steampipe

핵심 파일(클론 후)
· crates/coral-engine/src/backends/mod.rs — 3개 백엔드 디스패치
· crates/coral-engine/src/backends/http/provider.rs — SQL→API pushdown(TableProvider)
· crates/coral-engine/src/runtime/dependent_join/ — 크로스 소스 JOIN 옵티마이저
· crates/coral-engine/src/runtime/query.rs — SessionContext·읽기 전용 강제
· crates/coral-mcp/src/ — MCP 서버(에이전트 표면, 툴 8개)
· sources/core/github/manifest.yaml — 선언적 소스 스펙 예시

배경 지식
· Model Context Protocol — 에이전트 툴 표준
· Apache Arrow · DataFusion · sqlparser-rs
· Federated database system — 페더레이션의 개념
· object_store — 로컬/S3 파일 접근