Version 0.3.0 · MCP protocol 2025-03-26버전 0.3.0 · MCP 프로토콜 2025-03-26

DBridge documentationDBridge 문서

On a corporate security network, DBridge lets an AI read Oracle with only the least privilege it needs. The rest of this page is the setup and the tool reference.기업 보안망에서 DBridge는 AI가 Oracle을 읽을 때 필요한 최소 권한만 줍니다. 이 페이지의 나머지는 설치와 도구 설명입니다.

Overview개요#Link to this section이 섹션 링크

DBridge exposes 19 read-only tools over the Streamable HTTP MCP transport and ships a tkinter admin UI built on the standard library. It answers four practical problems:DBridge는 Streamable HTTP MCP 트랜스포트로 읽기 전용 도구 19종을 노출하고, 표준 라이브러리로 만든 tkinter 관리 UI를 함께 제공합니다. 다음 네 가지 문제를 다룹니다.

• MCP clients spawn a process per session, so a stdio server makes a new connection pool each time. Here one resident process owns the endpoint, the pool, the config, and the logs.MCP 클라이언트는 세션마다 프로세스를 새로 띄웁니다. stdio 방식이면 세션마다 커넥션 풀이 새로 생깁니다. 여기서는 상주 프로세스 하나가 엔드포인트·풀·설정·로그를 소유합니다.
• An agent that does not know the schema guesses table names. A catalog cache and search tools sit in front, and the initialize response tells the agent to confirm names with tools instead of guessing.스키마를 모르는 에이전트는 테이블명을 추측합니다. 카탈로그 캐시와 검색 도구를 앞에 두고, initialize 응답에서 추측 대신 도구로 확인하도록 안내합니다.
• A read-only account policy conflicts with raw SQL execution. A character scanner, a catalog-based identifier check, row caps, and a timeout sit in the proxy layer.읽기 전용 계정 정책과 SQL 실행이 충돌합니다. 문자 스캐너·카탈로그 기반 식별자 검사·행수 상한·타임아웃을 프록시 계층에 둡니다.
• Large warehouse responses burn tokens. Row data returns as column arrays plus row arrays, and every list tool has a default, a cap, and a truncated flag.큰 DW에서 응답이 토큰을 태웁니다. 행 데이터를 컬럼 배열 + 행 배열로 반환하고, 목록 도구마다 기본값·상한·truncated 신호를 둡니다.

Who it's for누구를 위한 것인가#Link to this section이 섹션 링크

In a corporate security network, DBridge gives an AI agent only the least privilege it needs to reach the database.기업 보안망 환경에서 AI에게 DB에 접근할 수 있는 최소 권한만 부여합니다.

• DB administrators, data owners, and security staff who want to let an AI coding agent read work databases but worry about permissions and data leaving the network.DB 관리자·데이터 담당·보안 담당이 AI 코딩 에이전트에게 업무 DB 조회를 허용하고 싶지만 권한과 유출이 걱정되는 경우.
• Networks where the internet is blocked, external SaaS is not allowed, only an in-house LLM gateway or proxy is permitted, and security software is resident on the machine.인터넷이 차단되어 외부 SaaS를 쓸 수 없고, 사내 LLM 게이트웨이·프록시만 허용되며, 보안 소프트웨어가 상주하는 환경.

Requirements요구 사항#Link to this section이 섹션 링크

Installation설치#Link to this section이 섹션 링크

Run from source소스로 실행#Link to this section이 섹션 링크

git clone https://github.com/bamtang/dbridge
cd dbridge
pip install oracledb cryptography
python app.py                              # config.json + admin UI, live DB
python app.py --config other.json          # a different config file
python -m transport --config config.json   # headless resident server

The first run creates config.json next to the script or exe with default values. Edit connections before the server can reach a database.첫 실행 시 스크립트/exe 옆에 기본값으로 config.json이 생성됩니다. DB에 접속하려면 connections를 먼저 수정하세요.

Package a Windows exeWindows exe 패키징#Link to this section이 섹션 링크

pyinstaller --onefile --noconsole app.py
# only for the sun palette: --add-data "theme_sv;theme_sv"

Logs are written next to the exe under logs/ with a rotating file handler. Do not place config.json inside the PyInstaller bundle; the onefile temp directory is read-only.로그는 exe 옆 logs/에 RotatingFileHandler로 남습니다. PyInstaller onefile 임시 디렉터리는 읽기 전용이므로 config.json을 번들 안에 두지 마세요.

First run and config.json첫 실행과 config.json#Link to this section이 섹션 링크

Keys are validated on load; invalid values are rejected with a message. Saving a config validates first, backs up to backup/YYYYMMDDHHMMSS/, writes a temp file, and replaces it atomically, then restarts the server. If saving fails, the original file is left intact.설정은 로드 시 검증하며 잘못된 값은 메시지와 함께 거부합니다. 저장은 검증 → backup/YYYYMMDDHHMMSS/ 백업 → 임시 파일 → 원자적 교체 → 서버 재기동 순서입니다. 저장이 실패하면 원본이 손상되지 않습니다.

Connecting an MCP clientMCP 클라이언트 연결#Link to this section이 섹션 링크

The server speaks Streamable HTTP (MCP protocol 2025-03-26) at 127.0.0.1:8811/mcp. Register it with Claude Code:서버는 127.0.0.1:8811/mcp에서 Streamable HTTP(MCP 프로토콜 2025-03-26)를 씁니다. Claude Code에는 이렇게 등록합니다.

claude mcp add --transport http dbridge http://127.0.0.1:8811/mcp
# headless resident server (no admin UI):
python -m transport --config config.json

On initialize the server issues a session ID that later requests must carry. Idle sessions expire after 30 minutes.initialize에서 서버가 세션 ID를 발급하고 이후 요청은 이를 함께 보내야 합니다. 유휴 세션은 30분 뒤 정리됩니다.

Tool reference도구 레퍼런스#Link to this section이 섹션 링크

All 19 tools, grouped. Row data returns as {columns, rows, row_count, truncated, elapsed_ms}. Caps are enforced server-side; a truncated result sets truncated: true.도구 19종을 그룹별로 정리했습니다. 행 데이터는 {columns, rows, row_count, truncated, elapsed_ms} 형식입니다. 상한은 서버측에서 강제하며 잘리면 truncated: true가 됩니다.

Explore탐색#Link to this section이 섹션 링크

Understand이해#Link to this section이 섹션 링크

Query조회#Link to this section이 섹션 링크

Verify검증#Link to this section이 섹션 링크

Structure & compare구조·비교#Link to this section이 섹션 링크

Permission권한#Link to this section이 섹션 링크

Least-privilege design최소 권한 설계#Link to this section이 섹션 링크

Least privilege is enforced in code by the proxy layer, not just declared. When a tool would need a privilege that conflicts with a pure read-only account, the project disables the tool instead of granting or bypassing the privilege.최소 권한은 선언이 아니라 프록시 계층의 코드로 강제됩니다. 순수 읽기 전용 계정 정책과 충돌하는 권한이 필요한 도구는 권한을 자동 부여하거나 우회하지 않고 비활성화합니다.

• Read-only account premise: the tools never issue DML or DDL and expect only SELECT privileges.읽기 전용 계정 전제: 도구는 DML·DDL을 쓰지 않으며 SELECT 권한만 요구합니다.
• Only a single SELECT/WITH statement passes. A character scanner skips comments and literals, blocks DML, DDL, PL/SQL, multi-statements, and FOR UPDATE, and refuses anything ambiguous (fail-closed).SELECT/WITH 단일 문장만 통과합니다. 문자 스캐너가 주석·리터럴을 건너뛰며 DML·DDL·PL/SQL·다중문·FOR UPDATE를 차단하고 애매하면 거부합니다(fail-closed).
• Identifiers must exist in the catalog (a whitelist, since identifiers cannot be bound); values must be bind variables — no string-built SQL.식별자는 카탈로그에 존재해야 하고(식별자는 바인드할 수 없어 화이트리스트로 막음), 값은 바인드 변수만 허용합니다.
• Row, time, and LOB caps: 100 rows by default (query up to 1,000), a 30-second timeout, and LOB values cut at 2,000 characters.행수·시간·LOB 상한: 기본 100행(query 최대 1,000), 타임아웃 30초, LOB는 2,000자에서 절단.
• The listener binds to the literal 127.0.0.1; that binding is the only access control. There is no client authentication, so other processes on the same machine can connect.리스너는 리터럴 127.0.0.1에만 바인딩하며 이 바인딩이 유일한 접근 통제입니다. 클라이언트 인증이 없어 같은 머신의 다른 프로세스도 접속할 수 있습니다.
• explain is the only write path — it writes to a designated PLAN_TABLE and stays disabled until explain.enabled=true and an approved explain.plan_table are both set.explain이 유일한 쓰기 경로로, 지정한 PLAN_TABLE에 기록하며 explain.enabled=true와 승인된 explain.plan_table이 둘 다 설정되기 전까지 비활성입니다.
• Secrets: config prefers password_env; the app reads the value at connect time and passes it to the driver without decrypting it, and secrets appear as *** in logs, errors, and the status screen.비밀값: 설정은 password_env를 권장합니다. 앱은 접속 시 값을 읽어 복호화 없이 드라이버에 넘기고, 로그·오류·상태 화면에는 ***로 표시됩니다.

Error codes오류 코드#Link to this section이 섹션 링크

Errors serialize as {"error": {"code", "ora"?, "message", "hint"}} with isError: true. Codes are the public contract; each carries a default hint that tells the agent the next step.오류는 {"error": {"code", "ora"?, "message", "hint"}} 형태로 직렬화되고 isError: true로 표시됩니다. 코드가 공개 계약이며, 각 코드에는 에이전트의 다음 행동을 알려주는 기본 hint가 붙습니다.

When the driver reports an ORA/DPI/DPY code, the proxy maps it to a code and keeps the original string in ora. Privilege, credential, and TNS codes map to NO_ACCESS; connection and timeout codes map to TIMEOUT.드라이버가 ORA/DPI/DPY 코드를 보고하면 프록시가 이를 코드로 매핑하고 원문은 ora에 보존합니다. 권한·자격증명·TNS 코드는 NO_ACCESS, 연결·타임아웃 코드는 TIMEOUT으로 매핑됩니다.

Admin UI관리 UI#Link to this section이 섹션 링크

A tkinter panel built on the standard library, with five palette presets. It reads a status snapshot and a log queue; commands go to worker threads. It is not part of the query path.표준 라이브러리로 만든 tkinter 패널이며 팔레트 프리셋 5종을 내장합니다. 상태 스냅샷과 로그 큐를 읽고 명령은 워커 스레드에 위임합니다. 조회 경로와는 분리되어 있습니다.

• Status — server state, connections, and readiness.상태 — 서버 상태·커넥션·준비 여부.
• Client setup — the MCP registration command.Claude 연동 — MCP 등록 명령.
• Tools — the registered tools.도구 — 등록된 도구.
• Common codes — the shared common-code table.공통코드 — 공유 공통코드 테이블.
• Settings — edit and save config.json.설정 — config.json 편집·저장.
• Logs — a 5,000-line ring buffer.로그 — 5,000행 링버퍼.

Troubleshooting문제 해결#Link to this section이 섹션 링크

Startup is refused기동이 거부됨#Link to this section이 섹션 링크

The default config fills require_process with one program. If it is not running, the GUI shows a message box and exits 1; the headless path prints to stderr and exits 1. If the process list itself cannot be read, startup is refused as well (fail-closed). Set "require_process": [] to disable the gate.기본 설정은 require_process에 프로그램 하나를 채웁니다. 그 프로그램이 실행 중이 아니면 GUI는 messagebox를 띄우고 exit 1, 헤드리스는 stderr에 출력하고 exit 1로 거부합니다. 프로세스 목록 열거 자체가 실패해도 기동을 거부합니다(fail-closed). 게이트를 끄려면 "require_process": []로 두세요.

Port already in use포트 사용 중#Link to this section이 섹션 링크

If the port is taken, binding fails: the headless path prints failed to bind: ... and exits 1. Change proxy.port and update the client registration URL to match.포트가 사용 중이면 바인딩이 실패합니다. 헤드리스는 failed to bind: ...를 출력하고 exit 1로 끝납니다. proxy.port를 바꾸고 클라이언트 등록 URL도 맞춰 수정하세요.

Catalog refresh fails카탈로그 갱신 실패#Link to this section이 섹션 링크

Warmup collects the catalog once. If it fails, the server records the error and keeps serving; the tool list is published only after a successful warmup. Check the connection and credentials, then call catalog_refresh.기동 시 카탈로그를 한 번 수집합니다. 실패하면 오류를 남기고 서버는 계속 응답하며, 도구 목록은 수집이 성공한 뒤에만 게시됩니다. 커넥션과 자격증명을 확인한 뒤 catalog_refresh를 호출하세요.

ORA errorsORA 오류#Link to this section이 섹션 링크

Read the code, the original ora string, and the hint together. A NO_ACCESS usually means a missing SELECT grant or a wrong DSN; a UNKNOWN_OBJECT usually means the catalog is stale.code와 원문 ora, hint를 함께 보세요. NO_ACCESS는 대개 SELECT 권한 누락이나 DSN 오류이고, UNKNOWN_OBJECT는 대개 카탈로그가 오래된 경우입니다.

Config is rejected설정이 거부됨#Link to this section이 섹션 링크

Validation messages are in Korean. Common causes: proxy.host is not the literal 127.0.0.1, proxy.port is out of 1–65535, proxy.log_level is not DEBUG/INFO/WARNING/ERROR, or a connection is missing name/dsn/user.검증 메시지는 한국어입니다. 흔한 원인은 proxy.host가 리터럴 127.0.0.1이 아님, proxy.port가 1~65535를 벗어남, proxy.log_level이 DEBUG/INFO/WARNING/ERROR가 아님, 커넥션에 name/dsn/user 누락입니다.

Limitations한계#Link to this section이 섹션 링크

• No authentication or authorization layer. The loopback binding and session IDs are the only access control.인증·인가 계층이 없습니다. 루프백 바인딩과 세션 ID가 유일한 접근 통제입니다.
• No data masking; it assumes masking is enforced at the database level.데이터 마스킹이 없습니다. 마스킹은 DB 단에서 적용된다는 전제입니다.
• Oracle only; adding another DBMS means adding a branch to the driver factory.Oracle 전용입니다. 다른 DBMS를 쓰려면 드라이버 팩토리에 분기를 추가해야 합니다.
• Tools are added in code only; JSON-declared tools are not supported. Only the join-relationship JSON loader is used.도구는 코드로만 추가합니다. JSON 선언 도구는 지원하지 않고, 조인 관계 JSON 로더만 사용합니다.
• The deployment target is Windows, but the checks so far ran on macOS with Python 3.12; live Oracle, a real display, and the packaged exe are not yet verified.배포 대상은 Windows이지만 지금까지 점검은 macOS·Python 3.12에서 실행했습니다. 실 Oracle, 실제 디스플레이, 패키징된 exe는 아직 검증하지 않았습니다.
• batch_permission reads a permission table with a fixed, site-specific schema; it does not work without that table.batch_permission은 고정된 특정 스키마의 권한 테이블을 읽습니다. 그 테이블이 없으면 동작하지 않습니다.

FAQ#Link to this section이 섹션 링크

License라이선스#Link to this section이 섹션 링크

DBridge is released under the MIT License.DBridge는 MIT License로 배포됩니다.

Edit on GitHubGitHub에서 편집 MIT License