> ## Documentation Index
> Fetch the complete documentation index at: https://manual.seahorse.dnotitia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> PostgreSQL RDB MCP Server 템플릿 — 관리형 서버(rdb_server.py) + System Default 환경변수. 구 RDB Endpoint 통합

# Postgresql

# PostgreSQL RDB MCP Server 템플릿

**경로**: Console → **Agent Ops → Tool Management** → **+ 도구 생성** → **Quick Setup** 에서 **PostgreSQL (RDB)** 선택

`RDB MCP Server for PostgreSQL database query and management`

Seahorse 내부 관리형 MCP 서버(`rdb_server.py`)로 PostgreSQL 에 연결해 스키마 탐색·쿼리 실행을 수행합니다.

<Info>
  이전 버전의 **RDB Endpoint** 기능은 이 템플릿으로 통합되었습니다. 별도 메뉴가 아닌 **서비스 템플릿** 의 하나로 제공됩니다.
</Info>

## 시작 전 — PostgreSQL 이 준비되어 있어야 합니다

<Warning>
  **이 MCP 템플릿은 "Seahorse 가 접속할 수 있는 PostgreSQL 이 이미 구축·운영 중" 임을 전제로 합니다.** 도구를 등록하는 이 화면에서 DB 를 새로 만들어주지 않습니다. DB 준비 → 접속값 준비 → Seahorse 연결 순서로 진행하세요.
</Warning>

### 일반적인 배포 흐름

대부분의 기업은 **AWS RDS · GCP Cloud SQL · Azure Database** 등 클라우드 관리형 PostgreSQL 에 이미 데이터가 올라가 있습니다. 아직 없다면 먼저 DB 부터 구축해야 합니다.

```
(1) DB 구축                     (2) 접속 정보 준비          (3) Seahorse 연결
─────────────────               ─────────────────           ─────────────────
AWS RDS PostgreSQL              host / port / user        MCP Tools 연결란
GCP Cloud SQL              →    password / dbname    →    (Environment Vars)
Azure Database                  sslmode
자체 호스팅 DB                   (읽기 전용 계정)
```

### 선행 조건 체크리스트

* **PostgreSQL 인스턴스 가동 중** — AWS RDS · GCP Cloud SQL · 자체 호스팅 어디든 가능
* **Seahorse 에이전트 서버가 DB 에 네트워크로 도달 가능** — 방화벽·VPC·보안 그룹에서 포트(`5432` 기본) 허용, 필요 시 Seahorse 서버 IP 를 허용 목록에 추가
* **전용 DB 사용자 발급** — 권장 권한은 `GRANT SELECT` 만 (읽기 전용). `postgres` · `admin` 같은 전역 계정 금지
* **DB 이름·호스트·포트·SSL 모드** 확정
* (SSL 사용 시) **인증서·CA** 가 필요하면 운영자가 사전 배포

### Seahorse MCP Tools 연결란이 요구하는 정보

템플릿 등록 화면의 Environment Variables 는 **DB 접속에 필요한 커넥션 정보** 를 전부 요구합니다. 위에서 준비한 값을 그대로 넣으면 됩니다.

| 필요한 값         | 예                                                             | 어디서 얻나                                   |
| ------------- | ------------------------------------------------------------- | ---------------------------------------- |
| `PG_HOST`     | `mydb.xxxxx.ap-northeast-2.rds.amazonaws.com` / `10.20.30.40` | AWS RDS 콘솔·GCP SQL 인스턴스 상세 / 자체 DB 서버 IP |
| `PG_PORT`     | `5432` (기본)                                                   | 동일                                       |
| `PG_USER`     | `agent_ro`                                                    | DBA 가 별도 발급                              |
| `PG_PASSWORD` | (시크릿)                                                         | DBA 가 별도 발급                              |
| `PG_DBNAME`   | `analytics`                                                   | 접속 대상 DB 이름                              |
| `PG_SSLMODE`  | `require` 권장                                                  | 운영 정책                                    |

이 값들은 **System Default 타입** 이라 사용자 화면에서 직접 입력하지 않고 **운영자가 [Environment](/internal/system-admin/settings/environment) 에 세팅** 합니다. 아래 [Environment Variables](#environment-variables) 섹션 참고.

### DB 가 아직 없으면?

* **클라우드 관리형 PostgreSQL (권장)** — AWS RDS · GCP Cloud SQL · Azure Database 중 선택해 인스턴스 생성. 보안 그룹에서 Seahorse 에이전트 서버 IP 허용.
* **자체 호스팅** — VPC 내 EC2·Compute Engine 등에 PostgreSQL 설치. 네트워크 라우팅·방화벽 구성 필요.
* **임시 테스트만** — 로컬에 `docker run postgres` 로 임시 기동 (실제 운영 용도로는 부적합).

<Warning>
  DB 가 준비되지 않은 상태로 템플릿을 Save 하면 도구는 등록되지만 **호출 시 `could not connect to server` · `authentication failed` 같은 에러로 조용히 실패** 합니다.
</Warning>

### 요약 순서

1. **DB 구축·계정 발급** (DBA / 인프라팀) — AWS RDS / GCP Cloud SQL / 자체 호스팅 중 택1 + 읽기 전용 계정
2. **운영자가 Seahorse Environment 에 접속값 세팅**
3. 본 화면에서 **PostgreSQL 템플릿으로 도구 등록 → Save**
4. [도구 상세](/console/agent-ops/agent-tool/tool-detail) **Test** 로 연결 검증

## 사전 주입 값 (Basic Information)

Quick Setup 에서 `PostgreSQL (RDB)` 선택 시 자동 채워지는 값.

| 필드            | 값                           |
| ------------- | --------------------------- |
| **Name**      | `postgresql`                |
| **Transport** | `Standard I/O` (stdio)      |
| **설명**        | `PostgreSQL RDB MCP Server` |
| **Access**    | 기본 `Private`                |

### Run Settings

| 항목          | 값                                          |
| ----------- | ------------------------------------------ |
| **Command** | `python`                                   |
| **Args**    | `-u`, `/app/app/mcp_servers/rdb_server.py` |

## Environment Variables

### 템플릿 기본 제공 (전부 `System Default`)

PostgreSQL 템플릿의 사전 정의 7 개 변수는 **모두 `System Default` 타입** 으로 박혀 있습니다. Value 필드에는 `Environment variable value` 플레이스홀더가 보이지만 `This value is fixed and automatically used at runtime` 안내처럼 **이 화면에서 값을 수정하지 않습니다** — 실제 값은 운영자가 [Environment](/internal/system-admin/settings/environment) 에 세팅한 값이 런타임에 주입됩니다.

일부 변수는 **기본 표시값** 이 미리 보입니다 (`PG_PORT = 5432`, `PG_SSLMODE = prefer`). 이 표시값도 System Default 경로에서 관리됩니다.

| Key              | 설명                          | UI 기본 표시                                 |
| ---------------- | --------------------------- | ---------------------------------------- |
| **PG\_HOST**     | PostgreSQL host address     | 빈값                                       |
| **PG\_PORT**     | PostgreSQL port             | `5432`                                   |
| **PG\_USER**     | PostgreSQL username         | 빈값                                       |
| **PG\_PASSWORD** | PostgreSQL password         | 빈값                                       |
| **PG\_DBNAME**   | PostgreSQL database name    | 빈값                                       |
| **PG\_SSLMODE**  | PostgreSQL SSL mode         | `prefer` (권장: `require` / `verify-full`) |
| **TOOL\_DESC**   | MCP 용 도구 설명 (LLM 호출 시 hint) | 빈값                                       |

<Warning>
  **사전 정의 7 개 변수의 값은 이 화면에서 변경 불가** 합니다. 다른 DB · 계정으로 바꾸려면 운영자가 [Environment](/internal/system-admin/settings/environment) 에서 해당 키의 값을 갱신해야 합니다.
</Warning>

### 추가 환경변수 (Add Environment Variable)

사전 정의 변수 아래 **`Add Environment Variable`** 버튼으로 **추가 변수를 자유롭게 정의** 할 수 있습니다. 추가 시 아래 두 타입 중 **선택** 하며, **User Input 도 가능** 합니다.

| 타입                 | 이 화면에서 값 입력?                          | 용도                                  |
| ------------------ | ------------------------------------- | ----------------------------------- |
| **User Input**     | ✓ 직접 입력                               | 도구별 커스텀 설정 — 테넌트별 스키마·타임아웃 등을 개별 지정 |
| **System Default** | ✗ 입력 불가 — 운영자 Environment 에 세팅한 값이 주입 | 조직 전체 공통 추가 설정 (프록시 등)              |

**추가를 고려할 변수**

| 변수                           | 타입 권장                        | 설명                                              |
| ---------------------------- | ---------------------------- | ----------------------------------------------- |
| `PG_SCHEMA`                  | User Input 또는 System Default | 기본 스키마 (`public` 외 특정 스키마 사용 시)                 |
| `PG_READONLY`                | User Input                   | `true` 로 설정해 `UPDATE/DELETE` 호출을 MCP 레벨에서 추가 차단 |
| `PG_STATEMENT_TIMEOUT_MS`    | System Default               | 세션 쿼리 타임아웃 (ms)                                 |
| `HTTP_PROXY` / `HTTPS_PROXY` | System Default               | 사내 프록시 경유 시                                     |

<Info>
  **PostgreSQL 템플릿의 설계 의도**

  * 기본 7 개 변수는 "테넌트 공통 DB 한 개에 모두 붙는다" 전제로 System Default 고정.
  * **Add Environment Variable 로는 User Input 타입도 선택 가능** 하므로, 테넌트별 다른 값을 쓰고 싶으면 추가 변수로 확장하면 됩니다.
  * 다만 기본 7 개(`PG_HOST` 등)를 테넌트별로 다르게 하려면 [커스텀 도구](/console/agent-ops/agent-tool/custom-create) 로 rdb\_server.py 를 복사 등록 + 전체 환경변수를 User Input 으로 새로 구성하는 것이 **영향 격리** 관점에서 안전합니다.
</Info>

## 제공 기능

| 기능         | 설명                                                               |
| ---------- | ---------------------------------------------------------------- |
| **스키마 탐색** | `list_tables` · `get_table_schema` — 테이블·컬럼·인덱스 목록               |
| **쿼리 실행**  | `execute_query` — SELECT 중심 (DB 권한으로 쓰기 차단 권장)                   |
| **샘플·통계**  | 상위 N 행 조회, 행 수·기본 통계                                             |
| **연결 검증**  | [도구 상세](/console/agent-ops/agent-tool/tool-detail) 의 **Test** 버튼 |

## 권장 사용 패턴

<Steps>
  <Step title="운영 DB 에 읽기 전용 계정 발급">
    ```sql theme={null}
    CREATE USER agent_ro WITH PASSWORD 'strong-pw';
    GRANT CONNECT ON DATABASE mydb TO agent_ro;
    GRANT USAGE ON SCHEMA public TO agent_ro;
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO agent_ro;
    ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO agent_ro;
    ```

    해당 계정 정보를 운영자에게 전달 → Environment 설정에 반영.
  </Step>

  <Step title="SSL 설정">
    운영 환경은 `PG_SSLMODE=require` 또는 `verify-full` 권장.
  </Step>

  <Step title="템플릿에서 도구 생성">
    Quick Setup → **PostgreSQL** → Save. System Default 변수는 자동 주입되므로 **자격 증명을 이 화면에서 입력하지 않습니다**.
  </Step>

  <Step title="에이전트에 연결">
    [Agent 수정 → Tools 탭](/console/agent-ops/agent/agent-update) 에서 활성화.
  </Step>

  <Step title="동작 확인">
    [도구 상세](/console/agent-ops/agent-tool/tool-detail) **Test** 로 연결 검증 → Agent Chat 에서 `테이블 목록 알려줘` 로 호출 확인.
  </Step>
</Steps>

## 활용 레시피

* [PostgreSQL 반복 쿼리 자동화](/agent-chat/recipes/postgres-sql-automation) — 10 가지 쿼리 시나리오 + Flow + Scheduler
* [보고서 자동 발행](/agent-chat/recipes/scheduled-report) — DB 지표 → 보고서
* [대량 문서 인덱싱·요약](/agent-chat/recipes/bulk-document-summarize) — 요약 메타를 PostgreSQL 적재

## 보안 주의

<Warning>
  **AI 가 데이터를 임의로 수정·삭제할 가능성이 있습니다.** LLM 이 의도를 잘못 해석하거나 외부 프롬프트 인젝션(Slack·문서 등)에 영향받아 `DELETE` / `UPDATE` / `DROP` / `TRUNCATE` 같은 파괴적 쿼리를 실행할 수 있으며, 한 번 실행된 DML 은 백업 복원 전까지 되돌릴 수 없습니다. **읽기 전용 용도로만** 연동하시고, 데이터 변경 파이프라인은 검증된 ETL 도구로 수행하세요.
</Warning>

**핵심 안전장치**

* **운영 DB 에 쓰기 권한 계정 연결 금지** — `GRANT SELECT` 만 부여. `INSERT/UPDATE/DELETE/DROP/TRUNCATE` 는 DB 레벨에서 차단
* 가능하면 **Read Replica · 분석 전용 DB** 에 연결해 운영 DB 를 직접 건드리지 않기
* **System Prompt 에 명시적 금지 규칙** — `SELECT 외 쿼리 생성 금지`, `사용자가 쓰기 요청해도 거절` 명시
* **민감 컬럼(PII·단가)** 은 DB 뷰로 마스킹하거나 읽기 계정에서 컬럼 권한을 제한
* **System Default 값은 전역 공유** — 이 템플릿으로 생성된 모든 테넌트의 PostgreSQL 도구가 동일한 DB 를 바라봅니다. 테넌트별 격리가 필요하면 커스텀 도구로 분리
* **퇴사자 계정 회수** — DB 계정 disable + Environment 값 갱신

## 다른 DBMS (MySQL / Oracle / MSSQL 등)

<Warning>
  **현재 Seahorse 공식 템플릿은 PostgreSQL 만 지원** 합니다. 다른 DBMS 는 [커스텀 도구](/console/agent-ops/agent-tool/custom-create) 로 해당 MCP 서버(`@modelcontextprotocol/server-mysql` 등) 를 `stdio` / `npx` 방식으로 직접 등록해야 하며, 공식 지원이 아니라 안정적으로 동작하지 않을 수 있습니다.
</Warning>

* 커스텀 MCP 서버의 **동작·호환성은 Seahorse 에서 보장하지 않습니다**. 업스트림 변경·드라이버 버전·네트워크 구성에 따라 연결 실패·데이터 타입 불일치·인증 오류 등이 발생할 수 있습니다.
* 등록 직후 [도구 상세](/console/agent-ops/agent-tool/tool-detail) 의 **Test** 로 핸드셰이크·`list_tools` 응답이 정상인지 **반드시 사전 검증** 하세요.
* 공식 지원이 필요하면 [고객지원 창구](/shared/intro/seahorse-cloud-overview#지원--문의) 로 요청해주세요 — 수요에 따라 향후 템플릿으로 추가될 수 있습니다.

**일반적인 접근**

* 간단 읽기 전용: 공식 `@modelcontextprotocol/server-<dbms>` 가 존재하면 `npx` 로 등록
* 커스텀 스키마·뷰 조합: 자체 래퍼 MCP 서버를 작성해 쿼리 화이트리스트와 함께 배포
* 대안: [PostgreSQL Foreign Data Wrapper](https://www.postgresql.org/docs/current/postgres-fdw.html) 로 다른 DB 를 PostgreSQL 뷰로 노출 후 본 템플릿으로 접근

## Transport 필드에 관하여

Basic Information 의 Transport 드롭다운에서 **Standard I/O** 외에 **Streamable HTTP** 를 선택하는 것이 UI 상으로는 가능합니다. HTTP 선택 시 입력 필드는 다음과 같이 바뀝니다:

| stdio 필드                               | → | HTTP 필드                                                             |
| -------------------------------------- | - | ------------------------------------------------------------------- |
| Command + Args + Environment Variables | → | Connection Settings (Endpoint URL · Timeout · Verify SSL) + Headers |

<Warning>
  **본 템플릿의 기본 Transport 는 `Standard I/O` 입니다.** 업스트림 MCP 서버(`@modelcontextprotocol/server-slack` · `@modelcontextprotocol/server-github` · `uvx mcp-atlassian` · `rdb_server.py`) 는 모두 **로컬 프로세스(stdio) 기반** 으로 설계되어 있습니다.

  UI 에서 **Streamable HTTP** 로 전환할 수는 있지만, 그 경우 같은 기능을 HTTP 엔드포인트로 감싸서 별도 호스팅한 서버가 이미 준비되어 있어야 합니다 (공식 지원되는 HTTP 버전이 Seahorse 에 번들된 것은 아닙니다).

  * **일반 사용자는 기본 `Standard I/O` 를 그대로 유지** 하세요.
  * HTTP 엔드포인트를 자체 운영 중이고 그걸 연결하려는 경우라면, 사실상 [커스텀 도구](/console/agent-ops/agent-tool/custom-create#streamable-http-방식) 로 처음부터 등록하는 편이 깔끔합니다.
  * HTTP 로 전환한 상태에서는 본 템플릿의 사전 주입 Command/Args/Env 가 더 이상 의미를 갖지 않습니다.
</Warning>

## 관련 문서

* [Quick Setup 템플릿 목록](/console/agent-ops/agent-tool/templates)
* [도구 상세](/console/agent-ops/agent-tool/tool-detail)
* [커스텀 도구 생성](/console/agent-ops/agent-tool/custom-create)
* [Environment (운영자 환경변수)](/internal/system-admin/settings/environment)
* [PostgreSQL 반복 쿼리 자동화](/agent-chat/recipes/postgres-sql-automation)