Skip to content

feat: Add a MySQL table prefix and fix PlanetScale's findings - #60

Merged
gjtorikian merged 10 commits into
mainfrom
fix/planetscale-findings
Nov 17, 2026
Merged

gjtorikian merged 10 commits into
mainfrom
fix/planetscale-findings

Conversation

@gjtorikian

@gjtorikian gjtorikian commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Host name verification. With a CA set, @workos/sync-mysql verified the certificate chain but not the host name: mysql2 checks it only when verifyIdentity is on. With the operating system's bundle as the CA, any publicly trusted certificate passed for any host. sslCa and an ssl={...} object in the connection string now both turn the check on. The mysql2 floor moves to 3.24.6, the version this was verified against.
  • A command line whose exits can be trusted. reconcile exits 1 when a stream could not be compared, where it exited 0. Output is flushed before the process exits, so init --print-sql through a pipe is no longer cut at 64 KB. status only reads, and reports initialized: false on an empty database instead of creating the mirror. A CA variable that is set but empty is refused.
  • Reconcile under a transaction limit. The MySQL diff held one transaction open for a stream's whole listing, and PlanetScale ends a transaction after 20 seconds. Only the capture of the live ids runs in a transaction now; the listing runs with none open.
  • init --repair. It stopped at the recorded fingerprint like plain init, so a dropped view or column stayed missing while it printed schema ready. A repair now forces the whole pass, in both SQL packages.
  • Table prefix. tablePrefix, --table-prefix and WORKOS_SYNC_TABLE_PREFIX for @workos/sync-mysql, so the mirror can share a Vitess database with an application that already has a users table. Without a prefix, every name, statement and fingerprint is unchanged.

The PlanetScale guide is corrected for D1 to D9 and L2, and the package READMEs follow the behavior changes.

Behavior changes

  • reconcile exits 1 when any stream failed, in every destination's command. A stream that a page budget left for a later slice is still exit 0.
  • status no longer applies the schema on Postgres and MySQL, and EnvironmentStatus gains initialized. MongoDB and ClickHouse do not implement ready() yet, so their status behaves as before.
  • A CA variable that is set but empty is an error, in every destination's command. It used to be read as unset.
  • MySQL connections that ask for verified TLS now require a DNS hostname and fail when the certificate does not name it. IPv4 and IPv6 URLs are rejected before connecting: mysql2 3.24.6 verifies localhost instead of the target IP. The URL opt-out is "verifyIdentity":false in its ssl object, only when WORKOS_SYNC_MYSQL_SSL_CA is unset; an explicit CA always requires verification. A pre-built pool carries its own TLS settings.
  • init --repair runs the full schema pass even when the fingerprint is recorded. A forced pass that finds drift it cannot repair removes the recorded fingerprint.

…status read-only

Four findings from PlanetScale's testing of the sync against Vitess, all in
the command line and engine every destination shares.

reconcile exited 0 when a stream's diff threw. The stream was reported with
`complete: false`, but only drift changed the exit code, so a run in which
every stream was refused by the database passed as a scheduled check. A
failed stream now carries `failed: true` and the command exits 1. A stream
a page budget left for a later slice is still exit 0.

Output through a pipe was cut off at 64 KB. `exitWith` called
`process.exit` straight after writing, and a pipe is written asynchronously
on macOS: `init --print-sql | cat` wrote 65,536 of 154,588 bytes and exited
0. The exit now waits for stdout and stderr to drain.

A CA variable that was set but empty was read as unset, which is what a
mistyped `$(cat path)` leaves behind. It is now refused by name.

status applied the schema before reading, so a status check on an empty
database created every table and view. A destination can now implement
`ready()`, and status asks it instead: when the tables are not there it
reports `initialized: false` and creates nothing. Destinations without
`ready()` behave as before.
…tion before listing

Two findings from PlanetScale's testing against Vitess.

With a CA set, the certificate chain was verified but the host name was
not. mysql2 checks it only when `ssl.verifyIdentity` is on, and the
destination passed `{ ca, rejectUnauthorized: true }`. With the operating
system's bundle as the CA, any publicly trusted certificate passed for any
host. `sslCa` now turns the check on, and so does an `ssl={...}` object in
the connection string unless it turns verification off or sets
`verifyIdentity` itself. The mysql2 floor moves to 3.24.6, the version this
was verified against.

reconcile held one transaction open for a stream's whole listing. PlanetScale
ends a transaction after 20 seconds, so a stream that lists for longer could
never be reconciled there. Only the capture of the live ids needs the
snapshot: the diff now runs on a pinned connection, commits after the
capture, and lists with no transaction open. A pinned connection's
`transaction()` begins its own instead of taking a savepoint outside one.
…re it reads

`init --repair` did nothing once the schema fingerprint was recorded: the
fingerprint check returned before any view or column was looked at, so a
dropped `_live` view or generated column stayed missing while the command
printed `schema ready`. A repair now forces the whole pass on the
destination's first `init()`, and a forced pass that finds drift it cannot
repair takes the fingerprint back. Plain `init` keeps the one-query path.

Both SQL destinations implement `ready()`, so `status` no longer creates
the mirror on an empty database.
The mirror's tables have plain names: `users`, `organizations`, `sessions`,
`roles`, `events`. On plain MySQL the mirror has a database to itself and
that is fine. A PlanetScale Vitess branch is one database, the
application's tables are in it, and most applications already have a
`users`: PlanetScale found that `init` takes that table for its own, tries
to add generated columns to it, and fails with `Unknown column '_raw'`.

`tablePrefix` (`--table-prefix`, `WORKOS_SYNC_TABLE_PREFIX`) puts a prefix
on every object the engine names in the database: stream tables, `_live`
views, the bookkeeping tables, the event archive and the temporary tables.
With `workos_`, `users` becomes `workos_users`. Lowercase letters, digits
and underscores, up to 24 characters.

The prefix travels with the database name as one `Target`, in the place
the name alone was passed, so no statement can name the database and
forget the prefix. Without one, every name, every statement and the schema
fingerprint are what they were, so an existing mirror runs no DDL.
PlanetScale ran the guide against Postgres and Vitess and reported where it
did not match what they saw. The guide now says:

- Vitess TLS works with the `ssl` parameter PlanetScale's connection string
  ends with; the CA variable is the alternative, not a requirement.
- With safe migrations on, the schema goes in from a development branch as
  two deploy requests, because one holding all 17 views fails the lint.
- Install the package before `npx`, set `WORKOS_ENVIRONMENT_NAME`, and use
  the host shown with the password rather than a host shape we guessed.
- Which table names the mirror takes in a Vitess database, how to prefix
  them, and that the keyspace has to be unsharded.
- What a new branch and a restored branch each start with.
- How `reconcile` behaves under PlanetScale's 20-second transaction limit,
  on 0.1.0 and after.

The package READMEs follow the behavior changes in this branch: the
reconcile exit code, read-only `status`, `init --repair`, host name
verification, and the table prefix. The MySQL README no longer describes a
single deploy request, or an `init` that names a missing column.
@greptile-apps

greptile-apps Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[High impact] The PR appears safe to merge.

Summary

Adds MySQL table prefixes and improves TLS checks, command exits, schema repair, and PlanetScale guidance.

  • MySQL mirrors can add a prefix to their tables and views.
  • MySQL checks that a verified TLS certificate names the connection host.
  • MySQL reconciliation leaves its transaction closed while it lists remote IDs.
  • Command exits distinguish failed checks from drift and wait for output to finish.
  • Postgres and MySQL status checks report an empty mirror without creating it.
  • Repair checks the recorded schema again and removes its fingerprint if drift remains.
  • Setup guides explain the updated commands and database choices.

No new actionable issues found in the changes since the previous review.

Reviews (5) · Last reviewed commit: "fix(mysql): refuse verified TLS to IP ho..." · Reviewed by Greptile

Comment thread packages/sync-engine/src/cli/help.ts Resolved
…alled

Every doc ran the command as `npx workos-sync-postgres`. That is the name
of the command a package installs, not of a package. With nothing
installed, npx asks the registry for a package by that name, and there is
none, so the first command in each guide failed with a 404. The unscoped
names are also unowned, so a package published under one of them would
run in place of ours.

`npx @workos/sync-postgres` names the package, which has one command, so
npx runs it. Installed, it runs the version in the project. The same
change is made for the MySQL, MongoDB and ClickHouse commands.
…uilds a column

A repair forgot every other fingerprint before its first DDL statement,
because MySQL commits each statement on its own and a repair that dies
between dropping a column and adding it back has already changed the
table. That was enough while a pass only ran with the current fingerprint
unrecorded.

`init --repair` now forces the pass with it recorded. A process that lost
its connection after the drop left that fingerprint behind, so the next
plain `init` trusted it and the column stayed missing. Every fingerprint
is forgotten now, and the current one is recorded again when the pass
comes back clean.
…s one

The shared help said `status` reads only, for every destination's
command. That holds for Postgres and MySQL, which implement `ready()`.
MongoDB and ClickHouse do not, so their `status` still runs `init` first,
and their help told a user it would not touch the database.

The line now follows the spec. A destination that answers `ready()` sets
`statusReadsOnly`, and the others say that the mirror is set up first.
The repo ships four destinations now, so the title no longer names only Postgres.
mysql2 verifies localhost for IP-address URLs, rejecting a valid IP
certificate while accepting one for the wrong identity. Require a DNS
hostname until the driver can verify the actual address, so credentials
cannot be sent under a false identity-verification guarantee.
@gjtorikian
gjtorikian merged commit b0a2428 into main Nov 17, 2026
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant