AXHub
⌘K

커넥터로 회사 데이터 연결하기

회사가 이미 쓰는 데이터베이스를 앱에서 조회하는 방법이에요. 승인받은 범위만, 안전한 쿼리로 가져와요.

회사에서 쓰는 데이터베이스를 앱에 안전하게 잇는 통로가 커넥터예요.
승인만 받아 두면 앱 코드에서 바로 조회할 수 있어요 — 접속 정보는 AxHub가 맡아서, 코드에는 회사 DB 비밀번호가 전혀 남지 않아요.

준비물

  • 승인받은 커넥터 — 회사 관리자가 연결을 등록하고 내 계정에 접근을 승인(grant)해 둬야 해요. 아직 없다면 관리자에게 요청하세요 (커넥터 등록하고 승인하기)
  • SDK — SDK 설치하기를 먼저 보세요

내가 쓸 수 있는 커넥터 확인

승인이 됐는지, 어떤 이름으로 부르면 되는지 먼저 봐요.

axhub connectors mine                      # 내가 조회할 수 있는 커넥터
axhub connectors resources <connector_id>  # 그 커넥터의 리소스 트리

목록이 비어 있으면 아직 승인이 안 된 거예요 — grant 없는 커넥터는 목록에조차 나오지 않아요.

앱에서 조회하기

값은 반드시 params로 넘기세요. SQL 문자열에 사용자 입력을 직접 붙이면 값에 명령을 섞어 넣는 공격에 열려요.

PostgreSQL 커넥터는 자리표시자로 $1 · $2를 써요 — ?를 쓰면 백엔드에서 500이 나요. 테이블 이름에는 public. 같은 스키마도 함께 적어요.

템플릿으로 만든 앱이라면

Next.js · Astro 템플릿에는 조회 헬퍼가 이미 들어 있어요. 커넥터 이름만 알면 돼요.

import { queryConnector } from '@/lib/axhub-server';

const { rows } = await queryConnector<{ id: number; name: string }>({
  connector: 'my-db',   // 커넥터 이름 — UUID 아니에요
  sql: 'SELECT id, name FROM public.employees WHERE active = $1 LIMIT $2',
  params: [true, 100],
});

이 한 번의 호출이 커넥터 찾기 → 세션 열기 → 조회 → 세션 닫기를 다 해요. 권한이 없으면 PermissionDeniedError(403), 세션이 만료됐으면 UnauthenticatedError(401)로 던져져요.

직접 조회하기

헬퍼를 안 쓴다면 세 단계를 직접 밟아요. 게이트웨이 세션은 "이 연결로 잠깐 조회하겠다"고 여는 임시 통로예요 — 8시간이 지나면 자동으로 닫혀요.

const gw = sdk.tenant(tenantId).gateway;   // ← 회사 UUID (슬러그 아님)

const session = await gw.sessions.create({ connectorId: 'con_1' });
try {
  const { rows } = await gw.query.run({
    sessionId: session.id,
    sql: 'SELECT id, name FROM public.employees WHERE active = $1 LIMIT $2',
    params: [true, 10],
  });
} finally {
  await gw.sessions.end(session.id);
}

게이트웨이는 회사를 UUID로만 받아요 — 슬러그를 넣으면 400 invalid_format이 나요. UUID는 sdk.identity.me()의 tenants에서 찾아요.

내가 접근 가능한 커넥터 · 리소스는 gw.me.connectors() · gw.me.connectorResources(connectorId)로 확인해요.

터미널에서는 같은 일을 이렇게 해요.

axhub gateway session start --connector-id <connector_id>
axhub gateway query --session-id <session_id> \
  --sql 'SELECT id, name FROM public.employees LIMIT 10' --execute
axhub gateway session end <session_id>

DB 말고 REST API · 문서 저장소 · Google Drive에 연결한 커넥터는 axhub gateway invoke · document-invoke · file-invoke로 불러요.

막혔을 때

상황무슨 뜻인가요
axhub connectors mine이 비어 있어요아직 grant가 없어요 — 관리자에게 승인을 요청하세요
403 scope_requires_target테이블 범위가 지정된 grant예요. 자유 SQL 대신 승인된 리소스를 지정해 조회하세요
403 scope_out_of_range승인 범위 밖의 리소스예요
403 PermissionDeniedErrorpreset이 허용하지 않는 액션이에요. 기본 읽기 전용 preset은 SELECT · WITH · EXPLAIN만 통과시켜요
400 invalid_format회사를 슬러그로 넘겼어요 — UUID여야 해요

모든 조회는 허용 · 거부 여부와 함께 감사 기록으로 남아요.

이렇게 보이면 성공

axhub connectors mine에 커넥터가 보이고, 쿼리 결과로 행(rows)이 돌아오면 성공이에요.

다음은 배포 관리에서 배포 상태 · 로그 · 되돌리기를 다뤄요.