> ## 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，基于用户行为触发自动化 Journeys 和个性化消息活动。

export const PLATFORM_0 = "Google Cloud SQL"

export const DATA_TYPE_0 = "事件表字段"

export const COLUMN_HEADER_0 = "Cloud SQL 字段"

export const PROPERTIES_DESCRIPTION_0 = "作为 JSON 对象的事件元数据"

## 概述

OneSignal + Google Cloud SQL 集成可以实现从您的 Cloud SQL 数据库自动同步自定义事件到 OneSignal。这允许您基于存储在托管 PostgreSQL 数据库中的用户行为数据触发自动化 Journeys 和个性化消息活动。

***

## 要求

* 访问自定义事件（目前处于测试阶段）
* [升级账户计划](https://onesignal.com/pricing)（免费应用不可用）。

### 谷歌云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 中，前往 **数据 > 集成**，然后点击 **添加集成**。

    选择 **Google Cloud SQL** 并提供：

    * **实例连接名称**：`PROJECT_ID:REGION:INSTANCE_ID`
    * **数据库名称**：您的事件数据库名称
    * **用户名**：`onesignal_reader`
    * **密码**：在步骤1中创建的密码
    * **SSL 模式**：`require`（出于安全考虑推荐）
    * **连接类型**：在直接、Auth Proxy 或私有 IP 之间选择
  </Step>

  <Step title="配置事件数据查询">
    定义 SQL 查询以从您的 Cloud 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
    ```

    确保您的事件表包含：

    * 事件名称/类型（字符串）
    * 用户标识符（字符串）
    * 事件时间戳（时间戳）
    * 事件属性（JSON/JSONB）
  </Step>

  <Step title="测试连接">
    点击**测试连接**验证 OneSignal 可以连接到您的 Cloud SQL 实例并成功执行事件查询。
  </Step>
</Steps>

***

### 事件数据映射

将您的 {PLATFORM_0} {DATA_TYPE_0} 映射到 OneSignal 的自定义事件格式：

| OneSignal 字段  | {COLUMN_HEADER_0} | 描述                         | 必需 |
| ------------- | ----------------- | -------------------------- | -- |
| `name`        | `event_name`      | 事件标识符                      | 是  |
| `external_id` | `user_id`         | 用户标识符                      | 是  |
| `timestamp`   | `event_timestamp` | 事件发生时间                     | 否  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | 否  |

***

## 高级配置

### 连接池

为大量事件同步优化数据库连接：

```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>

***

## 常见问题

### OneSignal 多久从 Cloud SQL 同步一次事件？

OneSignal 根据您配置的计划同步事件数据，最小间隔为 15 分钟。

### 我可以使用 Cloud SQL 读取副本进行事件同步吗？

是的，建议使用读取副本来将分析查询与生产数据库工作负载隔离。

### 如果我的 Cloud SQL 实例暂时不可用会发生什么？

OneSignal 将使用指数退避重试连接。一旦您的实例可再次访问，事件同步将自动恢复。