Skip to main content
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.
  1. In PlanetScale, navigate to your database and branch, and click the “Connect” button.
  2. Click “Create new role” and keep “User-defined role” selected.
  3. Select the postgres permission.
  4. 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.

Run the sync

  1. Install the package:
  2. Set your environment variables:
  3. Run init, backfill, and listen:
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:

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.

Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.