> ## Documentation Index
> Fetch the complete documentation index at: https://control.datarelay.run/llms.txt
> Use this file to discover all available pages before exploring further.

# PostgreSQL DB에서 이벤트 수집

> 읽기 전용 DB 계정으로 SQL Query를 실행하고 Route를 통한 전송을 확인합니다.

# PostgreSQL 테이블의 로그를 수집하기

**목표:** Control의 **Database query (PostgreSQL)** Connector로 테스트 테이블을 읽어 HTTP Destination에 전달합니다. 사용자가 관리하는 **테스트 DB**가 필요합니다.

> [!NOTE]
>
> **화면 버전:** 표시된 이미지는 과거 Control UI 테스트 캡처입니다. 현재 제품의 기본 5단계 순서(Connect → Sample & Record Selection → Destinations → Route Processing → Deploy)를 우선하세요. [번호별 화면 가이드](https://control.datarelay.run/ko/use-cases/screen-walkthrough.md)에서 차이를 설명합니다.

## 실행 순서와 완료 기준

1. **필수 정보 준비:** Vendor 공식 API/연동 가이드에서 Endpoint, 인증 방식, 최소 권한, Pagination/Checkpoint, 응답 샘플을 확인합니다. 테스트용 비식별 이벤트와 실제 Destination 접속 정보를 준비합니다.
2. **모르는 항목은 ChatGPT로 정리:** 공개 API 문서와 비식별 샘플을 제공하고 Connector 필수 필드, 요청 예시, Event Root, Timestamp/ID, Cursor, 미확인 사항을 표로 요청합니다. **Token·비밀번호는 입력하지 않습니다.** ChatGPT 답변은 Vendor 문서와 Run Test로 검증합니다.
3. **Connector 생성:** Connectors → Create Connector에서 이 페이지의 해당 Source Type을 선택하고 실제 접속·인증 정보를 입력합니다. 저장하고 연결 테스트를 확인합니다.
4. **Destination 생성:** Destinations → Create에서 실제 수신기 유형(SYSLOG\_UDP/TCP/TLS 또는 WEBHOOK\_POST)을 선택하고 Host/Port/URL, TLS/인증을 입력합니다.
5. **Stream 생성:** Streams → Create → Connect에서 Connector를 선택하고 Source 요청/수집 조건을 지정합니다.
6. **샘플과 스키마:** Sample & Record Selection → Run Test에서 실제 레코드가 추출되는지 확인합니다. Record Root, Union Schema, Pagination 및 Checkpoint를 확정합니다.
7. **데이터 처리:** Destinations에서 Route를 연결하고 Route Processing에서 Mapping, Timestamp, Enrichment, Masking/Drop/Quarantine을 설정합니다. Tokenization은 **실제 제품에서 지원되는 경우에만** 사용합니다. Route Effective Status와 최종 출력값을 확인합니다.
8. **배포와 검증:** Deploy의 경고를 해결하고 Stream을 실행합니다. Run ID, Route Logs와 **실제 Destination 수신 기록**을 비교합니다. 이 세 가지가 일치해야 완료입니다.
9. **장애 대응:** 연결/인증 오류는 API 권한·TLS·Network·429를, 레코드 0건은 Record Root·Pagination을, 전송 실패는 [Delivery Incident](https://control.datarelay.run/ko/use-cases/delivery-incident.md)를, 필드 변경은 [Schema Drift](https://control.datarelay.run/ko/use-cases/schema-change.md)를 확인합니다.

### ChatGPT 질문 예시

> DataRelay Control에서 이 제품의 로그를 수집하려고 합니다. 아래 공개 API 가이드와 비식별 JSON 샘플을 기준으로 Connector 연결·인증 필수값, API Request/Pagination, Event Root, Timestamp/ID/Checkpoint, Mapping·민감 필드 보호, 장애 시 확인 항목을 표로 작성해 주세요. 문서에 없는 정보는 임의로 생성하지 말고 '확인 필요'로 표시하세요.

## 1. 테스트 테이블 준비

승인된 테스트 PostgreSQL DB에서 다음 SQL을 실행합니다.

```sql theme={null}
CREATE TABLE IF NOT EXISTS control_tutorial_events (
    id bigint PRIMARY KEY,
    occurred_at timestamptz NOT NULL,
    message text NOT NULL
);
INSERT INTO control_tutorial_events(id, occurred_at, message)
VALUES (101, '2026-10-18T00:00:00Z', 'synthetic db event')
ON CONFLICT (id) DO NOTHING;
```

별도 읽기 전용 DB 계정을 만들고 테이블에 `SELECT` 권한만 부여합니다. Control 서버에서 DB 포트에 접근 가능해야 합니다.

## 2. Connector 설정

1. \*\*Connectors → Create Connector → Database query (PostgreSQL)\*\*을 선택합니다.
2. **Connector Name** = `Lab PostgreSQL`, **DB type** = `PostgreSQL`을 지정합니다.
3. 실제 **Host**, **Port**(보통 5432), **Database name**, **Username**, **Password**를 입력합니다.
4. 서버 인증서 정책에 맞는 **SSL mode**를 설정합니다. 운영 인증서가 존재한다면 `VERIFY_FULL` 같은 검증 옵션을 사용합니다.
5. 저장하고 지원되는 DB Connectivity Test를 실행해 권한/TLS/네트워크를 확인합니다.

## 3. SQL Query와 Sample 확인

1. `/streams/new`에서 저장한 Connector를 선택합니다.
2. **Connect/Run Test**의 DB Discovery 또는 Query Builder에서 읽기 전용 Query를 구성합니다.

```sql theme={null}
SELECT id, occurred_at, message
FROM control_tutorial_events
ORDER BY occurred_at, id
```

3. **Run Test**에서 샘플 1건 이상을 확인하고 **Record Selection**에서 반환 레코드를 선택합니다.
4. Union Schema와 필드 타입을 확인합니다.
5. 증분 수집을 사용한다면 안정적인 Cursor/정렬과 ID Tie-breaker를 갖추고 Checkpoint를 명시적으로 검증합니다. 시간 필드가 있다고 자동으로 올바른 Cursor가 되는 것은 아닙니다.

![run-test — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/run-test.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=b608f03405b24c6b130a215599571177)

*그림 1. **실제 수집 테스트와 레코드 수 확인.** ① Run Test 실행 → ② HTTP 상태와 추출 레코드 수 확인 → ③ 성공하면 Record Selection으로 이동합니다. API 호출 성공만으로 Destination 전송이 증명되지는 않습니다.*

![record-selection — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/record-selection.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=196de1ecaf541296095434008afc05ad)

*그림 2. **레코드 경로와 Checkpoint 선택.** ① 추천 Record Path를 검토하고 ② JSON Tree에서 실제 이벤트 필드를 확인한 다음 ③ Checkpoint Field를 지정합니다. 이 화면은 미확정 상태이므로 경고가 표시되어 있습니다.*

## 4. 전송 확인

1. [테스트 HTTP 수신기](https://control.datarelay.run/ko/use-cases/lab-setup.md)를 `WEBHOOK_POST` Destination으로 선택합니다.
2. **Route Processing**에서 Mapping/Preview를 검토하고 **Deploy**를 수행합니다.
3. Stream을 실행한 후 **Logs**와 `received-9011.ndjson`에서 해당 DB 이벤트를 찾습니다.
4. 추가 가상 Row를 삽입한 뒤 재수집하여 중복이나 누락이 없는지도 검증합니다.

**완료 조건:** DB 테스트 Query 성공, Route 전달 로그, 독립 HTTP 수신 파일에 동일한 이벤트 존재.

![stream-actions — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/stream-actions.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=f5462ebde85e05d0c95ab32096a1a24e)

*그림 3. **Stream 생성 후 실행 및 로그 확인.** ① Stream 생성 결과 확인 → ② 실제 Runtime이 정상일 때 Start Stream → ③ View logs에서 Run과 Route 결과 확인. 캡처에는 Runtime API unavailable이 표시되므로 실제 전송 성공 증거는 아닙니다.*

## 실패 시

* 연결 실패: DB Host/Port, SSL, 계정 및 권한 확인
* Query 0건: DB/Schema/Table과 WHERE 조건 확인
* 중복/누락: 정렬, Checkpoint와 Tie-breaker 확인
* PostgreSQL이 아닌 DB: 현재 확인된 Query Runtime은 PostgreSQL 중심이므로 추가 엔진 지원을 가정하지 않습니다.

**관련:** [HTTP API 수집](https://control.datarelay.run/ko/use-cases/http-api.md), [Schema 변경](https://control.datarelay.run/ko/use-cases/schema-change.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.