Skip to main content

Overview

The OneSignal + PostgreSQL integration enables syncing of custom events from your PostgreSQL database to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

What data syncs

Data moves one way, from PostgreSQL into OneSignal. The PostgreSQL integration does not create users or subscriptions, set Tags, or import audiences. OneSignal does not send message events to PostgreSQL. To send message events to a system you control, use Event Streams. See what data each integration syncs to compare integrations.

Requirements

OneSignal

  • A paid OneSignal plan. This integration isn’t available on the Free plan. See plans.

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
We strongly recommend against connecting OneSignal to a production PostgreSQL database. Event sync queries are analytical in nature and may impact production performance. Use with databases set up for analytic workloads only.

Setup

1

Create dedicated user for OneSignal

Create a dedicated user account with appropriate permissions:
2

Grant permissions to event data

Provide read access to schemas containing your event data:
3

Connect to OneSignal

In OneSignal, go to Data > Integrations and click Add Integration.
  1. Select PostgreSQL from the list
  2. Enter your connection details:
    • Host: Your PostgreSQL server hostname
    • Port: Usually 5432
    • Database: Your database name
    • Username: CENSUS
    • Password: The password you created
  3. Test the connection
  4. Configure which tables contain your event data

Event data mapping

Map your PostgreSQL columns to OneSignal’s custom events format:
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

SQL Query Mode

Write custom SQL queries to transform your event data:

Advanced Network Configuration

OneSignal can connect to PostgreSQL instances using advanced networking controls:
  • IP Allow Lists: Add OneSignal’s IP addresses to your firewall and pg_hba.conf
  • SSH Tunneling: Connect through a bastion host for private networks
  • VPC Configuration: Direct connection within cloud environments
  • TLS Encryption: Secure connections using SSL/TLS

SSH Tunnel Setup

For PostgreSQL instances on private networks:
  1. Create SSH user: Set up a dedicated user on your SSH host
  2. Configure tunnel: Enable “Use SSH Tunnel” in OneSignal integration settings
  3. Install keypair: Add OneSignal’s public key to ~/.ssh/authorized_keys
  4. Test connection: Verify tunnel connectivity

Notes

  • Multiple Schemas: Repeat permission grants for each schema containing event data
  • Views with Cross-Schema References: May require additional read permissions in older PostgreSQL versions
  • Azure PostgreSQL: Use username@hostname format for Azure instances
  • AWS RDS: Use standard username format
  • Performance: Consider using read replicas for large-scale event processing

Limitations

  • Avoid connecting to production databases due to analytical query overhead
  • Complex cross-schema queries may require additional permissions
  • Connection pooling recommended for high-frequency event processing

FAQ

Should I use read-only mode?

Use read-only mode if you prefer simpler setup and can’t allow OneSignal to create tables. Use full mode for better performance with large event datasets.

How do I handle multiple event schemas?

Repeat the permission grant commands for each schema containing event data. OneSignal can read from multiple schemas within a single connection.