Locale Snapshot

About

Payload CMS 3.x with the PostgreSQL adapter has a destructive edge case. When you save a document in one locale, the Drizzle adapter issues a cascade `DELETE` on the block and array tables scoped only by `_parent_id`, with no `_locale` filter. PostgreSQL then removes every translated block, nested array, and sub-item across all other languages, and Payload only re-inserts the rows for the active locale. The loss is silent. `localeSnapshot` closes that gap. The plugin attaches to the `beforeChange` and `afterChange` lifecycle hooks. Before a save, it runs parameterized SQL to snapshot all block, array, and child rows belonging to non-active locales into `req._localeSnapshot`, walking the foreign-key hierarchy in topological order so parents are captured before children. After the save commits, it restores those rows inside a dedicated `BEGIN ... COMMIT` transaction with `ON CONFLICT ("id") DO NOTHING`, releasing a PostgreSQL advisory lock in a `finally` block. It auto-discovers relevant tables from foreign-key constraints with a TTL cache, so you do not hardcode collection slugs. Configuration is a single plugin entry in `payload.config.ts`. You can pin specific `collections` and `globals` or let the plugin auto-detect any with localized blocks or arrays. Other options include `failOnError` (abort the save on snapshot failure), `maxDepth` for hierarchy traversal, `schemaCacheTTL`, `lockTimeoutMs`, and `serverless` for runtimes like AWS Lambda or Vercel where `setImmediate` may be frozen. The plugin supports integer, serial, text, and UUID primary keys, and reuses Payload's own connection pool. It targets Payload `^3.0.0` with `@payloadcms/db-postgres` and PostgreSQL 14 or later, and does nothing for MongoDB or SQLite setups. If the database connection drops mid-restore, it writes a durable JSON dump under `.locale-snapshot-recovery/` that you can replay with the exported `restoreFromRecoveryDump()` helper. `resetSchemaCache()` invalidates the schema hierarchy cache after migrations add new block types.

Package info

Package name

payload-locale-snapshot

Latest version

0.1.0

Unpacked size

156 kB

License

MIT

Last publish

Aug 16, 2026