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

> Sincronize eventos personalizados do Google Cloud SQL para o OneSignal para acionar Journeys automatizados e campanhas de mensagens personalizadas baseadas no comportamento do usuário.

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 = "Event metadata as JSON object"

## Visão Geral

A integração OneSignal + Google Cloud SQL permite a sincronização automática de eventos personalizados do seu banco de dados Cloud SQL para o OneSignal. Isso permite que você acione Journeys automatizados e campanhas de mensagens personalizadas baseadas em dados comportamentais do usuário armazenados no seu banco de dados PostgreSQL gerenciado.

***

## Requisitos

* 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

* Instância **Cloud SQL for PostgreSQL** (versão 11 ou superior recomendada)
* **Acesso ao banco de dados** com permissões de leitura para tabelas de eventos
* **Conectividade de rede** do OneSignal para sua instância Cloud SQL
* **Cloud SQL Auth proxy** para conexões seguras (recomendado)

***

## Configuração

<Steps>
  <Step title="Configurar acesso ao banco de dados Cloud SQL">
    Crie um usuário dedicado para o OneSignal com acesso somente leitura às tabelas de eventos:

    ```sql theme={null}
    -- Criar usuário OneSignal
    CREATE USER onesignal_reader WITH PASSWORD 'strong_unique_password';

    -- Conceder acesso ao schema
    GRANT USAGE ON SCHEMA event_data TO onesignal_reader;

    -- Conceder acesso à tabela
    GRANT SELECT ON ALL TABLES IN SCHEMA event_data TO onesignal_reader;

    -- Conceder acesso a tabelas futuras
    ALTER DEFAULT PRIVILEGES IN SCHEMA event_data
    GRANT SELECT ON TABLES TO onesignal_reader;
    ```
  </Step>

  <Step title="Configurar acesso à rede">
    Certifique-se de que o OneSignal possa se conectar à sua instância Cloud SQL:

    **Opção 1: Redes Autorizadas (IP Público)**

    * No Google Cloud Console, vá para **SQL > Instances**
    * Selecione sua instância → **Connections** → **Networking**
    * Adicione endereços IP do OneSignal às **Authorized networks**

    **Opção 2: IP Privado (Recomendado)**

    * Configure sua instância Cloud SQL com um IP privado
    * Use Cloud SQL Auth Proxy para conexões seguras
    * Garanta o peering VPC adequado ou regras de firewall

    **Opção 3: Cloud SQL Auth Proxy**

    * Baixe e configure o Cloud SQL Auth Proxy
    * Use autenticação de conta de serviço
    * Conecte através de túnel proxy seguro
  </Step>

  <Step title="Configurar Cloud SQL Auth Proxy (recomendado)">
    Para segurança aprimorada, use Cloud SQL Auth Proxy:

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

    # Tornar executável
    chmod +x cloud_sql_proxy

    # Executar proxy (substitua pelo nome de conexão da sua instância)
    ./cloud_sql_proxy -instances=PROJECT:REGION:INSTANCE=tcp:5432
    ```

    Crie uma conta de serviço com função 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="Adicionar integração no OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Selecione **Google Cloud SQL** e forneça:

    * **Instance Connection Name**: `PROJECT_ID:REGION:INSTANCE_ID`
    * **Database Name**: Nome do seu banco de dados de eventos
    * **Username**: `onesignal_reader`
    * **Password**: A senha criada no Passo 1
    * **SSL Mode**: `require` (recomendado para segurança)
    * **Connection Type**: Escolha entre Direct, Auth Proxy ou Private IP
  </Step>

  <Step title="Configurar consultas de dados de eventos">
    Defina a consulta SQL para recuperar dados de eventos do seu banco de dados 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
    ```

    Certifique-se de que suas tabelas de eventos incluam:

    * Nome/tipo do evento (String)
    * Identificador do usuário (String)
    * Timestamp do evento (Timestamp)
    * Propriedades do evento (JSON/JSONB)
  </Step>

  <Step title="Testar a conexão">
    Clique em **Test Connection** para verificar se o OneSignal pode se conectar à sua instância Cloud SQL e executar a consulta de eventos com sucesso.
  </Step>
</Steps>

***

### Event data mapping

Map your {PLATFORM_0} {DATA_TYPE_0} to OneSignal's custom events format:

| OneSignal Field | {COLUMN_HEADER_0} | Description                | Required |
| --------------- | ----------------- | -------------------------- | -------- |
| `name`          | `event_name`      | Event identifier           | Yes      |
| `external_id`   | `user_id`         | User identifier            | Yes      |
| `timestamp`     | `event_timestamp` | When event occurred        | No       |
| `properties`    | `event_data`      | {PROPERTIES_DESCRIPTION_0} | No       |

***

## Configuração Avançada

### Connection Pooling

Otimize conexões de banco de dados para sincronização de eventos de alto volume:

```sql theme={null}
-- Verificar limites de conexão atuais
SELECT * FROM pg_stat_activity WHERE datname = 'your_database';

-- Otimizar para conexões OneSignal
ALTER SYSTEM SET max_connections = 200;
ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';
```

### Otimização de Consultas

Melhore o desempenho de consultas de eventos:

```sql theme={null}
-- Criar índice no timestamp para filtragem eficiente
CREATE INDEX idx_events_created_at ON user_events(created_at);

-- Criar índice composto para consultas baseadas em usuário
CREATE INDEX idx_events_user_time ON user_events(user_id, created_at);

-- Analisar desempenho da consulta
EXPLAIN ANALYZE
SELECT event_name, user_id, created_at, properties
FROM user_events
WHERE created_at >= NOW() - INTERVAL '1 hour';
```

### Manipulação de Dados JSON

Se usar JSONB para propriedades de eventos, otimize consultas JSON:

```sql theme={null}
-- Criar índice GIN para propriedades JSON
CREATE INDEX idx_events_properties ON user_events USING GIN(properties);

-- Consultar propriedades JSON específicas
SELECT
    event_name,
    user_id,
    properties->>'purchase_amount' as amount,
    properties->>'product_id' as product
FROM user_events
WHERE properties->>'event_type' = 'purchase';
```

<Warning>
  Monitore o desempenho da sua instância Cloud SQL quando o OneSignal consultar dados de eventos. Considere usar réplicas de leitura para cargas de trabalho de análise para evitar impactar o desempenho de produção.
</Warning>

***

## FAQ

### Com que frequência o OneSignal sincroniza eventos do Cloud SQL?

O OneSignal sincroniza dados de eventos com base no seu cronograma configurado, com um intervalo mínimo de 15 minutos.

### Posso usar réplicas de leitura do Cloud SQL para sincronização de eventos?

Sim, usar réplicas de leitura é recomendado para isolar consultas de análise da carga de trabalho do seu banco de dados de produção.

### O que acontece se minha instância Cloud SQL estiver temporariamente indisponível?

O OneSignal tentará reconectar com backoff exponencial. A sincronização de eventos será retomada automaticamente assim que sua instância estiver acessível novamente.