Mirror WorkOS data into PlanetScale Postgres with the @workos/sync-postgres package and query it with SQL.
WorkOS Sync Engine keeps a copy of your WorkOS data, such as users and organizations, in your own database.
It connects to PlanetScale Postgres over a standard Postgres connection with the @workos/sync-postgres package.
For the full command and configuration reference, see the @workos/sync-postgres README.
Set up Sync Engine
Requirements
A PlanetScale Postgres database
A WorkOS account and API key
Node.js 22 or later, to run the workos-sync-postgres command
Network access
Sync Engine runs on your own infrastructure and connects to PlanetScale from there.
If your database uses IP restrictions, allow the IP addresses of the host that runs the sync.
Create a role
Sync Engine’s init command creates a workos schema, so the role it uses needs CREATE on the database, which the postgres permission grants.
Without it, init fails with permission denied for database postgres.
In PlanetScale, navigate to your database and branch, and click the “Connect” button.
Click “Create new role” and keep “User-defined role” selected.
Select the postgres permission.
Click “Create role” and copy the connection URI. PlanetScale only shows the password once.
Set the connection string
If the connection URI includes sslrootcert=system, remove it and keep sslmode=verify-full.
The pg driver that Sync Engine uses reads sslrootcert as a file name, so every command otherwise fails with ENOENT: no such file or directory, open 'system'.
Without it, sslmode=verify-full still verifies the server’s certificate and host name.
Set WORKOS_ENVIRONMENT_NAME to the name of the WorkOS environment your API key belongs to, such as staging, before you run any command.
Use the same value for every command.
Sync Engine labels every row with _env = 'production' by default, even when you use a test API key.
Changing the label later doesn’t relabel existing rows.
Sync Engine writes a second copy of each row, and the _live views return both.
Sync overview
init creates the workos schema with its tables and views.
backfill loads the data that already exists in WorkOS.
listen applies new WorkOS events as they happen, and keeps running until you stop it.
Query the mirror
Each mirror table in the workos schema except events and auth_attempts has a _live view that leaves out deleted rows.
Query the views:
SELECT id, email FROM workos.users_live;
Branches
Each branch needs its own credentials.
A branch created from the Branches page has no schema or data, so create a role on it and run init and backfill.