> ## 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.

# Google Cloud SQL

> Google Cloud SQL에서 OneSignal로 사용자 지정 이벤트를 동기화하여 사용자 행동을 기반으로 자동화된 저니와 개인화된 메시징 캠페인을 트리거하세요.

export const PLATFORM_0 = "Google Cloud SQL"

export const DATA_TYPE_0 = "event table fields"

export const COLUMN_HEADER_0 = "Cloud SQL Field"

export const PROPERTIES_DESCRIPTION_0 = "JSON 객체로 된 이벤트 메타데이터"

## 개요

OneSignal + Google Cloud SQL 통합은 Cloud SQL 데이터베이스에서 OneSignal로 사용자 지정 이벤트를 자동으로 동기화할 수 있게 합니다. 이를 통해 관리형 PostgreSQL 데이터베이스에 저장된 사용자 행동 데이터를 기반으로 자동화된 저니와 개인화된 메시징 캠페인을 트리거할 수 있습니다.

***

## 요구 사항

* 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)

### Google Cloud SQL

* **Cloud SQL for PostgreSQL** 인스턴스 (버전 11 이상 권장)
* 이벤트 테이블에 대한 읽기 권한이 있는 **데이터베이스 액세스**
* OneSignal에서 Cloud SQL 인스턴스로의 **네트워크 연결**
* 보안 연결을 위한 **Cloud SQL Auth proxy** (권장)

***

## 설정

<Steps>
  <Step title="Cloud SQL 데이터베이스 액세스 구성">
    이벤트 테이블에 대한 읽기 전용 액세스 권한이 있는 OneSignal 전용 사용자를 생성합니다:

    ```sql theme={null}
    -- Create OneSignal user
    CREATE USER onesignal_reader WITH PASSWORD 'strong_unique_password';

    -- Grant schema access
    GRANT USAGE ON SCHEMA event_data TO onesignal_reader;

    -- Grant table access
    GRANT SELECT ON ALL TABLES IN SCHEMA event_data TO onesignal_reader;

    -- Grant access to future tables
    ALTER DEFAULT PRIVILEGES IN SCHEMA event_data
    GRANT SELECT ON TABLES TO onesignal_reader;
    ```
  </Step>

  <Step title="네트워크 액세스 구성">
    OneSignal이 Cloud SQL 인스턴스에 연결할 수 있는지 확인합니다:

    **옵션 1: 승인된 네트워크 (공개 IP)**

    * Google Cloud 콘솔에서 **SQL > 인스턴스**로 이동합니다
    * 인스턴스 선택 → **연결** → **네트워킹**
    * OneSignal IP 주소를 **승인된 네트워크**에 추가합니다

    **옵션 2: 비공개 IP (권장)**

    * 비공개 IP로 Cloud SQL 인스턴스를 구성합니다
    * 보안 연결을 위해 Cloud SQL Auth Proxy를 사용합니다
    * 적절한 VPC 피어링 또는 방화벽 규칙을 확인합니다

    **옵션 3: Cloud SQL Auth Proxy**

    * Cloud SQL Auth Proxy를 다운로드하고 구성합니다
    * 서비스 계정 인증을 사용합니다
    * 보안 프록시 터널을 통해 연결합니다
  </Step>

  <Step title="Cloud SQL Auth Proxy 설정 (권장)">
    보안 강화를 위해 Cloud SQL Auth Proxy를 사용합니다:

    ```bash theme={null}
    # Download Cloud SQL Auth Proxy
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64

    # Make executable
    chmod +x cloud_sql_proxy

    # Run proxy (replace with your instance connection name)
    ./cloud_sql_proxy -instances=PROJECT:REGION:INSTANCE=tcp:5432
    ```

    Cloud SQL Client 역할로 서비스 계정을 생성합니다:

    ```bash theme={null}
    gcloud iam service-accounts create onesignal-cloudsql
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:onesignal-cloudsql@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/cloudsql.client"
    ```
  </Step>

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

    **Google Cloud SQL**을 선택하고 다음을 제공합니다:

    * **Instance Connection Name**: `PROJECT_ID:REGION:INSTANCE_ID`
    * **Database Name**: 이벤트 데이터베이스 이름
    * **Username**: `onesignal_reader`
    * **Password**: 1단계에서 생성한 비밀번호
    * **SSL Mode**: `require` (보안을 위해 권장)
    * **Connection Type**: Direct, Auth Proxy 또는 Private IP 중 선택
  </Step>

  <Step title="이벤트 데이터 쿼리 구성">
    Cloud SQL 데이터베이스에서 이벤트 데이터를 검색하기 위한 SQL 쿼리를 정의합니다:

    ```sql theme={null}
    SELECT
        event_name,
        user_id,
        created_at as event_timestamp,
        properties as event_payload
    FROM event_data.user_events
    WHERE created_at >= CURRENT_TIMESTAMP - INTERVAL '1 hour'
    ORDER BY created_at DESC
    ```

    이벤트 테이블에 다음이 포함되어 있는지 확인합니다:

    * 이벤트 이름/유형 (String)
    * 사용자 식별자 (String)
    * 이벤트 타임스탬프 (Timestamp)
    * 이벤트 속성 (JSON/JSONB)
  </Step>

  <Step title="연결 테스트">
    **연결 테스트**를 클릭하여 OneSignal이 Cloud SQL 인스턴스에 연결하고 이벤트 쿼리를 성공적으로 실행할 수 있는지 확인합니다.
  </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}
-- Check current connection limits
SELECT * FROM pg_stat_activity WHERE datname = 'your_database';

-- Optimize for OneSignal connections
ALTER SYSTEM SET max_connections = 200;
ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';
```

### 쿼리 최적화

이벤트 쿼리 성능을 개선합니다:

```sql theme={null}
-- Create index on timestamp for efficient filtering
CREATE INDEX idx_events_created_at ON user_events(created_at);

-- Create composite index for user-based queries
CREATE INDEX idx_events_user_time ON user_events(user_id, created_at);

-- Analyze query performance
EXPLAIN ANALYZE
SELECT event_name, user_id, created_at, properties
FROM user_events
WHERE created_at >= NOW() - INTERVAL '1 hour';
```

### JSON 데이터 처리

이벤트 속성에 JSONB를 사용하는 경우 JSON 쿼리를 최적화합니다:

```sql theme={null}
-- Create GIN index for JSON properties
CREATE INDEX idx_events_properties ON user_events USING GIN(properties);

-- Query specific JSON properties
SELECT
    event_name,
    user_id,
    properties->>'purchase_amount' as amount,
    properties->>'product_id' as product
FROM user_events
WHERE properties->>'event_type' = 'purchase';
```

<Warning>
  OneSignal이 이벤트 데이터를 쿼리할 때 Cloud SQL 인스턴스의 성능을 모니터링하세요. 프로덕션 성능에 영향을 주지 않도록 분석 워크로드에 읽기 복제본 사용을 고려하세요.
</Warning>

***

## FAQ

### OneSignal은 Cloud SQL에서 얼마나 자주 이벤트를 동기화하나요?

OneSignal은 구성된 일정에 따라 이벤트 데이터를 동기화하며, 최소 간격은 15분입니다.

### 이벤트 동기화에 Cloud SQL 읽기 복제본을 사용할 수 있나요?

예, 프로덕션 데이터베이스 워크로드에서 분석 쿼리를 격리하기 위해 읽기 복제본을 사용하는 것이 권장됩니다.

### Cloud SQL 인스턴스를 일시적으로 사용할 수 없으면 어떻게 되나요?

OneSignal은 지수 백오프로 연결을 재시도합니다. 인스턴스에 다시 액세스할 수 있게 되면 이벤트 동기화가 자동으로 재개됩니다.