payload-locale-snapshot: Zero-loss safety plugin for localized fields, blocks, & arrays on PostgreSQL

[the-muzammilali]

Hey everyone! 👋

I'm sharing an open-source plugin I built to address a silent data loss issue when using Payload 3.x with PostgreSQL (@payloadcms/db-postgres) on multi-lingual collections: payload-locale-snapshot.

---

🔍 The Problem

When saving or updating a document in a specific locale (via Admin UI, local API, REST, or draft publishing) on PostgreSQL, the Drizzle adapter cleans up child tables with parent-scoped deletes:

DELETE FROM "<collection>_locales" WHERE "_parent_id" = $1;
DELETE FROM "<collection>_blocks_*" WHERE "_parent_id" = $1;
DELETE FROM "<collection>_<array>" WHERE "_parent_id" = $1;

Because these queries delete child rows without a _locale condition, any translations not present in the in-memory write buffer are wiped. Depending on the operation path or draft state, this can lead to:

1. Silent translation loss: Localized scalars, blocks, and arrays for unedited languages disappear.
2. Constraint errors: Serial ID regrowth can trigger duplicate key value violates unique constraint "<collection>_locales_locale_parent_id_unique".

---

🛡️ How payload-locale-snapshot Works

Rather than trying to intercept Payload's internal write transforms, the plugin acts as a transactional safety net:

1. beforeChange: Inspects PostgreSQL's foreign-key graph (information_schema) to dynamically discover all child tables (_locales, blocks, nested arrays, arbitrary depth) and snapshots non-active locale rows.
2. Payload executes its write phase.
3. afterChange: Restores the snapshotted rows using a scoped delete-before-insert and ON CONFLICT DO NOTHING.

Key Architecture Highlights:

• Zero Deadlocks: Runs entirely on Payload's active transaction (db.sessions[req.transactionID].db). No secondary pool connection is opened inside lifecycle hooks.
• Atomic Commits: Snapshot, Payload save, and restore commit together in a single transaction. If anything fails, the entire save cleanly rolls back.
• Universal IDs: Fully compatible with integer/serial, text, and UUID primary keys.
• Zero Manual Schema Config: Auto-detects collections and globals with localized fields.

---

📦 Quick Start

npm install payload-locale-snapshot
# or
pnpm add payload-locale-snapshot

Add it to your payload.config.ts:

import { buildConfig } from 'payload'
import { localeSnapshot } from 'payload-locale-snapshot'

export default buildConfig({
  // ...
  plugins: [
    localeSnapshot,
  ],
})

---

🔗 Links

• GitHub: the-muzammilali/payload-locale-snapshot
• npm: payload-locale-snapshot

I hope this helps teams running multi-locale production setups on PostgreSQL while upstream adapter optimizations continue. Feedback, issues, or ideas are very welcome!