📘 DataGate — 안전한 AI 대응 데이터 게이트웨이

DataGate는 정책 기반으로 작동하는 헤드리스(headless)형 안전한 게이트웨이로, GitHub Copilot과 같은 AI 도구에 데이터베이스를 통제되고 예측 가능한 방식으로 노출하며 자유로운 SQL을 허용하지 않습니다.

DataGate는 LLM과 실제 데이터베이스 사이의 중개자 역할을 합니다. 데이터베이스에 대한 직접 접근을 허용하지 않고, 임의의 쿼리를 노출하지 않으며, 쓰기 작업을 허용하지 않습니다. 읽기 전용(read-only), 스키마 인지(schema-aware), 멀티 데이터베이스(multi-database), 그리고 완전한 LLM 안전(LLM-safe) 을 목표로 설계되었습니다.

🎯 주요 목표

• 안전한 데이터 접근 — DB 역할, 정책 엔진 및 통제된 쿼리 빌더를 통한 읽기 전용 보장.

• 데이터베이스 추상화 — 모델이 SQL을 생성하지 않습니다. DataGate가 안전하고 검증된 쿼리를 구성합니다.

• 멀티 데이터베이스 — DBeaver headless처럼 여러 애플리케이션의 다양한 데이터베이스에 연결할 수 있습니다.

• 정책 엔진 — 테이블, 컬럼, 필터, 제한 및 작업 복잡성에 대한 세밀한 제어.

• 스키마 인지 — 데이터베이스 스키마를 자동으로 로드하고 보안 규칙을 적용합니다.

• 실제 동시성 — Copilot의 병렬 요청에 적합한 비동기 및 안전한 아키텍처.

• 메트릭 및 감사 — 디버깅과 관찰 가능성을 위한 요청, 시간, 오류 및 제한 추적.

• 성능 프로파일링 — 지속적인 성능 모니터링을 위한 인프로세스 지연 시간 프로필(min/media/p50/p95/p99/max).

• 추상화된 백엔드 — 데이터베이스 백엔드를 위한 공통 읽기 전용 트레이트(trait)와 PostgreSQL, MySQL/MariaDB 및 SQLite용 구체적 구현.

Related MCP server: DB MCP Gateway

🧩 주요 기능

• 통제된 쿼리 빌더 — select, search, aggregate 같은 의미론적 작업과 자동 검증.

• 타입화된 MCP select — JSON 계약, JSON 행을 반환하는 읽기 전용 실행, 정책, 감사 및 살균된 오류; MCP 전송(transport)은 다음 단계로 남겨둡니다.

• 타입화된 MCP search — 허용된 컬럼에 대한 ILIKE 기반 의미론적 검색, 매개변수화된 쿼리, 정책/속도 제한/메트릭/감사 및 서버 측 출력 제한.

• 타입화된 MCP aggregate — 허용된 컬럼에 대한 count, sum, avg, min 및 max, 매개변수화된 필터, 자유 SQL 또는 GROUP BY 미지원.

• 버전 관리되는 MCP API — API 버전 및 사용 가능한 도구에 대한 안정적인 디스크립터(descriptor).

• MCP stdio 전송 — 정책 안전 경로를 통한 handshake, discovery 및 select, search, aggregate 호출.

• 고급 필터 — 패턴(LIKE/ILIKE), 범위(BETWEEN) 및 전체 텍스트(to_tsvector + plainto_tsquery) 지원. 항상 매개변수화되고 정책으로 검증됩니다.

• 통제된 스키마 카탈로그 — 테이블, 뷰, 인덱스, 제약 조건(PK/FK/UNIQUE/CHECK/EXCLUSION), 트리거, 함수, 프로시저 및 시퀀스에 대한 정책 필터링된 인트로스펙션; 안전한 경우에만 DDL 정의.

• 속도 제한 — 모델 루프 및 과도하게 무거운 쿼리로부터 보호.

• 출력 제한 — 응답은 항상 제한적이고 안전하며 구조화됩니다.

• 결정적 오류 — 스키마 누출 없음, SQL 노출 없음, 스택 추적 없음.

• 구조화된 오류 — 코드, 일반 메시지 및 retryable 표시가 포함된 안정적인 봉투(envelope).

• 외부 구성 — 정책, 제한 및 명명된 프로필(dev/staging/prod)을 위한 TOML 파일.

• MCP 입력 강화 — DoS/입력 남용 표면을 줄이기 위한 request_id 검증, 텍스트 페이로드 및 카디널리티 제한.

• 동적 정책 — 활성 정책은 MCP 도구를 다시 만들지 않고도 TOML에서 다시 로드하는 방식으로 원자적으로 교체할 수 있습니다.

DataGate는 자유 SQL 쿼리용 MCP 함수를 노출하지 않습니다. 에이전트는 구조화된 매개변수만 보내며, 매개변수화된 쿼리를 구성하기 전에 스키마와 정책에 대해 검증됩니다.

공개 오류는 invalid_request, policy_denied, backend_unavailable, internal_error 코드를 사용합니다. SQL, 스택 추적, 비밀번호, 필터 값 및 권한이 없는 객체 이름은 MCP 경계를 넘지 않습니다.

PostgreSQL 구성

PostgreSQL 자격 증명은 구성 파일이나 코드에 저장되지 않습니다. 서비스는 런타임 환경에서 연결 정보를 읽습니다.

• 간편 모드: DB_URL

• 구성 요소 모드: DB_HOST, DB_PORT(기본값 5432), DB_USER, DB_PASSWORD, DB_NAME

• PostgreSQL 옵션: DB_OPTIONS, key=value&key=value 형식

• 풀: DB_MAX_CONNECTIONS 및 DB_ACQUIRE_TIMEOUT_SECS

SQLite 구성

SQLite를 읽기 전용 모드로 사용하려면 다음 두 가지 변형 중 하나를 구성하세요.

• 전체 URL: SQLITE_URL

• 파일 경로: SQLITE_PATH

SQLite 풀 옵션:

• SQLITE_MAX_CONNECTIONS

• SQLITE_ACQUIRE_TIMEOUT_SECS

MySQL/MariaDB 구성

MySQL 또는 MariaDB를 읽기 전용 모드로 사용하려면 다음 두 가지 변형 중 하나를 구성하세요.

• 전체 URL: MYSQL_URL

• 구성 요소 모드: MYSQL_HOST, MYSQL_PORT(기본값 3306), MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE

MySQL/MariaDB 풀 옵션:

• MYSQL_MAX_CONNECTIONS

• MYSQL_ACQUIRE_TIMEOUT_SECS

멀티 데이터베이스 백엔드 선택

활성화할 백엔드를 명시적으로 선택하려면 DATAGATE_BACKEND를 설정하세요.

• auto(기본값): 우선순위 postgres -> mysql -> sqlite

• postgres

• mysql(또는 mariadb)

• sqlite

DATAGATE_BACKEND가 특정 백엔드로 설정되면 DataGate는 해당 환경 구성이 필요하며, 없으면 명시적 오류와 함께 종료됩니다.

부트스트랩 시 백엔드 우선순위:

1. PostgreSQL

2. MySQL/MariaDB

3. SQLite

목록에서 먼저 구성된 백엔드가 활성화됩니다.

선택적 서버 측 속도 제한은 RATE_LIMIT_REQUESTS와 RATE_LIMIT_WINDOW_SECS를 사용합니다. 제한은 정책, 쿼리 빌더 및 데이터베이스보다 먼저 request_id별로 적용됩니다. 임계값을 초과하는 요청은 rate_limited를 받으며 SQL을 생성하지 않습니다.

쿼리 빌더는 또한 정책에서 max_query_complexity를 통해 구성 가능한 최대 예산을 적용합니다. 각 컬럼은 1, 각 필터는 2의 비용이 듭니다. 예산을 초과하는 요청은 SQL을 생성하기 전에 거부됩니다.

select 응답은 정책의 max_output_bytes에도 적용됩니다. 최종 JSON 페이로드가 제한을 초과하면 DataGate는 SQL이나 내부 세부 정보를 노출하지 않고 정책 오류로 요청을 거부합니다.

메트릭 계층은 select 도구에 대해 서버 측 카운터와 지연 시간도 기록합니다. 총/허용/거부된 요청, 백엔드 오류, 메모리 내 p95 지연 시간 및 PostgreSQL 풀 스냅샷(size, idle).

애플리케이션 로깅은 두 가지 형식을 지원합니다.

• LOG_FORMAT=pretty(기본값)

• LOG_FORMAT=json(구조화, 로그 수집기에 적합)

최소 로그 레벨은 LOG_LEVEL(trace|debug|info|warn|error) 또는 RUST_LOG로 구성할 수 있습니다.

DB_URL이 있으면 구성 요소보다 우선합니다. PostgreSQL 역할에는 읽기 권한만 있어야 하며, 모든 연결은 default_transaction_read_only = on을 설정합니다.

활성 프로필은 profile = "dev"로 선택하며 [profiles.dev.policy]에서 정책을 정의할 수 있습니다. 명명된 프로필이 없으면 레거시 형식인 [policy]도 계속 지원됩니다. 선언되었지만 존재하지 않는 프로필은 데이터베이스 작업을 시작하지 않고 deny-all 정책을 활성화합니다.

공개 릴리스에는 Linux x64/ARM64, Windows x64/ARM64 및 macOS Intel/Apple Silicon용 바이너리가 포함되며, 플랫폼별 아카이브와 artifact 검증용 SHA256SUMS-* 파일이 함께 제공됩니다.

🛡️ 왜 DataGate인가?

LLM은 데이터베이스와 직접 대화해서는 안 됩니다. 안전하고, 예측 가능하며, 통제되고, 감사 가능하며, 확장 가능하고, 다중 애플리케이션을 지원하는 계층이 필요합니다. DataGate가 바로 그 계층입니다.

🔧 기술

• 언어: Rust

• 데이터베이스: PostgreSQL, MySQL/MariaDB 및 SQLite(현재), 추후 다른 DB

• 프로토콜: MCP(Model Context Protocol)

• 아키텍처: 비동기, 정책 기반, 스키마 인지

🚀 프로젝트 상태

DataGate는 설계 단계에 있습니다. 저장소에는 초기 구조, 문서 및 기술 로드맵이 포함되어 있습니다.

🧪 멀티 백엔드 통합 테스트

백엔드 통합 테스트는 선택적 환경 변수를 사용합니다.

• DATAGATE_TEST_POSTGRES_URL

• DATAGATE_TEST_MYSQL_URL

변수가 있으면 해당 테스트는 읽기 전용 백엔드가 통제된 SELECT를 실행하고 쓰기 문을 거부하는지 확인합니다. 변수가 없으면 테스트는 오류 없이 건너뜁니다.

전체 문서:

• Architecture.md — 설계 원칙 및 계층형 아키텍처

• ROADMAP.md — 1.0을 향한 상세 로드맵

• docs/configuration.md — 빠른 시작, 백엔드, 정책 및 운영

• docs/benchmarks.md — 로컬 SQLite 및 실제 PostgreSQL 벤치마크

• docs/hardening.md — MCP/데이터베이스 경계를 위한 최종 하드닝 체크리스트

• docs/http-transport-decision.md — 원격 MCP HTTP 전송에 대한 보안 결정

• docs/editor-registry-evaluation.md — MCP Registry 및 크로스 에디터 클라이언트 요구 사항 평가

• docs/packaging.md — 패키징 채널 및 artifact의 정식 소스

• docs/postgres-mcp-comparison.md — 다른 PostgreSQL MCP 서버와 비교

• docs/registry-publication.md — MCP Registry 전략, 크로스 에디터 설치 및 명명된 연결

• docs/mcp-registry-metadata.json — 레지스트리/MCP 갤러리용 후보 메타데이터

• docs/release-candidate.md — 1.0 후보의 기준 및 게이트

• docs/mcp-tools.md — MCP 도구의 내부 계약 및 규칙

• CONTRIBUTING.md — 기여, 커밋 및 브랜치 규칙

• SECURITY.md — 보안 정책 및 취약점 신고

VS Code에서 MCP로 시작하기:

• 기본 로컬 전송은 stdio입니다.

• 로컬 stdio용 mcp.json 템플릿은 docs/mcp-tools.md 및 docs/configuration.md에 있습니다.

• HTTP 원격은 기본 1.0 범위에서 제외되며 전용 보안 결정이 필요합니다.

📍 로드맵(요약)

• 정책 엔진 정의

• 통제된 쿼리 빌더 구현(매개변수화된 select)

• 읽기 전용 연결 보장

• 자동 스키마 인지(내부 PostgreSQL 카탈로그)

• 감사 로그 기반(AUDIT_LOG_PATH를 통한 JSONL)

• MCP 도구(select, search, aggregate)

• 멀티 데이터베이스 지원(PostgreSQL, MySQL/MariaDB, SQLite)

• 초기 엔터프라이즈 계층(관찰 가능성, 하드닝, 동적 정책)

• MCP API 안정성(버전 관리된 디스크립터, stdio 전송)

• MCP stdio 전송

• 벤치마크

• 최종 하드닝

• 1.0 후보 버전

📄 라이선스

Apache License 2.0