> ## 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 MCP + Scheduler 조합 — 반복 SQL 리포트 자동화 (일일/주간 지표)

# Postgres sql automation

# PostgreSQL 반복 쿼리 자동화

**요약**: PostgreSQL 데이터베이스에 연결된 에이전트로 정기 지표 쿼리를 실행하고, 결과를 정해진 포맷으로 자동 리포트. 단순 일일 KPI부터 이상 탐지·트렌드 분석·고객 코호트·재고 알림까지 광범위하게 활용 가능합니다.

## 먼저 읽어주세요 — 읽기 전용 보고서 용도로만 권장

<Warning>
  **AI 가 실수 또는 외부 프롬프트의 영향으로 `DELETE` / `UPDATE` / `DROP` 같은 파괴적 쿼리를 임의로 실행할 가능성이 있습니다.** 본 레시피는 **정기 보고서 출력·지표 조회 같은 읽기 전용 용도로만 연동** 하시길 권장합니다. 데이터를 추가하거나 수정하는 작업은 자동화하지 마세요.
</Warning>

**최소 안전장치**

1. **읽기 전용 DB 계정** 으로만 연결 — `GRANT SELECT` 만 부여, `INSERT/UPDATE/DELETE/DROP/TRUNCATE` 는 DB 레벨에서 차단
2. 가능하면 **운영 DB 가 아닌 Read Replica·분석용 DB** 에 연결
3. **민감 컬럼**(개인정보·결제 정보) 은 뷰로 마스킹하거나 컬럼 권한 제거
4. System Prompt 에 `SELECT 외 쿼리 금지` 명시

```sql theme={null}
-- 읽기 전용 계정 예시 (이 범위를 넘지 마세요)
CREATE USER agent_ro WITH PASSWORD '...';
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;
```

데이터 변경이 필요한 파이프라인이 있다면 **에이전트가 아닌 검증된 ETL 도구** 를 사용하고, 에이전트는 **조회·요약·리포트 생성** 까지만 담당하도록 역할을 분리하세요.

## 활용 시나리오

| 시나리오                       | 빈도         | 출력                                  |
| -------------------------- | ---------- | ----------------------------------- |
| **일일 매출 / 주문 KPI**         | 매일 09:00   | 전일 대비 변화율 + Slack 채널                |
| **주간 신규 가입자 코호트**          | 매주 월 09:00 | 가입 주차별 retention 표 + 이메일            |
| **이상 탐지 (매출·트래픽 outlier)** | 매시간        | 임계 초과 시에만 PagerDuty / Slack alert   |
| **재고 부족 알림**               | 매일 08:00   | 안전재고 하회 SKU 목록 + 발주 담당자 멘션          |
| **장애 대시보드 자동 답변**          | 사용자 질의 시   | error\_log + slow\_query 조인 → 원인 추정 |
| **고객 문의 통계**               | 주간         | 카테고리별 건수 · SLA 미준수 비율               |
| **A/B 테스트 결과 자동 집계**       | 일간         | 그룹별 전환율 + 통계적 유의성                   |
| **계약 만료 임박 알림**            | 매주         | 30/60/90 일 내 만료 고객 · 갱신 담당자         |
| **데이터 품질 점검**              | 매일 새벽      | NULL률·중복·정합성 위반 로그                  |
| **임원 위클리 요약**              | 매주 금 17:00 | 핵심 KPI 5 개 + 자연어 인사이트 1 단락          |

## 요구 사항

| 항목                    | 설정 위치                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| **PostgreSQL MCP 도구** | [Console → Tool Management → PostgreSQL 템플릿](/console/agent-ops/agent-tool/templates/postgresql)           |
| **DB 접속 환경변수**        | **Internal → System Management → [Environment](/internal/system-admin/settings/environment)** (운영자만 설정 가능) |
| **읽기 전용 DB 계정**       | 운영 DB 에서 직접 생성 (보안 필수)                                                                                     |
| **에이전트 생성 & 도구 연결**   | [Agent 생성](/console/agent-ops/agent/agent-create) → Tools 탭                                                |
| **Scheduler (반복 실행)** | [사용자 메뉴 → Scheduler](/agent-chat/user-menu/scheduler)                                                      |
| **(선택) Slack 전송**     | Slack MCP 템플릿 + 채널 bot token                                                                               |

<Warning>
  **PostgreSQL 접속 설정은 사용자 화면이 아닌 운영자 Console 에서 선행** 되어야 합니다.

  PostgreSQL 템플릿의 환경변수(`PG_HOST` · `PG_PORT` · `PG_USER` · `PG_PASSWORD` · `PG_DBNAME` · `PG_SSLMODE` · `TOOL_DESC`)는 전부 **System Default 타입** 입니다. 사용자가 도구 생성 화면에서 직접 입력하지 못하며, **운영자가 Internal → System Management → [Environment](/internal/system-admin/settings/environment) 에서 세팅** 해야 런타임에 자동 주입됩니다.

  **진행 순서**

  1. 운영자에게 DB 접속 정보(호스트·계정·DB 명) 전달 + 연결 요청
  2. 운영자가 Environment 에 7 개 환경변수 등록
  3. 그 다음에 사용자 화면(Tool Management)에서 PostgreSQL 템플릿 생성 → Save
  4. [도구 상세](/console/agent-ops/agent-tool/tool-detail) 의 **Test** 로 연결 확인

  Environment 세팅이 누락된 상태로 템플릿을 만들면 **도구는 등록되지만 호출 시 조용히 실패** 합니다. 상세 동작·타입 구분: [PostgreSQL 템플릿 → Environment Variables](/console/agent-ops/agent-tool/templates/postgresql#environment-variables)
</Warning>

## 단계

<Steps>
  <Step title="에이전트 + PostgreSQL 도구 등록">
    Console → Tool Management → **도구 생성** → **PostgreSQL** 템플릿 선택.
    환경변수 `POSTGRES_CONNECTION_STRING` 에 읽기 전용 연결 문자열 입력.
    자세한 설정: [PostgreSQL 템플릿](/console/agent-ops/agent-tool/templates/postgresql)
  </Step>

  <Step title="MCP Tools 패널에서 활성화">
    채팅 툴바 \[1] **MCP Tools** 패널에서 `postgresql` 서버 체크 → **Apply**.
  </Step>

  <Step title="스키마 탐색">
    첫 실행 시 에이전트에게 스키마를 알려줍니다:

    > **프롬프트 예시**:
    > "postgresql 에 연결된 DB에서 public 스키마의 테이블 목록과 각 테이블의 컬럼을 알려줘."

    에이전트가 `list_tables`, `get_table_schema` 도구를 Tool Call 카드로 호출하며 구조 파악.
  </Step>

  <Step title="쿼리 자연어로 실행">
    > **프롬프트 예시**:
    > "어제 하루 주문 건수를 region 별로 집계하고, 상위 5개 지역을 표로 보여줘."

    에이전트가 `execute_query` 로 SQL 실행. 결과는 Tool Call 카드 + 자연어 요약으로 표시.
  </Step>

  <Step title="Flow Studio 에 저장 (재사용)">
    반복 실행할 쿼리 플로우를 [Flow Studio](/agent-chat/toolbar/flow-studio) 로 저장:

    * 노드 1: `execute_query(sql="...")`
    * 노드 2: LLM 응답 포맷 (예: Markdown 표)
    * 노드 3: (선택) Slack 메시지 전송
  </Step>

  <Step title="Scheduler 로 반복 예약">
    [사용자 메뉴 → Scheduler](/agent-chat/user-menu/scheduler) → **+ New Schedule**:

    * Flow: 저장한 Flow 이름
    * Cron: `0 9 * * MON` (매주 월요일 9시) 또는 `0 9 * * *` (매일 9시)
    * Timezone: `Asia/Seoul`

    실행 결과는 Scheduler 이력에서 확인 + Slack 전송 시 채널에 자동 게시.
  </Step>
</Steps>

## 프롬프트 템플릿

### 일일 지표 리포트

```
어제 {yesterday} 하루 동안의 다음 지표를 구해줘:
1. 신규 사용자 수 (users.created_at 기준)
2. 주문 건수 및 총 매출
3. 지역별 상위 5개 매출

결과를 Markdown 표로 정리하고, 전일 대비 변화율도 포함해줘.
```

### 이상 탐지 (Outlier)

```
최근 7일 간 주문 금액 패턴을 분석하고,
표준편차 2배 이상 벗어난 outlier 를 찾아줘.
쿼리와 결과를 함께 보여줘.
```

### 코호트 분석 (Retention)

```
최근 8주간 주별 가입 코호트의 retention 을 계산해줘.
주차별로 W1~W4 까지 재방문율을 표로 만들어주고,
가장 retention 이 높은 주의 가입 채널을 분석해줘.
```

### A/B 테스트 결과

```
experiments 테이블에서 'checkout-v2' 실험의
A/B 그룹별 전환율을 비교하고,
chi-square test 의 p-value 를 계산해서
통계적으로 유의한 차이가 있는지 알려줘.
```

### 재고 부족 알림

```
products 테이블에서 stock <= safety_stock 인 SKU를 모두 찾아서,
공급자별로 그룹핑한 뒤 가장 시급한 상위 10개를
sku, name, stock, safety_stock, supplier 컬럼으로 보여줘.
```

### 데이터 품질 점검

```
다음 테이블별로 데이터 품질을 점검해줘:
- users: email NULL 비율, 중복 email 수
- orders: order_date 미래 날짜 건수, amount 음수 건수
- products: price 0원 또는 NULL 건수

문제가 있으면 SQL 과 함께 결과를 보여줘.
```

### 자연어 임원 요약

```
지난주 (월~일) KPI 를 다음 형식으로 요약해줘:

📊 **위클리 요약 ({날짜})**
- 매출: ₩X (전주 대비 ±%)
- 주문: N건 (±%)
- 신규: N명 (±%)
- 이탈률: %

🔍 **인사이트** (1단락 자연어):
가장 두드러진 변화와 원인 추정.
```

## 주의사항

<Warning>
  * **읽기 전용 계정 필수** — 에이전트가 UPDATE/DELETE 하지 않도록 DB 권한에서 차단
  * **쿼리 복잡도** — 비용이 큰 풀스캔 쿼리는 인덱스 추가 또는 LIMIT 강제
  * **실행 시간 제한** — 툴 호출 타임아웃 고려 (기본 30–60초)
  * **민감 정보** — PII 컬럼은 SELECT 대상에서 제외하거나 마스킹 뷰 사용
</Warning>

<Info>
  Tool 호출 실패 시 [Blocked API Keys](/internal/system-admin/operations/blocked-api-keys) 나 DB 접속 로그를 먼저 확인하세요.
</Info>

## 변형·응용

* **다중 DB 조합** — PostgreSQL + GitHub MCP → 배포 일자와 매출 변화 상관 분석
* **RAG + SQL 하이브리드** — 사내 위키(Storage 문서) + DB 지표 → "이번 분기 매출 하락 원인" 같은 질의에 정량+정성 답변
* **사용자 권한별 마스킹 뷰** — 영업·재무·임원 등 역할별 다른 뷰를 에이전트에 노출
* **자연어 → SQL → 시각화** — 결과를 [Plotly Tool](/agent-chat/toolbar/flow-studio) 로 차트 생성
* **장애 자동 분석** — 모니터링 알람 발생 시 Slack → 에이전트 호출 → 관련 SQL 자동 실행 → 1차 분석 보고

## 관련 레시피

* [Slack 알림 자동화](/agent-chat/recipes/slack-notification) — 쿼리 결과를 Slack으로
* [보고서 자동 발행](/agent-chat/recipes/scheduled-report) — Scheduler + Flow 로 정기 리포트 발행
* [대량 문서 인덱싱·요약](/agent-chat/recipes/bulk-document-summarize) — 요약 메타를 PostgreSQL 에 적재
* [GitHub PR 리뷰 요약](/agent-chat/recipes/github-pr-review) — 다른 MCP 예시
* [레시피 목록](/agent-chat/recipes)