​
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

​
MySQL

  • 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

1

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

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
3

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 to OneSignal’s custom events format:
OneSignal FieldDescriptionRequired
nameevent_nameEvent identifierYes
external_iduser_idUser identifierYes
timestampevent_timestampWhen event occurredNo
propertiesevent_dataNo

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