Skip to content

DLQ table migration (worker → pystator.dlq)

Default table name

The DLQ default table name is now dead_letter_queue.

If you’re upgrading from an older deployment that used a different default table name, run:

pystator db upgrade

(or pystator db init on a fresh database, which applies all migrations.)

The squashed Alembic revision 20260401120000 ends with the same DLQ step as before:

  1. No table — create an empty unified DLQ table (and indexes).
  2. Already unified (column payload exists) — skip.
  3. Legacy layout (has trigger_name, no payload) — rename the old table, create the new one, copy rows, drop the backup.

Back up the database before upgrading production.

Downgrade: the squashed revision’s DLQ portion is not reversed individually; downgrade() drops the DLQ table with the rest of the schema.

Existing database already migrated (pre-squash Alembic)

If your database was already at the old migration chain head (schema matches current PyStator) and you only updated the package to the squashed migrations, do not run upgrade (it would try to recreate tables). Stamp the new head instead:

pystator db stamp --revision 20260401120000

Confirm alembic_version (or pystator.alembic_version on PostgreSQL) shows 20260401120000 afterward.

Custom table name

If PYSTATOR_WORKER_DLQ_TABLE_NAME points to a non-default table, adapt the steps manually:

  1. Rename your legacy table (e.g. to my_dlq_legacy_v1).
  2. Let the worker or DatabaseDeadLetterStore create the new table, or copy the CREATE TABLE / indexes from pystator.dlq.database_store.
  3. Insert from legacy, mapping:
Legacy column New column / field
machine_name source_name
event_id payload.event_id
entity_id payload.entity_id
trigger_name payload.trigger
context payload.context (JSON object)
(other) reason, stage, error_message, error_type, metadata, attempt, max_attempts, status, retry_count, created_at

Set updated_at and expires_at to NULL unless you have values to preserve.

Legacy note

Very old worker deployments used the table name pystator_dead_letter_queue for DLQ rows. Current migrations rename it to dead_letter_queue when found.

Verify

After upgrade, use the API Test DLQ action or query counts on reason, stage, and status to confirm rows look correct.