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

# PostgreSQL

> PostgreSQL에서 OneSignal로 사용자 지정 이벤트를 동기화하여 사용자 행동에 따라 자동화된 Journey 및 개인화된 메시징 캠페인을 트리거합니다.

export const PLATFORM_0 = "PostgreSQL"

export const DATA_TYPE_0 = "columns"

export const COLUMN_HEADER_0 = "PostgreSQL Column"

export const PROPERTIES_DESCRIPTION_0 = "JSON object with event details"

## 개요

OneSignal + PostgreSQL 통합을 사용하면 PostgreSQL 데이터베이스에서 OneSignal로 사용자 지정 이벤트를 동기화하여 사용자 행동에 따라 자동화된 메시징 캠페인 및 Journey를 트리거할 수 있습니다.

***

## 요구 사항

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### PostgreSQL

* **PostgreSQL 9.6+** 또는 호환 가능한 데이터베이스
* 적절한 권한이 있는 **데이터베이스 사용자**
* OneSignal에서 PostgreSQL 인스턴스로의 **네트워크 액세스**
* 구조화된 행동 데이터가 포함된 **이벤트 테이블**

<Warning>
  OneSignal을 프로덕션 PostgreSQL 데이터베이스에 연결하는 것은 **권장하지 않습니다**. 이벤트 동기화 쿼리는 분석 특성이 있으며 프로덕션 성능에 영향을 줄 수 있습니다. 분석 워크로드용으로 설정된 데이터베이스에만 사용하세요.
</Warning>

***

## 설정

<Steps>
  <Step title="OneSignal용 전용 사용자 생성">
    적절한 권한이 있는 전용 사용자 계정을 생성하세요:

    ```sql theme={null}
    -- Create OneSignal user with strong password
    CREATE USER CENSUS WITH PASSWORD '<strong-unique-password>';

    -- Create private bookkeeping schema for sync state (skip if read-only mode)
    CREATE SCHEMA CENSUS;

    -- Grant full access to bookkeeping schema (skip if read-only mode)
    GRANT ALL ON SCHEMA CENSUS TO CENSUS;

    -- Ensure access to existing objects in bookkeeping schema (skip if read-only mode)
    GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA CENSUS TO CENSUS;
    ```
  </Step>

  <Step title="이벤트 데이터에 권한 부여">
    이벤트 데이터가 포함된 스키마에 대한 읽기 액세스를 제공하세요:

    ```sql theme={null}
    -- Grant schema access (repeat for each schema with event data)
    GRANT USAGE ON SCHEMA "<your_schema>" TO CENSUS;

    -- Grant read access to existing tables
    GRANT SELECT ON ALL TABLES IN SCHEMA "<your_schema>" TO CENSUS;

    -- Grant read access to future tables
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your_schema>" GRANT SELECT ON TABLES TO CENSUS;

    -- Grant execute permissions on functions
    GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA "<your_schema>" TO CENSUS;
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your_schema>" GRANT EXECUTE ON FUNCTIONS TO CENSUS;
    ```
  </Step>

  <Step title="OneSignal에 연결">
    OneSignal에서 **Data > Integrations**으로 이동하여 **Add Integration**을 클릭합니다.

    1. 목록에서 **PostgreSQL**을 선택하세요
    2. 연결 세부 정보를 입력하세요:
       * **Host:** PostgreSQL 서버 호스트 이름
       * **Port:** 일반적으로 5432
       * **Database:** 데이터베이스 이름
       * **Username:** `CENSUS`
       * **Password:** 생성한 비밀번호
    3. 연결을 테스트하세요
    4. 이벤트 데이터가 포함된 테이블을 구성하세요
  </Step>
</Steps>

***

### 이벤트 데이터 매핑

{PLATFORM_0} {DATA_TYPE_0}를 OneSignal의 사용자 지정 이벤트 형식에 매핑합니다:

| OneSignal 필드  | {COLUMN_HEADER_0} | 설명                         | 필수  |
| ------------- | ----------------- | -------------------------- | --- |
| `name`        | `event_name`      | 이벤트 식별자                    | Yes |
| `external_id` | `user_id`         | 사용자 식별자                    | Yes |
| `timestamp`   | `event_timestamp` | 이벤트가 발생한 시간                | No  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | No  |

### 예시 이벤트 테이블 스키마

```sql theme={null}
-- Example PostgreSQL event table
CREATE TABLE analytics.user_events (
    event_id SERIAL PRIMARY KEY,
    event_name VARCHAR(100) NOT NULL,
    user_id VARCHAR(255) NOT NULL,
    event_timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    event_data JSONB,
    session_id VARCHAR(255),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
```

### SQL 쿼리 모드

사용자 지정 SQL 쿼리를 작성하여 이벤트 데이터를 변환하세요:

```sql theme={null}
-- Example: Recent purchase events
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_data
FROM analytics.user_events
WHERE event_timestamp >= NOW() - INTERVAL '7 days'
    AND event_name = 'purchase'
ORDER BY event_timestamp DESC;
```

***

## 고급 네트워크 구성

OneSignal은 고급 네트워킹 제어를 사용하여 PostgreSQL 인스턴스에 연결할 수 있습니다:

* **IP 허용 목록**: 방화벽 및 `pg_hba.conf`에 OneSignal의 IP 주소를 추가하세요
* **SSH 터널링**: 프라이빗 네트워크를 위해 베스천 호스트를 통해 연결하세요
* **VPC 구성**: 클라우드 환경 내에서 직접 연결하세요
* **TLS 암호화**: SSL/TLS를 사용하여 안전한 연결을 구성하세요

### SSH 터널 설정

프라이빗 네트워크의 PostgreSQL 인스턴스의 경우:

1. **SSH 사용자 생성**: SSH 호스트에서 전용 사용자를 설정하세요
2. **터널 구성**: OneSignal 통합 설정에서 "Use SSH Tunnel"을 활성화하세요
3. **키 페어 설치**: OneSignal의 공개 키를 `~/.ssh/authorized_keys`에 추가하세요
4. **연결 테스트**: 터널 연결을 확인하세요

***

## 참고 사항

* **다중 스키마**: 이벤트 데이터가 포함된 각 스키마에 대해 권한 부여를 반복하세요
* **교차 스키마 참조가 있는 뷰**: 이전 PostgreSQL 버전에서는 추가 읽기 권한이 필요할 수 있습니다
* **Azure PostgreSQL**: Azure 인스턴스의 경우 `username@hostname` 형식을 사용하세요
* **AWS RDS**: 표준 `username` 형식을 사용하세요
* **성능**: 대규모 이벤트 처리를 위해 읽기 복제본 사용을 고려하세요

***

## 제한 사항

* 분석 쿼리 오버헤드로 인해 프로덕션 데이터베이스에 연결하지 마세요
* 복잡한 교차 스키마 쿼리에는 추가 권한이 필요할 수 있습니다
* 고빈도 이벤트 처리에는 연결 풀링을 권장합니다

***

## FAQ

### 읽기 전용 모드를 사용해야 하나요?

더 간단한 설정을 선호하고 OneSignal이 테이블을 생성하도록 허용할 수 없는 경우 **읽기 전용 모드**를 사용하세요. 대규모 이벤트 데이터 세트로 더 나은 성능을 원하면 **전체 모드**를 사용하세요.

### 여러 이벤트 스키마를 어떻게 처리하나요?

이벤트 데이터가 포함된 각 스키마에 대해 권한 부여 명령을 반복하세요. OneSignal은 단일 연결 내에서 여러 스키마에서 읽을 수 있습니다.