clickhouse.build는 기존 Postgres 기반 TypeScript 애플리케이션에서 분석 워크로드를 ClickHouse로 옮겨 결합 Postgres+ClickHouse 아키텍처를 빠르게 시도해 볼 수 있게 해주는 오픈 소스 에이전틱 CLI이다.
clickhouse.build는 기존 Postgres 기반 TypeScript 애플리케이션에 ClickHouse를 도입하는 과정을 가속해 주는 오픈 소스 에이전틱 CLI입니다. 목표는 Postgres를 대체하는 것이 아니라, 동일한 애플리케이션 안에서 분석 워크로드에 대해 ClickHouse를 자연스럽게 결합해 두 데이터베이스의 강점을 함께 활용하는 것입니다.
이 도구는 다음과 같은 멀티‑에이전트 워크플로를 사용합니다.
clickhouse.build는 가속기를 목표로 설계되었으며, 1시간 이내에 동작하는 PoC(Proof of Concept, 개념 증명)를 만들어 볼 수 있도록 돕습니다. 이 PoC를 사용해 Postgres+ClickHouse를 결합한 백엔드를 사용할 때 애플리케이션이 어떻게 동작하는지 평가할 수 있습니다.
이미 Postgres + ClickHouse를 검토 중이라면 어떻게 동작하는지 보기로 바로 넘어가셔도 되고, 두 데이터베이스가 왜 그렇게 잘 어울리는지부터 계속 읽어보셔도 좋습니다.
ClickHouse Cloud 무료 체험을 통해 지금 바로 clickhouse.build를 사용해 보세요. 1시간 이내에 동작하는 PoC를 만들 수 있습니다.
clickhouse.build 작업은 AWS Prototyping and Cloud Engineering(PACE) 팀과의 파트너십으로 시작되었으며, Amazon Bedrock과 Strands Agents SDK를 사용합니다. 이 협업에 함께해 준 파트너들에게 감사드립니다.
Postgres와 ClickHouse는 각자의 카테고리에서 가장 인기 있는 오픈 소스 데이터베이스로, 거대한 커뮤니티 채택과 풍부한 생태계를 가지고 있습니다. 이런 채택 덕분에 두 데이터베이스는 무적의 듀오가 되었고, 에이전틱 AI는 이러한 트렌드를 더욱 가속하고 있습니다.
ClickHouse는 Postgres를 대체하지 않습니다. 대신 두 데이터베이스는 각자에 가장 적합한 워크로드를 처리하는 역할을 나누어 수행합니다. 트랜잭션 워크로드는 Postgres로, 분석 워크로드는 ClickHouse로 보내는 식입니다.
많은 애플리케이션 백엔드는 쿼리 종류와 관계없이 모든 쿼리를 Postgres로 보냅니다. 예를 들어, ID로 단일 행을 SELECT * 하는 경우도 있고, 100,000개 행에 대해 SUM() … GROUP BY를 수행하는 경우도 있죠. 전자는 Postgres가 빛을 발하는 영역이고, 후자는 ClickHouse에서 100~1000배 더 빠를 수 있는 영역입니다.
Postgres + ClickHouse 조합에서는 애플리케이션 백엔드가 작업에 가장 적합한 데이터베이스로 쿼리를 보낼 수 있습니다. Postgres를 과도하게 키우거나 복제를 두고 씨름할 필요 없이, 사용자에게 노출되는 성능과 경험을 개선할 수 있습니다. 다만 새로운 아키텍처를 프로토타입하는 데는 몇 주가 걸릴 수 있는데, 특히 ClickHouse를 처음 사용하는 경우라면 마이그레이션할 적절한 쿼리를 식별하고, 데이터 동기화를 설정하고, 백엔드 통합을 업데이트하는 데 시간이 필요합니다. 바로 이 프로토타입을 만드는 작업을 clickhouse.build가 도와줍니다.
clickhouse.build CLI는 여러 개의 작업 특화 에이전트를 사용해 Postgres 기반 TypeScript 애플리케이션을 Postgres+ClickHouse 아키텍처로 마이그레이션합니다. 이 에이전트들은 독립적으로 사용할 수도 있고, 올인원(all‑in‑one) 워크플로를 통해 호출할 수도 있습니다. 고품질 레퍼런스 예제가 보강된 품질 보증(QA) 서브 에이전트가 모든 코드 변경 제안을 검사합니다.
주요 에이전트는 세 가지입니다.
스캐너 에이전트는 TypeScript 코드베이스를 스캔해 Postgres 쿼리를 찾습니다. 현재는 코드 안에 직접 작성된 Postgres 드라이버 기반 쿼리뿐 아니라 Prisma, Drizzle ORM의 쿼리 빌더를 사용하는 경우에도 동작합니다.
쿼리를 찾으면, 해당 쿼리가 Postgres에 더 적합한지 ClickHouse에 더 적합한지 판별합니다. 일반적으로 단일 행 조회나 insert/update/delete 작업은 Postgres에, COUNT, SUM, GROUP BY 같은 연산은 ClickHouse에 더 적합합니다. 스캐너 에이전트는 ClickHouse로 마이그레이션해야 할 쿼리를 구조화된 출력 보고서 형태로 생성합니다.
올인원 워크플로 밖에서 단독으로 호출한 스캐너 에이전트 데모
데이터 마이그레이터 에이전트는 필요한 Postgres 테이블을 ClickHouse와 동기화하는 작업을 돕습니다. 스캐너 에이전트가 식별한 쿼리를 기반으로, ClickHouse가 해당 쿼리를 처리하는 데 필요한 테이블을 판별합니다. 그런 다음 ClickPipes Postgres CDC 커넥터를 설정하기 위한 관련 ClickPipes API 페이로드를 생성합니다. 이 커넥터는 먼저 모든 과거 데이터를 백필(backfill)한 뒤, Postgres에서 ClickHouse로 변경 사항을 지속적이고 실시간으로 전송해 ClickHouse를 Postgres와 동기 상태로 유지합니다.
올인원 워크플로 밖에서 단독으로 호출한 데이터 마이그레이터 에이전트 데모
코드 마이그레이터 에이전트는 쿼리와 코드를 업데이트하는 작업을 담당합니다. ClickHouse에서 올바르게 동작하도록 SQL 문법을 조정할 수 있으며(일반적으로 Postgres와 ClickHouse 간 쿼리는 변경 없이 호환되지만, 특히 ORM 쿼리 빌더를 사용할 경우 항상 그런 것은 아닙니다), TypeScript 코드가 공식 ClickHouse JS 클라이언트를 통해 ClickHouse를 호출하도록 업데이트합니다. 이 에이전트는 각 주요 단계 후 마이그레이션을 잠시 멈추고, 제안된 변경 사항을 수락할지 거부할지 사용자 입력을 요청합니다. 한 번의 명령으로 모든 변경 사항을 한꺼번에 수락할 수도 있습니다.
코드 마이그레이터는 기존에 잘 동작하던 Postgres 쿼리를 제거하는 대신, 하위 호환성을 유지하는 간접 호출 패턴을 사용합니다. 각 데이터베이스용 쿼리를 별도의 유틸리티 파일로 옮긴 뒤, 기능 플래그를 사용해 런타임에 사용할 백엔드를 선택할 수 있게 합니다. 이를 통해 두 모드를 손쉽게 전환하며 성능과 정확성을 비교해 볼 수 있습니다.
QA 에이전트는 코드 마이그레이터의 서브 에이전트로, 수행된 변경 사항을 검증합니다. 코드 마이그레이터가 수행하려는 작업을 제안하면, QA 에이전트는 해당 변경이 적절한지 확인합니다. QA 에이전트는 변경 사항을 스캔하고, 이미 Postgres+ClickHouse를 성공적으로 사용 중인 일련의 레퍼런스 코드베이스 패턴과 비교하는 체크 및 검증을 수행합니다.
올인원 워크플로 밖에서 단독으로 호출한 코드 마이그레이터 에이전트 데모
각 에이전트는 개별적으로 사용할 수 있지만, CLI에는 각 에이전트를 올바른 순서(스캐너 → 데이터 마이그레이터 → 코드 마이그레이터)로 호출하는 올인원 워크플로가 있습니다. PoC 용도로 CLI를 사용할 때는 일반적으로 이 방식이 권장되지만, 원하신다면 직접 에이전트를 호출하셔도 됩니다.
CLI는 clickhouse.build GitHub 저장소에서 받을 수 있습니다. README에는 CLI 설정 및 구성에 대한 자세한 안내가 포함되어 있습니다.
CLI 구성이 끝나면, 애플리케이션 저장소에서 작업용 새 브랜치를 만드는 것을 권장합니다. 그런 후 올인원 마이그레이션 워크플로를 실행할 수 있습니다.
bashuv run main.py migrate /path/to/your/repo --replication-mode cdc
이 명령은 스캐너 → 데이터 마이그레이터 → 코드 마이그레이터 순서로 모든 에이전트를 차례로 실행합니다. 에이전트는 기본적으로 완전히 자율적으로 동작하지는 않습니다. 진행 과정에서 CLI가 변경 사항을 검토하고 수락/거부하도록 계속 질문하지만, 원한다면 "모두 수락"을 선택할 수도 있습니다.
스캐너 에이전트는 코드를 살펴보며 Postgres 쿼리를 찾아내고, 쿼리와 설명, 파일 위치가 포함된 구조화된 JSON 파일을 출력합니다. 데이터 마이그레이터 에이전트는 이 스캔 파일을 읽어 ClickHouse로 복제해야 할 테이블 이름을 추출합니다. --replication-mode cdc 옵션이 설정된 상태에서, 데이터 마이그레이터 에이전트는 ClickPipes Postgres CDC를 설정하는 데 필요한 curl 명령을 ClickHouse Cloud API를 통해 생성합니다.
현재 ClickPipes 구성 명령에는 일부 수동 입력이 필요합니다. 명령과 함께 출력되는 환경 변수에는 ClickHouse Cloud 계정과 Postgres 인스턴스에 대한 세부 정보를 채워 넣어야 합니다. 이 정보를 채운 후, curl 명령은 직접 실행해야 합니다.
ClickPipes 구성 명령을 실행하고 ClickHouse Cloud에서 실행 중인 ClickPipes 서비스를 검증하는 데모
코드 마이그레이터 에이전트는 워크플로의 마지막 단계입니다. 이 에이전트는 먼저 스캔 파일을 로드하고, 프로젝트의 패키지 매니저를 사용해 clickhouse.js 드라이버를 설치합니다. 그런 다음 컨텍스트에 Postgres+ClickHouse 구현 레퍼런스 예시를 일부 로드한 뒤, 코드베이스를 분석해 어떤 부분을 변경할지 계획을 세우기 시작합니다.
에이전트는 구체적인 백엔드 구현을 추상화하는 ‘전략 패턴(strategy pattern)’을 구현하는 것을 목표로 합니다. 이 패턴을 사용하면 단순한 기능 플래그로 기존 Postgres 백엔드와 새 ClickHouse+Postgres 백엔드 사이를 전환할 수 있습니다. lib/strategies 아래에 Postgres와 ClickHouse용 파일이 각각 생성되며, 각 파일에는 해당 데이터베이스를 통해 쿼리를 처리하는 로직이 포함됩니다. 에이전트는 이를 프로젝트에 통합하는 올바른 방식을 찾으려고 시도하는데, 이 때문에 다음 단계는 프로젝트마다 조금씩 다를 수 있습니다. 일반적인 패턴은 lib/db.ts에 데이터베이스 구성을 생성해 전략 간 토글 로직을 구현하고, 기존 라우트를 db.ts에서 설정한 백엔드를 사용하도록 업데이트하는 방식입니다.
각 단계마다(또는 "모두 수락"을 선택하지 않은 경우에) 변경 사항을 검토하도록 요청받게 되며, QA 서브 에이전트는 레퍼런스 예시와 비교해 기본적인 품질 기준을 만족하는지 자동으로 검토합니다.
워크플로는 프로젝트가 빌드되는지 확인하고, 수행된 변경 사항 요약과 기능 플래그를 사용해 전략을 전환하는 방법에 대한 안내를 제공하며 마무리됩니다. 이제 애플리케이션에서 ClickHouse를 사용했을 때의 영향을 평가할 수 있습니다.
애플리케이션을 평소처럼 실행하면 기본적으로 기존 Postgres 구현을 계속 사용합니다. 새 ClickHouse 구현을 사용하려면 새 환경 변수에 기능 플래그를 추가하면 됩니다: USE_CLICKHOUSE=true. 이 플래그를 false로 전환하면 다시 되돌릴 수 있습니다.
Postgres와 ClickHouse 백엔드 사이를 전환하면서 3배 성능 향상을 보여주는 애플리케이션 데모
일반적인 애플리케이션 플로를 테스트하는 동시에, Postgres에 새 행을 삽입해 복제를 검증하고, ClickHouse 기능 플래그를 켜고 끈 상태에서 기능별 성능을 비교해 볼 것을 권장합니다.
많은 경우 차이는 즉시 눈에 띌 정도입니다. 통계, 차트, 분석 결과를 보여주는 테이블이 체감 가능한 지연 없이 몇 배 더 빠르게 로드되는 것을 확인할 수 있을 것입니다. 물론 로깅을 넣어 실제 숫자를 보는 것이 더 재미있을 수도 있습니다!
보게 될 성능 변화는 상황에 따라 다를 수 있지만, 일반적으로 데이터가 클수록 성능 향상 폭은 더 커집니다.
clickhouse.build는 강한 의견을 가진(highly opinionated) 구현입니다. 설계는 데이터 웨어하우징, SRE용 에이전트, 에이전틱 애널리틱스를 위한 에이전트를 구축하며 얻은 교훈에 기반하고 있습니다.
우리는 최고의 에이전틱 플로우는 항상 사람을 루프 안에 두는 것이라고 믿습니다. 단지 상황을 알려주는 것에 그치지 않고, 에이전트가 수행하는 작업에 사람이 관여하게 하는 것입니다. 또한 하위 호환성은 우리가 변경의 정확성을 검증하고 실제 영향도를 평가할 수 있게 해 줍니다.
에이전틱 워크플로는 아직 새로운 분야이며, 우리의 이해도는 여전히 진화하는 중입니다. 프로덕션 환경의 변경은 항상 신중히 접근해야 하지만, 에이전트는 개발과 PoC 단계에서 분명한 가속기 역할을 합니다.
에이전트는 특정 컨텍스트와 지시를 제공함으로써 서로 다른 작업에 맞게 튜닝할 수 있습니다. 이는 곧 변경을 가하는 데 최적화된 에이전트와, 그 변경을 검증하는 데 최적화된 또 다른 에이전트를 동시에 가질 수 있다는 의미입니다. 우리는 이것이 오류 감소에 효과적일 수 있다는 것을 확인했지만, 항상 완벽한 것은 아닙니다. 그래서 사람을 계속 곁에 두는 것이죠.
평가는 오늘날 에이전틱 워크플로에서 가장 영향력이 크면서도 아직 충분히 탐구되지 않은 영역일 수 있습니다. 80% 수준의 품질에 도달하는 것은 비교적 쉽게 달성할 수 있지만, 그 이상을 넘어서려면 상당한 노력이 필요합니다. 우리는 이 지점에서 평가가 매우 중요해진다고 생각합니다. 평가를 통해 지속적으로 검토하고, 측정하고, 개선할 수 있기 때문입니다. 하지만 평가는 수행하기 어렵고, 쉽게 잊어버리기 쉬운 작업이기도 합니다. 이를 완화하기 위해, 우리는 워크플로 자체에 평가를 녹여 넣고, 이 영역이 발전함에 따라 새로운 기법과 도구를 적극적으로 채택하려고 합니다.
오픈 소스가 앞으로 나아갈 길입니다. clickhouse.build 뒤에 비밀 소스 같은 것은 없습니다. 대부분의 회사가 어떤 블랙박스 API를 통해 제공되는 독점 에이전트를 만드는 것과 달리, 우리는 개방형 클라이언트 사이드 애플리케이션을 만들기로 했고, 이를 무료로 사용하고 자유롭게 수정할 수 있게 했습니다. 새로운 LLM API를 쓰고 싶나요? 새로운 데이터베이스를 지원하고 싶나요? 기여해 주신다면 정말 기쁠 것입니다!
ClickHouse로 Postgres를 가속하는 것은 clickhouse.build의 시작에 불과합니다. 고성능 애플리케이션의 기본 데이터 스택으로 Postgres+ClickHouse 조합이 사실상의 표준이 되었기 때문에 Postgres를 먼저 선택했습니다. 하지만 MySQL이나 MongoDB 같은 다른 트랜잭션 데이터베이스도 마찬가지 이점을 누릴 수 있으며, 자연스러운 다음 단계입니다.
마찬가지로, TypeScript 애플리케이션을 넘어 지원 범위를 확장할 계획입니다. 다음 후보로는 Python, Go, Rust, Ruby 등이 유력합니다.
또한 이 모델은 애플리케이션 개발자뿐만 아니라 데이터 및 애널리틱스 엔지니어에게도 도움이 될 수 있다고 보고 있습니다. ClickHouse는 클라우드 데이터 웨어하우스의 비용을 줄이고 워크로드를 가속하는 데 기여할 수 있기 때문입니다.
clickhouse.build는 오픈 소스로, 누구나 기여할 수 있습니다. 피드백, 제안, 코멘트 모두 환영합니다. 커뮤니티 Slack에서 여러분을 만나고 싶습니다.
ClickHouse Cloud 무료 체험을 통해 지금 바로 clickhouse.build를 사용해 보세요. 1시간 이내에 동작하는 PoC를 만들 수 있습니다.
