MySQL

Overview

The OneSignal + MySQL integration enables syncing of custom events from your MySQL database to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior. MySQL is a widely-used open-source relational database management system, ideal for storing structured event data that can power personalized messaging campaigns.

Requirements

Access to Event Streams for outbound message events (Plan limitations and overages apply)
Access to Custom Events for inbound event syncing (Plan limitations and overages apply)
Updated Account Plan (not available on free apps)

MySQL Community 5.7 or later, or recent versions of MariaDB
Event tables containing structured behavioral data
Network connectivity from OneSignal to your MySQL instance
TLS v1.2 or greater supported

Setup

Create dedicated user for OneSignal

Create a dedicated user account with read-only permissions:

-- Create census user with ability to sign in with a password
CREATE USER CENSUS IDENTIFIED BY '<strong, unique password>';

-- Grant read-only access to your event schema
GRANT SELECT ON <your_schema>.* TO CENSUS;

If you have multiple schemas that contain event data, repeat the GRANT SELECT statement for each schema.

Configure OneSignal connection

In OneSignal, go to Data > Integrations and click Add Integration.Select MySQL and provide your connection details:

Host: Your MySQL server hostname
Port: MySQL port (typically 3306)
Database: Database name containing your event tables
Username: CENSUS
Password: The password you created above

Test connection

Click Test Connection to verify OneSignal can successfully connect to your MySQL database and access your event tables.

Event data mapping

Map your MySQL event data to OneSignal’s custom events format:

OneSignal Field	MySQL Column	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`	Event properties as JSON	No

The Sync Key is the column you designate as the unique identifier for each row during sync. OneSignal uses it to detect whether a row has already been processed, so re-syncing your data doesn’t create duplicate events. Choose a column with a unique text value per row. Don’t use a boolean or a value that repeats across rows.

Example Event Table Schema

CREATE TABLE user_events (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    event_name VARCHAR(100) NOT NULL,
    user_id VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    event_data JSON,
    session_id VARCHAR(255),
    device_type VARCHAR(50)
);

Table Mode

Select your event table directly and OneSignal will sync all rows as individual events.

SQL Query Mode

Write custom SQL queries to transform your event data:

-- Example: Recent high-value events
SELECT
    event_name,
    user_id,
    created_at as timestamp,
    event_data as payload
FROM user_events
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
    AND JSON_EXTRACT(event_data, '$.value') > 100
ORDER BY created_at DESC;

Advanced Network Configuration

OneSignal can successfully connect to MySQL instances using advanced networking controls including region constraints, IP address allow lists, or SSH Tunneling. OneSignal supports MySQL with TLS versions 1.2 and greater for secure connections.

FAQ

Which MySQL versions are supported?

OneSignal supports MySQL Community 5.7 or later, as well as recent versions of MariaDB.

Can I connect to MySQL in a private network?

Yes, OneSignal supports SSH tunneling and IP allow lists for connecting to MySQL instances in private networks or behind firewalls.

First steps & settings

Message channels

Journeys

OneSignal AI

Audience & events

Analytics & Integrations

Privacy & Security

MySQL

Overview

Requirements

MySQL

Setup

Event data mapping

Example Event Table Schema

Table Mode

SQL Query Mode

Advanced Network Configuration

FAQ

Which MySQL versions are supported?

Can I connect to MySQL in a private network?

​Overview

​Requirements

​MySQL

​Setup

​Event data mapping

​Example Event Table Schema

​Table Mode

​SQL Query Mode

​Advanced Network Configuration

​FAQ

​Which MySQL versions are supported?

​Can I connect to MySQL in a private network?

Overview

Requirements

MySQL

Setup

Event data mapping

Example Event Table Schema

Table Mode

SQL Query Mode

Advanced Network Configuration

FAQ

Which MySQL versions are supported?

Can I connect to MySQL in a private network?