Syncing 50,000 directory entries without melting

Directory sync is the least glamorous feature we ship and the one we rewrote the most. Every OhKube product hangs off the same person record, which means sync is not a feature. It's the foundation everything else falls over on.

The naive version is easy: page through the identity provider's API, upsert every user, done. It works beautifully in the demo org with 40 users and falls apart at 50,000, where a full pass takes long enough that the data is stale before you finish writing it.

Deltas first, full sync as a safety net

Our sync runs in two modes. The delta loop asks the provider for changes since a cursor and applies them within seconds. The reconciliation pass walks the entire directory on a schedule, computes a diff against our copy, and repairs anything the deltas missed, because webhooks get dropped, cursors expire, and providers occasionally lie. Trusting deltas alone is how you end up with a ghost employee who was offboarded in March.

Idempotency is the whole game

Every operation in the pipeline is an upsert keyed on the provider's immutable ID, never on email, because emails change when people change names, and a sync that duplicates a person on marriage is a sync that ruins someone's week. Running the same batch twice produces the same database. That property means retries are free, crashes are recoverable mid-batch, and nobody gets paged for a half-applied sync.

The last piece is restraint. Group membership changes fan out into device policy scopes in MDM and routing rules in Desk, so a directory hiccup could stampede the whole platform. Downstream effects are queued, deduplicated, and rate-limited. A 10,000-member group rename becomes one scope recalculation, not ten thousand.

Fast, repeatable, self-healing, and quiet. Sync should be boring. It took three rewrites to get bored, and we consider that a feature.