MySQL
Mirror your WorkOS data into MySQL and query it with SQL.
The MySQL destination uses the same backfill, events API tail, and reconciliation as the sync engine. You’ll need:
- A WorkOS account and an API key for the environment you want to mirror
- A MySQL database meeting the package’s compatibility requirements; MariaDB is not supported
- A runtime supported by the MySQL package, or a container runtime
The database user needs CREATE, ALTER, INDEX, CREATE VIEW, CREATE TEMPORARY TABLES, SELECT, INSERT, UPDATE, and DELETE on the mirror database. Create the database beforehand, or grant the user permission to create it.
The package includes the engine, a MySQL destination, and the workos-sync-mysql command. See the MySQL package README for the full command and configuration reference. For Docker images, tags, and usage, follow the repository’s container instructions.
Set the connection string and API key as managed secrets:
WORKOS_SYNC_SCHEMA selects the database for all mirror tables and defaults to workos. The database in the DATABASE_URL path does not select the mirror database. On a host that provides a database for you, set WORKOS_SYNC_SCHEMA to that database’s name.
For a remote database, set WORKOS_SYNC_MYSQL_SSL_CA to the provider’s CA certificate, as PEM or base64-encoded PEM, to require TLS and verify the server certificate. The library equivalent is the sslCa destination option.
Rows are labeled production in their _env column by default. For another environment, set WORKOS_ENVIRONMENT_NAME before the first write. This label is part of every primary key and must not change once you have data.
init creates the database if needed, the mirror tables, their _live views, and the bookkeeping tables. It is safe to run repeatedly. Backfill loads current objects from the REST list endpoints and records a cursor so changes during the initial load are not missed.
If backfill is interrupted, resume from its last checkpoint:
For hosts that gate schema changes, use init --print-sql and apply the DDL through the host’s change process before running init. See the MySQL command line guide for the hosted-database workflow.
Leave this running as a service. It polls the events API from the stored cursor, applies changes, and finishes its current batch on SIGINT or SIGTERM. Only one listener writes per environment; another waits for the writer lease. For scheduled polling instead, npx workos-sync-mysql tick polls once and exits.
Read _live views to exclude deleted objects. Join on _env as well as the object id, because a database can mirror several environments.
The tables and _live views follow the same conventions as Postgres, with MySQL-specific types:
_rawisJSON. Fields without a generated column are queryable with MySQL JSON paths, such as_raw->>'$.custom_attributes.department'.- Key columns are
VARCHAR(191), other text columns areTEXT, and boolean values areTINYINT(1)(1or0). - Timestamps are
DATETIME(6)in UTC. UseUTC_TIMESTAMP(6)for time comparisons, or set your session to UTC. - Invalid values in generated projections become SQL
NULL, while the original value remains in_raw. Invalid key values are rejected and quarantined rather than silently changing a row’s identity.
The mirror is an eventually consistent read model. Use it for joins, lists, and analytics, not authorization decisions or reading back an object you just created. Send writes to the WorkOS API.
The command reports missed creates and deletes and exits with status 2 when it finds drift. To insert missing objects and tombstone missed deletes, run npx workos-sync-mysql reconcile --repair.
Check npx workos-sync-mysql status for the cursor, poll age, and per-stream counts. The operations guide covers monitoring, reconciliation schedules, and recovery; replace workos-sync-postgres with workos-sync-mysql in its commands.
See the library guide to reuse a mysql2 pool, configure TLS, or customize the destination.