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

***

## 要求

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

### PostgreSQL

* **PostgreSQL 9.6+** or compatible database
* **Database user** with appropriate permissions
* **Network access** from OneSignal to your PostgreSQL instance
* **Event tables** containing structured behavioral data

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

    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`      | 事件标识符                      | 是  |
| `external_id` | `user_id`         | 用户标识符                      | 是  |
| `timestamp`   | `event_timestamp` | 事件发生时间                     | 否  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | 否  |

### 示例事件表架构

```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 Allow Lists**: 将 OneSignal 的 IP 地址添加到您的防火墙和 `pg_hba.conf`
* **SSH Tunneling**: 通过保垒主机连接私有网络
* **VPC Configuration**: 云环境内的直接连接
* **TLS Encryption**: 使用 SSL/TLS 的安全连接

### SSH 隧道设置

对于私有网络上的 PostgreSQL 实例：

1. **Create SSH user**: 在您的 SSH 主机上设置专用用户
2. **Configure tunnel**: 在 OneSignal 集成设置中启用"使用 SSH 隧道"
3. **Install keypair**: 将 OneSignal 的公钥添加到 `~/.ssh/authorized_keys`
4. **Test connection**: 验证隧道连接性

***

## 注意事项

* **Multiple Schemas**: 为每个包含事件数据的架构重复权限授予
* **Views with Cross-Schema References**: 在旧版本的 PostgreSQL 中可能需要额外的读取权限
* **Azure PostgreSQL**: 对于 Azure 实例使用 `username@hostname` 格式
* **AWS RDS**: 使用标准的 `username` 格式
* **Performance**: 考虑在大规模事件处理时使用只读副本

***

## 限制

* 由于分析查询开销，避免连接到生产数据库
* 复杂的跨架构查询可能需要额外的权限
* 对于高频率事件处理建议使用连接池

***

## FAQ

### 我应该使用只读模式吗？

如果您希望设置更简单并且不允许 OneSignal 创建表，请使用**只读模式**。对于大型事件数据集，使用**完整模式**获得更好的性能。

### 如何处理多个事件架构？

为每个包含事件数据的架构重复执行权限授予命令。OneSignal 可以在单个连接中从多个架构读取数据。