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

# DB·벡터DB에서 데이터 조회

> 운영 중인 데이터베이스를 연동하여 AI로 활용할 수 있습니다.

<Card>
  MSSQL, PostgreSQL 등의 주요 데이터베이스와 Pinecone, Qdrant 등의 주요 벡터DB의 연동을 지원하며 데이터베이스 연동 시 AI가 테이블 구조(Schema)를 자동으로 분석하여 활용합니다. 각 데이터베이스의 연동 방식은 동일하며, 본 가이드는 PostgreSQL과 Pinecone 기준으로 설명합니다.
</Card>

<Info>
  커넥터로 연결된 데이터베이스는 읽기 전용으로만 조회됩니다.
</Info>

<Tip>
  애플리케이션 플랫폼에서 배포한 데이터베이스를 커넥터로 연동하여 사용할 수 있습니다. Porter AI에서 데이터베이스를 배포하고 운영하는 방법에 관한 내용은 [데이터베이스 운영](/ko/application-database) 페이지를 참고하세요.
</Tip>

## 데이터베이스 커넥터 설치

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/database01.png" />
</Frame>

> `스페이스 설정 > 커넥터`에서 연동하려는 데이터베이스를 선택한 후 커넥터를 설치합니다.

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/database02.png" />
</Frame>

## MSSQL 등의 데이터베이스 연결하기

### 접속 정보 입력

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/database03.png" />
</Frame>

> 커넥터 설정 탭에서 DB 연결 `추가하기` 버튼을 클릭하고 접속 주소를 입력하면 데이터베이스가 연결됩니다.

<Accordion title="접속 정보는 아래 형식의 URI로 입력합니다" defaultOpen={true}>
  <pre className="mt-4 p-4 bg-gray-50 dark:bg-gray-800 rounded-md text-sm font-mono text-gray-800 dark:text-gray-200">
    프로토콜://사용자:비밀번호@호스트:포트/데이터베이스이름
  </pre>

  | DB              | 예시                                    |
  | --------------- | ------------------------------------- |
  | PostgreSQL      | `postgresql://user:pass@host:5432/db` |
  | MSSQL           | `mssql://user:pass@host:1433/db`      |
  | MySQL / MariaDB | `mysql://user:pass@host:3306/db`      |
  | MongoDB         | `mongodb://user:pass@host:27017/db`   |

  <Warning>
    접속 정보는 화면상에 노출되지 않으며, 민감한 데이터는 암호화되어 안전하게 보관됩니다.
  </Warning>
</Accordion>

<Info>
  방화벽이 있는 DB는 연결 화면의 아웃바운드 IP를 허용 목록에 추가해야 합니다.
</Info>

### 고급 옵션 설정

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/database04.png" />
</Frame>

> 보안 통신이나 타임아웃 제어가 필요한 경우, `고급 옵션`을 펼쳐 관련 사항을 상세하게 설정할 수 있습니다.

| 설정 항목                | 설명                              | 기본값 / 권장사항                       |
| :------------------- | :------------------------------ | :------------------------------- |
| **SSL mode**         | DB와의 암호화 통신(SSL) 여부 및 수준 선택     | `접속 주소 설정 사용`                    |
| **서버 인증서 검증**        | 데이터베이스 서버의 SSL 인증서가 유효한지 검증     | `verify` 계열 옵션 사용 시 활성화          |
| **연결 타임아웃(ms)**      | DB 서버와 처음 연결을 시도할 때 대기할 최대 시간   | `15000` (15초)                    |
| **쿼리 타임아웃(ms)**      | AI가 DB에 조회를 요청한 후 응답을 기다릴 최대 시간 | `15000` (15초)                    |
| **Application name** | 접속 세션 로그에 표시될 식별 이름             | `porter-ai-postgres-integration` |

<AccordionGroup>
  <Accordion title="SSL mode는 어떤 걸 선택해야 하나요?">
    데이터베이스와의 암호화 통신(SSL) 수준을 사내 DB 보안 정책에 맞춰 선택할 수 있습니다.

    * **접속 주소 설정 사용**: 접속 주소(URI) 뒤에 붙은 파라미터(예: `?sslmode=...`)의 설정을 그대로 따릅니다.
    * **사용 안 함**: 암호화 없이 통신합니다. (보안에 취약하므로 로컬/테스트 환경에서만 권장)
    * **SSL 필수**: 항상 암호화 통신을 강제합니다. 단, 서버 인증서의 유효성은 검증하지 않습니다.
    * **CA 검증**: SSL 암호화 통신을 하며, 신뢰할 수 있는 기관(CA)에서 발급한 인증서인지 검증합니다.
    * **CA 및 호스트명 검증**: 가장 높은 보안 수준입니다. CA 검증뿐만 아니라, 접속 주소의 호스트명과 인증서에 적힌 호스트명이 일치하는지까지 엄격하게 검증합니다.
    * **SSL 필수, 인증서 검증 안 함**: 암호화 통신은 강제하지만, 인증서의 신뢰성이나 만료 여부 등은 체크하지 않고 연결합니다.
  </Accordion>

  <Accordion title="Application name은 어디에 사용되나요?">
    데이터베이스 관리자(DBA)가 DB 내 모니터링 도구나 프로세스 목록(`pg_stat_activity` 등)을 확인할 때, Porter AI를 통해 들어온 요청임을 쉽게 식별할 수 있도록 도와줍니다. 사내 보안 정책상 식별자 구분이 필요하다면 임의의 이름으로 변경하여 사용할 수 있습니다.
  </Accordion>
</AccordionGroup>

<Info>
  대용량 데이터 조회로 인해 타임아웃 에러가 발생하는 경우, `쿼리 타임아웃(ms)` 시간을 적절히 늘려주세요.
</Info>

### 스키마 정보 동기화

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/database05.png" />
</Frame>

> 연동한 데이터베이스의 테이블이 추가/삭제되거나 컬럼명이 변경된 경우, **스키마를 갱신**하면 AI가 변경된 데이터 구조를 기반으로 쿼리를 생성하여 답변에 활용합니다.

## Pinecone 등의 벡터DB 연결하기

### Pinecone 인덱스 연결

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/database06.png" />
</Frame>

> 커넥터의 `설정` 탭에서 `Pinecone index 연결`의 `추가하기` 버튼을 클릭한 후 인덱스 접속 정보를 입력합니다. Pinecone 인덱스는 최대 3개까지 연결할 수 있습니다.

| 설정 항목          | 설명                                                      |
| :------------- | :------------------------------------------------------ |
| **표시 이름**      | 연결된 인덱스를 구분하기 위한 이름입니다. 비워두면 Index host가 표시 이름으로 사용됩니다. |
| **Index host** | Pinecone 콘솔에서 확인한 인덱스의 호스트 주소를 입력합니다.                   |
| **API Key**    | Pinecone 인덱스에 접근할 수 있는 API 키를 입력합니다.                    |

<Info>
  방화벽이 적용된 Pinecone 환경에서는 연결 화면에 표시된 아웃바운드 IP를 허용 목록에 추가해야 합니다.
</Info>

<Warning>
  API Key는 화면상에 다시 노출되지 않으며, 민감한 데이터는 암호화되어 안전하게 보관됩니다.
</Warning>

### 고급 옵션 설정

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/database07.png" />
</Frame>

> 네임스페이스, 메타데이터 필드, API 버전과 임베딩 설정을 변경해야 하는 경우 `고급 옵션`을 펼쳐 설정합니다.

| 설정 항목                  | 설명                                               | 기본값 / 권장사항                             |
| :--------------------- | :----------------------------------------------- | :------------------------------------- |
| **기본 namespace**       | 검색할 기본 Pinecone 네임스페이스를 지정. 비워둘 경우 기본 네임스페이스를 사용 | 비워둠                                    |
| **API Version**        | Pinecone API 요청에 사용할 버전                          | `2025-10`                              |
| **본문 metadata key**    | 벡터 메타데이터에서 본문이 저장된 필드명을 지정                       | `content`                              |
| **제목 metadata key**    | 벡터 메타데이터에서 제목이 저장된 필드명을 지정                       | `title`                                |
| **URL metadata key**   | 벡터 메타데이터에서 원문 URL이 저장된 필드명을 지정                   | `url`                                  |
| **요청 타임아웃(ms)**        | 검색을 요청한 후 응답을 기다릴 최대 시간 설정                       | `15000` (15초)                          |
| **Embedding endpoint** | 검색어를 벡터로 변환할 임베딩 API의 엔드포인트                      | `https://api.openai.com/v1/embeddings` |
| **Embedding API Key**  | 임베딩 API 호출에 사용할 인증 키                             | 사용하는 임베딩 제공자의 API Key                  |
| **Embedding model**    | 검색어 임베딩에 사용할 모델                                  | `text-embedding-3-small`               |
| **차원(dimensions)**     | 생성할 임베딩 벡터의 차원                                   | 모델 기본값                                 |

<AccordionGroup>
  <Accordion title="기본 namespace는 언제 설정하나요?">
    하나의 Pinecone 인덱스에서 네임스페이스별로 데이터를 구분하여 관리하는 경우, AI가 기본적으로 검색할 네임스페이스를 지정합니다. 비워두면 Pinecone의 기본 네임스페이스를 검색합니다.
  </Accordion>

  <Accordion title="metadata key는 무엇인가요?">
    Pinecone 벡터에 함께 저장된 메타데이터 중 본문, 제목, 원문 URL에 해당하는 필드명을 지정합니다. 실제 인덱스에 저장된 메타데이터 구조와 동일하게 입력해야 검색 결과의 내용을 올바르게 가져올 수 있습니다.
  </Accordion>

  <Accordion title="Embedding 설정은 언제 필요한가요?">
    검색 요청에 벡터를 직접 전달하지 않는 경우, 사용자의 검색어를 벡터로 변환하기 위해 임베딩 설정을 사용합니다. Pinecone 인덱스에 저장된 벡터를 생성할 때 사용한 모델과 동일하거나 호환되는 임베딩 모델을 설정해야 합니다.
  </Accordion>
</AccordionGroup>

<Warning>
  `차원(dimensions)` 값이 Pinecone 인덱스의 차원 또는 임베딩 모델의 출력 차원과 일치하지 않으면 검색에 실패할 수 있습니다.
</Warning>

<Info>
  검색 요청이 시간 내에 완료되지 않는 경우 `요청 타임아웃(ms)` 값을 적절히 늘려주세요.
</Info>

### 인덱스 정보 갱신

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/database08.png" />
</Frame>

> 연결된 인덱스의 벡터 수, 네임스페이스 또는 차원 정보가 변경된 경우 더보기 메뉴에서 `Stats 갱신`을 선택합니다. 갱신된 인덱스 정보를 기반으로 AI가 벡터 검색을 수행합니다.

## DB 커넥터 활용

### 채팅창에서 사용

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/database09.png" />
</Frame>

> 채팅창에서 추가한 커넥터를 활성화하면, AI로 DB의 데이터를 활용할 수 있습니다.

### 에이전트와 봇의 도구로 사용

> 에이전트 설정 과정에서 추가한 데이터베이스 커넥터를 활성화하여 에이전트의 도구로 활용할 수 있습니다. 자세한 내용은 [커스텀 에이전트 설정](/ko/agents-and-bots#커스텀-에이전트-추가하기)을 참고하세요.

### Slack 등 메신저에서 사용

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/connector.png" />
</Frame>

> 커넥터를 통한 메신저 연동 시, 추가한 데이터베이스 커넥터를 활성화하면 연동한 메신저에서 DB의 데이터를 활용하여 AI가 답변합니다. 자세한 연동 방법은 아래의 링크에서 확인하세요.

<CardGroup cols={3}>
  <Card title="Discord Bot 연동" icon="discord" href="/ko/discord" />

  <Card title="Slack 워크스페이스 연동" icon="slack" href="/ko/slack" />

  <Card title="Telegram DM 연동" icon="telegram" href="/ko/telegram" />
</CardGroup>