reylo 딥다이브
— SQL 한 파일이 타입 있는 함수가 되기까지

1프로젝트 한줄 요약

reylo는 .sql 파일을 직접 가져와, 매개변수와 결과 타입이 추론된 쿼리 객체로 쓰게 하는 TypeScript 라이브러리입니다. Postgres·MySQL·SQLite를 다루며, 실제 쿼리는 애플리케이션이 고른 드라이버로 실행합니다. 데이터베이스 서버를 대신 운영하거나 테이블을 자동 생성하는 제품은 아닙니다.

SQL과 데이터베이스 스키마를 읽어 타입을 정하고, 그 타입에 맞춰 실행 결과까지 정리하는 연결이 이 프로젝트의 핵심입니다. 따라서 공부할 대상도 SQL 문법 하나에 그치지 않습니다. 컴파일러 확장, Rust의 인터페이스 설계, 캐시 무효화, 여러 실행 환경을 하나의 API로 묶는 방법을 함께 볼 수 있습니다.

1-1. 먼저 작은 사용 장면을 읽어 보자

다음은 이해를 위한 예제입니다. users.id가 integer primary key이고, name은 text not null, email은 NULL을 허용한다고 가정합니다. 테이블 정의가 달라지면 추론도 달라집니다.

-- get_user.sql: :id는 이름이 있는 매개변수
select id, name, email
from users
where id = :id::int

// main.ts: Postgres 드라이버와 런타임 로더 설정을 마친 뒤의 코드
import postgres from "postgres";
import getUser from "./get_user.sql";

const db = postgres(process.env.DATABASE_URL!);
const user = await getUser.run(db, { id: 1 });
// 추론되는 결과: { id: number; name: string; email: string | null } | null
if (user !== null) {
  console.log(user.name);
}
await db.end();

결과 끝의 | null은 사용자가 없을 수 있다는 뜻입니다. email의 | null은 사용자는 있지만 이메일이 비어 있을 수 있다는 뜻입니다. 행의 존재 여부와 열의 NULL 가능성은 서로 다른 정보입니다.

1-2. 반환값은 행 수에 따라 달라진다

이 반환 규칙은 src/index.ts의 Materialize<Row, C> 조건부 타입과 defineQuery() 내부의 materialize() 분기에 함께 정의되어 있습니다. 정적 타입과 실제 반환 동작을 짝지어 읽는 것이 첫 번째 학습 과제입니다.

2왜 주목받는가

2-1. 새로운 TypeScript 확장을 SQL에 적용했다

선정 근거는 TrendShift Daily #21(2026-10-23)입니다. 2026-10-23 GitHub 기준, 저장소 생성일은 2026-10-21이며 스타는 776개입니다. 다만 이 숫자만으로 유입 경로, 사용자 수, 실제 도입률을 알 수는 없습니다. 다음 세 가지는 관심을 끌 이유에 대한 설계 관점의 해석입니다.

• SQL을 그대로 쓴다. 쿼리를 다른 언어의 메서드 호출로 다시 표현하는 대신 SQL 파일 자체를 가져옵니다.
• 타입 갱신을 컴파일러에 연결한다. 별도의 타입 파일 생성 명령을 매번 기억해야 하는 부담을 줄입니다.
• 기존 드라이버를 유지한다. 실행 경로는 호출자가 넘긴 클라이언트를 받아 여러 드라이버에 맞춰 처리합니다.

이를 가능하게 하는 기능이 콘텐츠 매퍼입니다. TypeScript가 외부 형식의 파일을 가상 TypeScript로 읽도록 변환기에 맡기는 방식입니다. 공식 제안에는 표준 입출력의 JSON-RPC 통신과 --runExternalCode가 설명되어 있고, reylo의 구현은 src/rpc.ts·src/mapper.ts에 있습니다. TypeScript 콘텐츠 매퍼 공식 제안

“생성할 타입 파일이 없다”와 “내부에서 코드를 전혀 만들지 않는다”는 서로 다른 주장입니다. src/mapper.ts는 export type Params와 declare const query를 포함한 텍스트를 만들고, src/loader.ts의 sqlModule()은 defineQuery(...)를 호출하는 실행 모듈을 만듭니다.

2-2. 비슷한 문제를 푸는 방법과 비교

비교는 기능 전체의 우열이나 성능 비교가 아닙니다. “SQL 수정 뒤 어떤 단계로 타입이 갱신되는가”에 한정했습니다. 경쟁 도구의 흐름은 Prisma TypedSQL 공식 문서와 sqlc 생성 명령 공식 문서 기준입니다. sqlc도 DB 기반 분석을 제공하므로 “DB에 물어보는 것은 reylo만의 기능”이라고 하면 부정확합니다.

2-3. AI가 SQL을 써도, 검사는 구체적인 근거로 한다

README는 에이전트 친화성을 장점으로 내세웁니다. SQL·스키마·타입 선언을 여러 군데서 함께 수정할 필요를 줄인다는 주장입니다. 소스에서 확인 가능한 부분은 철자가 틀린 열이나 타입이 없는 매개변수를 진단으로 돌려주는 경로입니다. AI 모델을 호출하는 추론 엔진이 들어 있다는 뜻은 아닙니다.

src/module-types.ts의 moduleTypes()는 strictParams가 켜져 있고 매개변수 타입이 unknown이면 코드 12 진단을 만듭니다. SQL이 이미 다른 오류로 분석에 실패했다면 그 오류를 먼저 고치도록 중복 진단을 줄입니다. “타입이 틀렸다”뿐 아니라 어떤 오류를 먼저 보여줄지도 제품 설계라는 점을 배울 수 있습니다.

3기술 스택 전체 지도

이 저장소에는 애플리케이션용 백엔드 서버와 프론트엔드가 한 쌍으로 존재하는 전형적인 웹 서비스 구조가 없습니다. 분석 엔진을 백엔드 역할로, TypeScript 패키지를 개발 도구와 실행 연결층으로 구분하면 이해하기 쉽습니다. React 프론트엔드는 이 라이브러리를 쓰기 위한 필수 런타임이 아니라 문서 사이트입니다.

3-1. 백엔드 역할: Rust·C 분석 엔진

이 값들은 engine/core/Cargo.toml과 DB별 Cargo.toml, Cargo.lock, engine/build.sh의 선언·잠금 값입니다. 예를 들어 serde_json의 잠금 버전은 1.0.151, bindgen은 0.66.1입니다. 허용 범위를 선언한 버전과 실제로 잠긴 버전을 구분해서 읽으세요.

3-2. 개발 도구와 실행 연결층: TypeScript

scripts/build.ts는 소스를 dist/reylo로 컴파일하고 패키지의 내보내기 경로를 .ts에서 .js·.d.ts로 바꿉니다. 엔진은 dist/postgres 등으로 따로 복사합니다. 소스 패키지의 private: true는 우발적인 배포를 막는 설정이며, 배포본을 만드는 단계에서는 해당 속성을 제거합니다.

3-3. 프론트엔드: 문서와 추론 결과를 보여주는 사이트

site/react-router.config.ts는 ssr: false와 prerender 목록을 지정합니다. 빌드 때 문서와 Markdown 경로를 만들고, site/vercel.json은 build/client를 배포 대상으로 삼습니다. “React가 들어 있으니 DB 쿼리가 브라우저에서 직접 실행된다”는 해석은 이 구성과 맞지 않습니다.

3-4. 인프라·빌드·검증

사용자가 실행하는 SQL 함수와, 그 함수의 타입을 만드는 개발 도구는 서로 다른 의존성과 실행 시점을 가집니다. src/engine.ts의 WASI 호스팅과 src/index.ts의 쿼리 API를 나란히 읽으면 이 경계가 드러납니다.

4아키텍처 심화 분석

4-1. 전체 구조: 타입 검사와 실행을 나누어 보기

중요한 구분은 쿼리 모듈이 만들어지는 때와 .run()을 호출하는 때입니다. Node의 등록 훅은 실행 프로세스에서 모듈을 불러올 때 분석 경로를 사용할 수 있고, 번들러는 미리 분석 정보를 담은 모듈을 만듭니다. “개발 도구 경로”가 언제나 별도의 빌드 서버에서만 돈다는 뜻은 아닙니다.

src/mapper.ts의 transform()은 분석 결과를 받아 가상 선언을 돌려줍니다. src/loader.ts의 sqlModule()은 같은 결과를 실행 코드로 바꿉니다. 동일한 분석 결과에 두 소비자가 붙어 있는 구조라고 읽으면 됩니다.

4-2. 설계 패턴 ①: 계산 엔진과 입출력 호스트 분리

Rust 엔진은 직접 DB 연결을 열지 않습니다. 필요한 답이 없으면 “이 문장을 describe해 달라”, “이 카탈로그 쿼리를 실행해 달라”는 요청을 모읍니다. TypeScript 호스트가 그 일을 처리한 뒤, 지금까지의 답을 넣어 엔진을 다시 호출합니다.

engine/core/src/host.rs의 Host::describe()와 Host::query()를 보면 동작이 명확합니다. 답 목록에 해당 키가 있으면 그 값을 반환하고, 없으면 Need를 기록한 다음 None을 돌려줍니다. 이 파일의 Lazy<T>는 Option<T> 별칭이며, 이 문맥의 None은 “아직 답을 받지 못했다”는 뜻입니다.

// src/engine.ts / Engine.analyze()의 핵심 제어 흐름을 줄인 의사 코드
const answers = {};
for (let round = 0; round < 16; round++) {
  const result = engine.call({ op: "analyze", sql, dialect, answers });
  if (result.status === "analysis") return result.analysis;
  if (result.status !== "need") throw new Error("분석 응답 오류");
  await Promise.all(result.needs.map(async (need) => {
    answers[need.id] = await fulfil(need, io);
  }));
}
throw new Error("분석이 수렴하지 않음");

실제 구현은 중간에 AnswerCache.get()도 사용하며, 왕복 횟수를 최대 16회로 제한합니다. 한 차례의 독립 요청은 Promise.all()로 처리합니다. 모든 요청이 병렬로 실행된다고 단정할 수는 없습니다. 드라이버의 연결 수와 요청 간 의존성에 따라 실제 실행은 달라집니다.

Engine.call()은 JSON을 UTF-8 바이트로 바꾸고, WASM의 reylo_alloc으로 메모리를 확보한 뒤 reylo_call을 호출합니다. 결과 앞의 4바이트 길이를 읽어 JSON으로 복원하고 reylo_free로 해제합니다. 서로 다른 언어를 묶는 부분에서는 타입뿐 아니라 바이트 길이와 메모리 소유권도 계약이 됩니다.

읽을 파일: src/engine.ts · engine/core/src/host.rs · engine/core/src/abi.rs.

4-3. 설계 패턴 ②: DB별 구현을 같은 계약으로 묶기

engine/core/src/database.rs의 Database trait는 DB별 분석 구현이 갖춰야 할 항목을 정합니다. 각 DB는 방언과 지문 상수, describe 응답의 타입, analyze()를 제공합니다. 공통 round()는 분석이 끝났으면 신선도 확인용 사실을 덧붙이고, 아직 답이 없으면 필요한 목록을 반환합니다.

// Database trait에서 핵심 항목만 발췌
pub trait Database {
    const DIALECT: Dialect;
    const FINGERPRINT: &'static str;
    type Describe: Describe;
    fn analyze(sql: &str, host: &Host<'_, Self::Describe>) -> Lazy<Analysis>;
    // round(), tables(), unbundle() 등은 생략
}

각 WASM 진입 crate는 특정 DB를 골라 공통 API를 구체화합니다. 이 trait는 소스 주석이 밝히듯 정적 디스패치에 쓰입니다. 모든 DB를 하나의 거대한 바이너리에 넣고 실행 중 교체하는 구조와는 다릅니다. DB별 crate가 다른 DB crate에 의존하지 않는 점도 이 경계를 뒷받침합니다.

따라서 README의 “DB가 prepare한 결과를 읽는다”는 요약을 세 DB에 똑같이 적용하면 세부 동작을 놓칩니다. 특히 SQLite는 애플리케이션이 쓰는 SQLite와 분석 엔진의 SQLite가 다를 수 있어, src/sqlite-drivers.ts가 프로젝트에서 찾은 드라이버로 추가 prepare 검사를 수행합니다. 이 추가 검사에도 지원 대상의 범위가 있습니다.

Postgres에서 결과 타입을 좁히는 순서

1. engine/postgres/src/postgres.rs::analyze()가 엔진 스택에서 분석을 시작하고, 구조화 매개변수 처리 뒤 일반 분석으로 들어갑니다.
2. 이름 있는 매개변수를 서버의 $1 형식으로 바꾸고 describe 응답에서 타입과 열의 출처를 읽습니다.
3. 출처가 있는 열은 카탈로그의 NOT NULL 같은 사실을 읽고, 외부 조인이 NULL을 만들 수 있는지 반영합니다.
4. 표현식은 infer::plan()·infer::resolve()의 규칙을 더합니다. JSON 모양은 engine/postgres/src/jsonshape.rs가 별도로 담당합니다.
5. Engine::cardinality()는 exactly_one()을 먼저, 이어 at_most_one()을 시도해 반환 행 수 범주를 정합니다.

예를 들어 count(*)의 결과 열은 일반 테이블 열처럼 출처를 추적할 수 없습니다. engine/postgres/src/infer.rs는 count가 NULL이 되지 않는 규칙을 알고 있지만, 일반적인 다른 집계는 빈 입력에서 NULL이 될 수 있다고 봅니다. coalesce, CASE, 외부 조인 등을 거치면 다시 다른 규칙이 필요합니다.

engine/postgres/src/cardinality.rs는 GROUP BY·HAVING·LIMIT·집합 반환 함수 등을 살펴봅니다. “집계니까 언제나 한 행”이라고 단순화하지 않습니다. 사용자 정의 함수나 연산자가 기본 이름을 가린 경우에는 Trust 정보로 기본 규칙의 적용을 제한합니다.

확실하지 않은 결과를 더 넓은 타입으로 남기는 선택이, 잘못 좁힌 타입 때문에 실행 중 깨지는 것보다 안전하다는 판단이 코드에 반복됩니다. 이를 읽을 때 “추론하지 못함”과 “그 값이 절대 나오지 않음”을 구별해야 합니다.

4-4. 설계 패턴 ③: 분석 경로 하나와, 유효성을 따지는 캐시

src/analyze.ts의 Session은 콘텐츠 매퍼·번들러·등록 훅·CLI가 함께 사용하는 진입점입니다. entryFile()은 .reylo/queries/ 아래 파일 위치를 만들고, #statementKey()는 캐시 형식 버전·엔진 지문·DB 방언·SQL을 해시합니다. 서버 식별값의 해시도 파일명에 붙입니다.

캐시 본문에는 version, dialect, schema, analysis, at를 저장합니다. 분석 결과가 있다는 사실만 보지 않고 어떤 스키마를 상대로 만든 결과인지를 함께 기록하는 것입니다. 같은 SQL이어도 스키마가 바뀌면 다시 분석해야 하기 때문입니다.

이 TTL 값과 src/engine.ts의 AnswerCache는 구분해야 합니다. 후자는 엔진이 요청한 개별 답을 재사용하며 기본 TTL이 세션 범위 60초·문장 범위 5초입니다. 둘 다 시간을 쓰지만 저장하는 대상과 무효화 조건이 다릅니다.

4-5. 설계 패턴 ④: 타입 계약을 실행 데이터까지 이어 붙이기

sqlModule()은 타입 선언만 만들지 않습니다. 이름별 입력 타입, 드라이버에 전달할 순서, 열별 값 표현 방식, 행 수 범주를 실행 모듈에 넣습니다. defineQuery()는 이를 받아 .run()·.runSync()·.with()를 구성합니다.

src/execute.ts의 ClientFor<D>는 방언에 따라 허용되는 클라이언트 타입을 고릅니다. 실행 시에는 query()·unsafe()·prepare() 등 실제 메서드 형태를 보고 어댑터를 선택합니다. 드라이버 전체 클래스를 상속받기보다 필요한 메서드의 최소 형태를 계약으로 삼습니다.

여기서 어려운 부분은 메서드 이름만이 아닙니다. 드라이버에 따라 64비트 정수·날짜·JSON의 JavaScript 표현이 다릅니다. src/values.ts가 표현 방식을 모으고, src/render.ts·src/schema.ts·DB별 디코더가 이를 공유합니다.

SQLite의 일반 INTEGER는 number이며, NUMERIC은 저장된 값에 따라 숫자나 문자열이 될 수 있습니다. 행 수도 실행 시 다시 셉니다. materialize()는 one인데 0행이나 2행이 오면 오류를 내고, maybeOne인데 2행 이상이면 오류를 냅니다. TypeScript의 조건부 타입을 실제 JavaScript 분기로 뒷받침하는 좋은 사례입니다.

읽을 파일: src/loader.ts · src/index.ts · src/values.ts.

5디렉토리 구조 해부

아래 트리는 저장소 루트 기준입니다. src/는 TypeScript 라이브러리, engine/은 Rust·C 분석 엔진, oracle/은 실제 쿼리 결과로 추론을 검사하는 도구입니다.

5-1. 폴더 경계에서 의도를 읽는 법

examples/와 lab/는 비슷해 보여도 목적이 다릅니다. 전자는 사용자가 복제할 설정 단위의 예제이고, 후자는 드라이버 조합·경계 사례를 검증하는 작업장입니다. 처음에는 examples/node나 examples/vite 한 곳만 고르는 편이 읽기 쉽습니다.

5-2. 코드 규모

수치는 커밋 d93ee3a의 확장자별 물리적 줄 수이며, 공백·주석·테스트도 포함합니다. “외부·복사 영역 제외”는 engine/mysql/vendor/, engine/postgres/vendor/, site/docs-kit/를 뺀 범위이며, 완벽한 저작권별 분류나 순수 구현 줄 수를 뜻하지 않습니다.

이 기준에서 Rust 엔진은 32,668줄, Rust oracle은 3,484줄입니다. SQL 중 oracle 아래 파일은 2,076개·3,473줄이고, oracle/cases/의 바로 아래 사례 폴더는 110개입니다. 이 수치는 테스트 통과 횟수나 실행된 쿼리 수와 다릅니다.

6학습 포인트 (기술별)

6-1. TypeScript: 조건부 타입과 구조적 타이핑

src/index.ts의 Materialize는 행 수라는 문자열 리터럴을 반환 타입으로 바꿉니다. 같은 Row여도 C가 무엇인지에 따라 결과가 달라집니다. 제네릭을 “아무 타입이나 넣는 자리”로만 보지 말고, 입력 정보와 출력 타입의 관계를 보존하는 장치로 읽으세요.

// src/index.ts의 조건부 타입을 줄바꿈해 표시
export type Materialize<Row, C extends Cardinality> =
  C extends "many" ? Row[] :
  C extends "one" ? Row :
  C extends "none" ? void :
  Row | null;

실습 아이디어: Row = { id: number }라고 놓고 네 가지 C의 결과를 종이에 적습니다. 이어 materialize()를 읽고 0·1·2행을 넣었을 때 어떤 값 또는 오류가 나오는지 대응표를 만드세요. 타입 선언만 보고 끝내지 않는 연습입니다.

구조적 타이핑은 src/execute.ts의 PgQueryClient에서 볼 수 있습니다. 특정 드라이버의 클래스 이름 대신 필요한 query() 모양을 요구합니다. 덕분에 풀에서 꺼낸 연결이나 트랜잭션도 같은 계약으로 받을 여지가 생깁니다. 반면 메서드 이름이 겹치는 서로 다른 드라이버를 구별할 추가 조건도 필요합니다.

6-2. Rust: enum·trait·Option으로 프로토콜 모델링

engine/core/src/api.rs의 요청·응답 모델과 engine/core/src/database.rs의 trait를 함께 보세요. “분석이 끝남”, “아직 정보가 필요함”, “오류”가 별개의 상태로 표현됩니다. 임의의 문자열과 빈 객체로 상태를 섞어 표현하는 것보다, 가능한 상태를 열거하는 모델이 호출자의 분기를 명확하게 만듭니다.

실습 아이디어: Host::describe()를 읽고 응답이 없을 때, 정상 응답일 때, DB 오류일 때의 반환값을 적습니다. 이 문맥에서 Option<Result<D, DbError>>는 미응답·성공·DB가 거절한 응답의 세 상태를 표현합니다. None과 Err를 같은 실패로 취급하면 다음 왕복을 설계할 수 없습니다.

6-3. SQL: NULL과 외부 조인의 의미

테이블 열이 NOT NULL이어도 LEFT JOIN의 오른쪽 결과는 NULL일 수 있습니다. 오른쪽에 대응 행이 없을 때 DB가 빈 자리를 만들어 주기 때문입니다. “스키마에 NOT NULL이니 결과도 항상 값이 있다”는 생각을 깨는 데 좋은 예입니다.

-- posts.id가 NOT NULL이어도 LEFT JOIN 뒤의 p.id는 NULL 가능
select u.id as user_id, p.id as post_id
from users u
left join posts p on p.user_id = u.id

실습 아이디어: 게시글이 있는 사용자와 없는 사용자를 각각 하나씩 가정해 결과를 손으로 만듭니다. 이어 where p.id is not null을 더했을 때 결과가 어떻게 달라지는지 설명해 보세요. 데이터 예제와 engine/postgres/src/infer.rs의 규칙을 연결하는 것이 목표입니다.

6-4. 컴파일러 도구: 진단 위치도 제품 기능이다

src/mapper.ts는 positionEncoding: "utf-8"을 선택하고, mapToStatement()로 가상 선언 전체를 원래 SQL 문장에 연결합니다. 여기서는 정의로 이동할 때 SQL 파일을 열도록 하되, 이름 바꾸기가 잘못 TypeScript를 SQL에 써 버리는 기능은 매핑하지 않습니다.

src/module-types.ts의 withinFile()은 진단 범위를 파일의 바이트 길이 안으로 자릅니다. 범위를 벗어나면 컴파일러가 변환 응답 전체를 거절할 수 있기 때문입니다. “오류 메시지를 잘 쓴다”에는 문장뿐 아니라 위치·길이·인코딩의 정확성도 포함됩니다.

실습 아이디어: -- 사용자 조회 같은 한국어 주석 앞뒤의 문자 수와 UTF-8 바이트 수를 비교해 보세요. src/loader.ts의 utf16()은 엔진의 바이트 위치를 JavaScript 문자열 위치로 바꾸는 지점입니다. 한글이 들어가도 오류가 정확한 곳에 표시되는 이유를 설명할 수 있어야 합니다.

6-5. 캐시: 빠른 결과와 현재의 사실은 다를 수 있다

SQL 해시만 저장하면 테이블 변경을 놓칩니다. 스키마 지문만 보면 엔진의 추론 규칙 변경을 놓칠 수 있습니다. reylo는 두 종류의 정보와 서버 구분을 캐시 설계에 넣습니다. 캐시 키를 설계할 때는 결과를 바꿀 수 있는 모든 입력을 먼저 나열해야 한다는 교훈입니다.

실습 아이디어: SQL 수정·엔진 수정·스키마 변경·네트워크 단절의 네 상황을 표로 만듭니다. 각각 캐시 항목을 재사용할지, 재분석할지, 오류가 날지를 Session.#analyze() 분기와 연결하세요. 오프라인에서 성공했다는 사실이 최신 스키마로 검증되었다는 뜻인지는 별도로 적습니다.

6-6. 테스트: 추론한 타입을 실제 값으로 반박해 보기

추론 테스트의 좋은 질문은 “기대한 문자열이 나왔나”에 더해 “이 타입을 깨는 실제 값이 나올 수 있나”입니다. oracle/src/main.rs는 쿼리를 분석한 뒤, 경계값을 넣은 데이터에서 실제로 실행해 결과 값·행 수가 분석과 충돌하는지 검사합니다. 기대 출력 비교와 실행 기반 확인을 결합합니다.

기본 실행 제한 시간은 5,000ms입니다. 모든 시도에서 실패하거나 시간 제한에 걸린 SQL은 검증한 것으로 세지 않고 UNCHECKED로 드러냅니다. --strict-coverage도 “모든 SQL이 반드시 성공”이라는 옵션은 아닙니다. 실행되지 않은 문장이 있는데 사례의 unchecked.txt로 관리되지 않으면 실패시키는 조건이 있습니다.

실습 아이디어: 한 사례의 setup.sql·질의·expected.txt·unchecked.txt를 묶어 읽습니다. 테스트가 있다고 말하는 것보다, 어떤 입력에서 무엇을 관찰했고 무엇은 관찰하지 못했는지 설명하는 연습이 중요합니다.

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

README와 빌드 설정에는 최소 CPU 코어 수·RAM 수치가 명시되어 있지 않습니다. 아래 표는 명시된 소프트웨어 조건과 작업별 추가 준비 사항을 정리한 것입니다. 모델 학습이나 GPU 추론을 하는 도구가 아니므로 이 기능을 위해 별도 GPU를 요구하는 구성은 없습니다.

위 지원 버전은 README와 DB별 문서 기준이며, CI의 실행 환경은 .github/workflows/test.yml 기준입니다. 지원 범위와 CI에서 사용하는 버전은 서로 다르므로 이용할 DB·드라이버 조합을 함께 살펴보세요.

7-1. 노트북에서 시작한다면

먼저 작은 SQLite·TypeScript 예제로 시작하고, 엔진 개발 단계에서 DB 서버와 Rust 빌드 도구를 추가하세요. 메모리와 CPU 부담은 DB 데이터 크기, 함께 실행하는 프로세스, 빌드 병렬도에 따라 달라집니다.

엔진 개발은 npm 패키지 이용보다 준비 비용이 큽니다. engine/build.sh --prepare는 SQLite 소스와 패치할 파서 소스를 준비하고, Cargo 워크스페이스는 준비된 경로를 참조합니다. 일반 이용자는 커밋된 WASM 산출물을 받으므로 이 C·Rust 빌드 과정을 반복하지 않습니다.

7-2. 바이너리 크기는 메모리 사용량과 다르다

압축된 npm 다운로드 크기나 실행 중 최대 메모리는 따로 측정해야 합니다. engine/build.sh의 -zstack-size=8388608은 WASM의 스택 영역 설정인 8MiB를 가리킵니다. Node·WASM 메모리·파서·캐시·DB를 합친 전체 RAM이 8MiB라는 뜻이 아닙니다.

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

다음 다섯 과제는 읽기에서 실행으로 이어지는 학습안입니다. 실행 과제에는 학습용 프로젝트와 폐기 가능한 DB를 준비하세요. 앞의 두 과제는 소스와 설정 파일을 읽는 것만으로 시작할 수 있습니다.

8-1. 실행 과제를 준비할 때 확인할 설정 예시

아래는 README와 Node 예제에서 가져온 핵심 형태입니다. 이미 TypeScript 프로젝트와 드라이버를 준비했다는 전제이며, 이 블록만 복사하면 프로젝트 전체가 설정되는 것은 아닙니다. 이용할 릴리스의 reylo와 엔진 패키지는 같은 버전으로 맞추고 해당 버전의 문서를 확인하세요.

// tsconfig.json의 최상위 항목에 추가하는 형태
{
  "contentMappers": [
    {
      "package": "reylo",
      "extensions": [".sql", ".reylo.yaml", ".reylo.yml"]
    }
  ]
}

# 환경변수 또는 .env가 학습용 DB를 가리키도록 준비한 뒤 사용
# 타입 검사 시 Reylo는 환경변수 → .env.local → .env 순서로 값을 찾음
npx tsc --noEmit --runExternalCode

# Node 실행은 .env를 읽고 SQL 등록 훅을 불러오는 예시
node --env-file=.env --import reylo/register main.ts

타입 검사 시 Reylo는 src/project.ts에서 연결 설정을 읽습니다. 연결 URL은 .reylo.yaml의 direct_url이 우선이며, 없으면 DATABASE_URL을 사용합니다. 환경변수의 기본 조회 순서는 프로세스 환경변수 → .env.local → .env이며, 설정의 env로 파일 목록을 바꿀 수 있습니다. 반면 위 Node 명령의 --env-file=.env는 애플리케이션의 process.env에 값을 넣습니다. Reylo의 파일 조회가 애플리케이션 환경변수까지 설정해 주는 것은 아닙니다.

-- A: 여러 행 가능
select id, name, email from users;

-- B: 최대 한 행
select id, name, email from users where id = :id::int;

-- C: 행 수는 여러 행 가능, email의 NULL은 제거
select id, name, email from users where email is not null;

-- D: GROUP BY 없는 count, int로 변환해 number 예시로 통일
select count(*)::int as total from users;

-- oracle/cases/derived_tables/schema_qualified.sql
select s.id, s.score from (select id, score from public.bar) s

-- oracle/cases/derived_tables/with_schema_qualified.sql
with b as (select id, score from public.bar) select id, score from b

이 회귀 사례의 파일은 고정 커밋의 derived_tables 사례 모음에서 함께 볼 수 있습니다. 두 질의가 보존해야 할 타입과 NULL 가능성은 해당 사례의 입력·기대값에 명시되어 있습니다.

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

하루에 모든 파일을 읽는 방식보다, 같은 예제를 여러 관점에서 다시 보는 편이 좋습니다. 아래는 SQL 기본 문법과 TypeScript 함수 호출을 아는 초보자를 가정한 학습안입니다. 주차는 일정의 예시이며 실제 소요 시간은 선행 지식에 따라 달라집니다.

9-1. 중간에 막혔을 때 돌아갈 기초

• NULL이 어렵다면: 외부 조인 전에 테이블 두 개의 실제 행을 그리고, 대응하지 않는 행을 손으로 채워 봅니다.
• 제네릭이 어렵다면: Materialize의 타입 변수에 구체적인 값을 대입해 삼항 조건을 한 단계씩 지웁니다.
• Rust 수명이 어렵다면: 우선 Host가 답 목록을 소유하는지 빌리는지만 표시하고 전체 문법 해석은 뒤로 미룹니다.
• 파서 코드가 어렵다면: 작은 SQL 하나를 고르고 infer::plan()과 resolve() 사이에 어떤 정보가 전달되는지 찾습니다.
• 통합 테스트가 어렵다면: DB를 띄우기 전에 setup.sql·쿼리·기대값 세 파일부터 읽습니다.

공부의 완료 기준은 파일을 전부 읽는 것이 아니라, SQL 한 줄의 변화가 타입과 실행값에 미치는 영향을 근거와 함께 설명하는 것입니다. 각 주의 결과물에 추측과 확인된 사실을 따로 표시하면, 이후 다른 라이브러리를 분석할 때도 재사용할 수 있습니다.

9-2. 그다음 확장해 볼 방향

컴파일러 도구에 관심이 생겼다면 콘텐츠 매퍼의 원본·가상 위치 매핑을 더 공부하세요. 데이터 엔지니어링 쪽이라면 NULL과 키 제약이 분석에 주는 정보를 파고들 수 있습니다. 시스템 설계가 재미있다면 Need·Answer 왕복 프로토콜과 캐시 키 설계를 작은 다른 문제에 적용해 보세요.

예를 들어 로컬 설정 파일 검사기를 만들 때도 “순수한 검사 규칙”과 “파일을 읽는 호스트”를 나누고, 파일 내용의 지문을 캐시에 넣을 수 있습니다. 이때 목표는 reylo를 복제하는 것이 아니라, 어떤 입력이 결과를 결정하는지 드러내는 설계 습관을 가져가는 것입니다.

10핵심 키워드 사전

용어를 외우기보다 하나씩 파일에 연결해 보세요. “지문은 engine/core/src/fingerprint.rs와 Session에서 서로 다른 대상을 다룬다”, “카디널리티는 Rust 분석과 Materialize 양쪽에 나온다”처럼 사용되는 경계까지 기억하면 코드 탐색이 빨라집니다.

11참고 링크

11-1. 먼저 열어 볼 공식 자료

• 공식 저장소 — 현재 개발 상태를 볼 때 사용합니다.
• 분석에 사용한 고정 커밋 — 이 글과 같은 소스를 읽을 때 사용합니다.
• 분석 커밋의 README — 설치·사용 흐름의 근거입니다.
• reylo 공식 문서 — 이후 버전에서는 이 글과 설명이 달라질 수 있습니다.
• v0.3.0 릴리스 — 2026-10-23 GitHub 기준 최신 릴리스이며, 공개일은 2026-10-22입니다.
• TrendShift — 2026-10-23 Daily #21 선정 근거입니다.

11-2. 분석 경로를 재확인할 소스

• src/mapper.ts — 매퍼 프로토콜과 가상 선언 생성.
• src/analyze.ts — 분석 세션·캐시·오프라인 분기.
• engine/core/src/database.rs — DB별 엔진의 공통 계약.
• engine/postgres/src/postgres.rs — 서버 메타데이터·타입·행 수 분석의 조립.
• engine/postgres/src/infer.rs — 표현식과 NULL 가능성의 추론 규칙.
• oracle/src/main.rs — 실제 실행으로 추론의 모순을 찾는 도구.
• .github/workflows/test.yml — 테스트 환경과 세 작업의 정의.
• FAQ 원문 — 캐시 구현과 어긋나는 설명을 함께 비교할 근거.

11-3. 관련 기술의 원리 더 읽기

• TypeScript 콘텐츠 매퍼 공식 제안 — 프로토콜·가상 변환·실행 옵션.
• TypeScript 조건부 타입 — 카디널리티를 반환 타입으로 바꾸는 문법.
• Rust Book의 trait — DB별 구현의 공통 계약을 읽기 위한 기초.
• Node.js WASI 문서 — 분석 엔진을 호스팅하는 런타임 인터페이스.
• PostgreSQL 프로토콜 흐름 — Parse·Describe·실제 실행의 구분.
• Prisma TypedSQL 공식 문서 — SQL에서 생성한 타입 있는 함수를 사용하는 비교 흐름.
• sqlc 생성 명령 공식 문서 — 생성형 접근과 DB 기반 분석 옵션의 비교 근거.

외부 자료는 각 기술의 원리를 더 읽기 위한 링크입니다. reylo의 동작·설정값은 커밋 d93ee3a의 소스 기준입니다. 경쟁 도구 비교와 콘텐츠 매퍼 규약의 출처는 위 공식 페이지이며, 비교 범위는 타입 갱신 흐름입니다.

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

최신 릴리스의 버전, 소스의 패키지 버전, 설명의 기준 커밋을 구분해야 나중에도 같은 설명을 검증할 수 있습니다. 본문의 동작 설명은 패키지 버전 0.4.0을 선언한 커밋 d93ee3a 기준이며, v0.3.0 릴리스와 구분해야 합니다.