Skip to main content
A database migration changes the schema. It does not reconstruct historical values for a new column, table, or indexing rule. Before deploying a schema change, decide whether the change needs:
  • only a database migration;
  • an application-level backfill from data already stored in Postgres; or
  • a full blockchain replay in a fresh slot.

​
Choose a strategy

SQD Cloud does not automatically backfill historical data after a schema or handler change. Applying a migration and redeploying the existing slot only affects future processing unless your code explicitly repairs old rows.

​
Option 1: Update the existing slot

Use an in-place update when the existing database is valid and the change is additive or operational.
  1. Add and test an incremental migration locally.
  2. Back up any non-reconstructable data.
  3. Deploy to the existing slot:
  4. Confirm that the init service applies the migration successfully.
  5. Check processor logs, API queries, and indexing progress.
Do not use --hard-reset: it drops and recreates all deployment resources, including the database.

​
Option 2: Backfill from existing Postgres data

If the new value can be derived from existing tables, run the backfill outside the processor transaction:
  1. Apply the additive schema migration.
  2. Deploy a separate background job.
  3. Update rows in bounded batches.
  4. Store progress so the backfill can resume after a restart.
  5. Monitor locks, statement duration, and database growth.
  6. Remove the temporary job when verification is complete.
Avoid one unbounded UPDATE over a large table. It can create long locks, large transactions, and table bloat.

​
Option 3: Replay in a fresh slot

Use a new slot when correctness depends on replaying historical blocks:
  1. Keep the current slot tagged production.
  2. Deploy the changed code without specifying a slot or tag:
  3. Wait for the new slot to reach the expected chain height.
  4. Validate row counts, representative queries, and application behavior through the slot URL.
  5. Move the production tag:
  6. Keep the old slot temporarily for rollback.
  7. Remove the old slot only after the observation window:
See Slots and tags for the complete cutover and rollback procedure.
Parallel slots are independent deployments and are billed independently while both are running. Estimate the overlap before starting a long replay.

​
Validate before cutover

At minimum, compare:
  • processor height and lag;
  • entity counts for important tables;
  • known records at old, middle, and recent blocks;
  • API response shape and latency;
  • custom aggregate or materialized-table output;
  • error and restart rates.
If the new schema removes or renames API fields, treat the deployment as an API version change. Use a separate tag such as production-v2 until clients have migrated.

​
Roll back

If validation fails after moving the tag:
  1. Move production back to the old slot.
  2. Stop sending traffic to the new slot.
  3. Inspect its logs and database without changing the old slot.
  4. Fix the issue and redeploy to the same new slot, or remove it and start another replay.
Moving a tag changes the stable API destination. It does not merge, copy, or roll back database contents between slots.

​
Data that cannot be recreated

Managed Postgres should not be the only copy of user-generated or externally sourced data that an indexer replay cannot reproduce. Store that data separately or arrange the appropriate backup and availability requirements before destructive schema work.