Glancer — 자연어로 Rails 데이터베이스에 질문하기

RAG와 LLM을 사용하여 자연어로 데이터베이스를 쿼리할 수 있게 해주는 Rails 엔진입니다. 코드를 작성할 필요가 없습니다.

모든 Rails 프로젝트는 팀원 중 누군가(제품, 지원, 관리 부서)가 데이터가 필요하지만, 아무도 그들을 위해 빠른 쿼리를 작성할 시간이 없는 지점에 도달합니다. 어떤 상황인지 잘 아실 겁니다. Slack 메시지, "지난주에 가입한 사용자가 몇 명인가요?"라는 제목의 GitHub 이슈, 또는 누군가의 백로그에 쌓여버리는 CSV 요청 같은 것들 말이죠.

그래서 저는 Glancer를 생각했습니다.

Glancer란 무엇인가

Glancer는 앱 내부의 /glancer 경로에 전체 채팅 인터페이스를 마운트하는 Ruby on Rails 엔진입니다. 사용자가 자연어로 질문을 입력하면, 관련 스키마 컨텍스트 (schema context)를 검색하고, SELECT 쿼리(또는 ActiveRecord 표현식)를 생성하며, 이를 안전하게 검증 및 실행한 뒤, 사람이 읽을 수 있는 설명과 함께 결과를 반환합니다.

"지난 30일 동안 상태별로 주문이 몇 건 발생했나요?"
→ SELECT 실행, 결과 표시, 자연어로 답변 작성.

이 프로젝트는 Blazer에서 영감을 받았지만, 직접 SQL을 작성하는 대신 질문만 하면 됩니다.

시작하기

Gemfile에 다음을 추가하세요:

gem "glancer"

제너레이터(generator)를 실행하세요:

rails generate glancer:install
rails db:migrate
rails glancer:index:all

그 다음 /glancer를 방문하여 질문을 시작하세요.

제너레이터는 LLM 제공자(provider)를 설정할 수 있는 초기화 파일(initializer)을 생성합니다. Gemini를 사용한 최소한의 설정은 다음과 같습니다:

Glancer.configure do |config|
  config.llm_provider   = :gemini
  config.llm_model      = "gemini-2.0-flash"
...

OpenAI와 OpenRouter도 지원됩니다. RubyLLM 위에서 동작하므로, RubyLLM이 지원하는 모든 모델을 여기서 사용할 수 있습니다. 역할(role)별로 서로 다른 모델을 할당할 수 있습니다. 예를 들어, 쿼리 생성(query generation)에는 더 똑똑한 모델을, 응답 작성에는 더 저렴한 모델을 사용할 수 있습니다.

주요 기능

알아두면 좋은 몇 가지 기능은 다음과 같습니다:

안전성은 선택 사항이 아닙니다. 모든 쿼리는 항상 롤백(rollback)되는 트랜잭션(transaction) 내부에서 실행됩니다. 키워드 블랙리스트(keyword blocklist)가 DELETE, UPDATE, INSERT, DROP 및 유사한 명령어를 실행기에 닿기도 전에 거부합니다. 또한 읽기 전용 복제본(read-only replica)을 대상으로 지정할 수도 있습니다.

추가 인프라가 필요 없습니다. 임베딩(Embeddings)은 기존 데이터베이스의 JSON 컬럼에 저장됩니다. Pinecone이나 Weaviate 같은 별도의 설정이 필요하지 않습니다.

도메인을 이해합니다. config/glancer/llm_context.glancer.md 경로에 마크다운(Markdown) 파일을 두어 Glancer에게 비즈니스 규칙을 가르칠 수 있습니다. 예를 들어 status 값의 의미, 매출 계산 방식, 무시해야 할 컬럼 등을 지정할 수 있습니다:

- `orders.status` 값: "pending" | "paid" | "shipped" | "refunded"
- 월간 매출 = SUM(orders.total) WHERE status = "paid"
- "churn"에 대해 질문하면 `subscriptions` 테이블의 `churned_at` 컬럼을 사용하세요

UI에 세심한 배려가 담겨 있습니다. 결과는 테이블 형태로 렌더링되며 클릭 한 번으로 CSV 내보내기가 가능합니다. 차트(Charts)는 적절한 경우 자동으로 생성됩니다. 쿼리는 백그라운드 스레드(background thread)에서 실행되므로 메인 앱 스레드는 자유로운 상태를 유지합니다. @테이블_이름을 입력하여 특정 테이블을 질문에 고정할 수 있고, 생성된 SQL을 인라인(inline)으로 편집하여 다시 실행하거나, 마이크로 질문을 받아쓰기할 수도 있습니다. 또한 /glancer/db-schema에서 스키마 뷰어(schema viewer)를 확인할 수 있습니다.

Blazer 통합. 이미 Blazer가 설치되어 있다면, Glancer에서 생성된 SQL을 Blazer에서 직접 열 수 있는 버튼을 보여줍니다.

탄생 배경

이 프로젝트는 개인적인 연구 프로젝트로 시작되었습니다. 저는 이전에 gem을 한 번도 배포해 본 적이 없었기에, 엔진 내부 구조부터 gemspec, CI(지속적 통합)에 이르기까지 전체 프로세스를 이해하고 싶었습니다. 몇몇 동료들과 공유했는데 그들이 실제로 유용하다고 판단하여, 커뮤니티를 위해 공개하기로 결정했습니다.

현재 버전은 1.0.0입니다.

직접 사용해 보신다면, 코드나 아이디어 자체에 대해 여러분이 어떻게 생각하시는지 꼭 듣고 싶습니다. 이슈 (Issues)와 풀 리퀘스트 (Pull requests)는 열려 있습니다.

만약 이 도구가 유용하다고 느끼신다면, 레포지토리 (repo)에 스타 (star)를 눌러주세요. 더 많은 사람들이 이 프로젝트를 발견하는 데 큰 도움이 됩니다.

GitHub: https://github.com/ErnaneJ/glancer
RubyGems: https://rubygems.org/gems/glancer