Skip to content

Updated

Monitor pipeline status

Track replication status, view logs, and troubleshoot issues.

Use the Dashboard to check replication progress, investigate lag, and recover from errors.

Viewing pipeline status

Open Database > Pipelines to see each destination's pipeline status.

Pipeline states

StateMeaning
StoppedNot running; requires a manual start
StartingStarting or replacing the process after a restart
RunningProcess is running
StoppingFinishing in-flight work before stopping
RestartingApplying settings or table state before restarting
FailedReports a startup or runtime failure; can recover automatically
UnknownStatus is unavailable

Running does not confirm that initial sync has finished, the source is connected, or destination writes are complete. Check table states and lag to assess progress.

Viewing detailed pipeline metrics

Click a pipeline in the list to inspect its metrics and table states.

Running pipeline status page showing replication metrics and a live table
Use the pipeline status page to check replication lag, WAL retention remaining, connection health, and table states.

Table states

StateMeaning
QueuedWaiting to begin initial sync
CopyingCopying existing rows
CopiedCopy finished; changes made during the copy still need to be applied
LiveFollowing WAL changes, including catch-up after copying
ErrorReplication encountered an error
RestartingRestarting replication for the table from scratch
Not AvailableState is temporarily unavailable during a pipeline state change
UnknownThe Dashboard does not recognize the reported state

Replication lag metrics

These metrics come from Postgres replication slot state. Lag measures the gap between WAL flushed on a primary, or replayed on a standby, and the slot's confirmed flush position. It includes unrelated database activity and can trail the pipeline's local progress until Postgres receives feedback. WAL bytes do not measure destination payload size or elapsed delay.

Caught up means this gap is zero at measurement time. It does not guarantee that every table has finished initial sync or that data is visible to destination queries. Missing lag is shown as Unavailable.

MetricMeaningInvestigate when
LagWAL bytes available for replication but not yet acknowledged on the main slotThe value keeps growing
WAL retention remainingWAL that can accumulate before the slot risks becoming unusable, based on max_slot_wal_keep_sizeThe value is small or shrinking
Last check-inSource time minus the client's last feedback timestamp; clock skew can make this negativeFeedback is old or missing
Slot statusWhether required WAL is still retainedThe slot is Unreserved or Lost

The Dashboard displays Unavailable when Postgres returns no safe_wal_size. This can mean unlimited retention or unavailable headroom, including a Lost slot. A negative value is shown as Budget exceeded. Check slot status alongside retention headroom. See Postgres replication slot metrics.

Pipelines keeps sending feedback during slow writes and while WAL reading is paused. It repeats the last safe position without acknowledging unfinished writes. A recent check-in and an active connection can therefore coexist with growing lag.

Reading a change or having a destination accept it is not enough to advance durable progress. Retries can resend recent changes; see delivery guarantees for how each destination processes replay.

The main slot tracks ongoing replication. Table-sync slots appear temporarily during initial sync and have the same metrics.

Slot statuses

StatusMeaning
ReservedRequired WAL is retained within the normal WAL size limit
ExtendedRequired WAL is retained beyond that limit; this alone does not mean lag is growing
UnreservedRequired WAL is no longer fully reserved and can be removed
LostRequired WAL has been removed; replication cannot continue from this slot
UnknownSlot state is unavailable or unrecognized

See Respond based on the slot status for recovery actions.

Viewing logs

Open Logs > Pipelines for errors, retries, and performance warnings. Include the pipeline ID and relevant errors when contacting support.

Handling errors

Table errors can pause one table while others continue replicating. Pipeline errors affect the overall process.

Table errors

Open the pipeline, inspect the table error and any scheduled retry, and fix the cause. If replication cannot safely resume from its saved state, reset the affected tables.

Pipeline errors

A Failed pipeline can recover automatically. Check logs for persistent connectivity, permission, schema, or destination errors, fix the cause, and restart if needed. Supabase stops pipelines after repeated failures; a Stopped pipeline requires a manual start.

Dealing with replication lag

Lag grows when Postgres produces WAL faster than Pipelines confirms progress. Some lag is expected during initial sync, write bursts, and recovery from downtime. Sustained growth or shrinking WAL retention requires investigation.

Investigate the lag

  1. Open the pipeline and compare Lag with WAL retention remaining and Slot status.
  2. Check Last check-in for connection or feedback problems.
  3. Check table states for initial sync or table errors.
  4. Open replication logs and look for destination errors, rate limits, retries, or repeated restarts.
  5. Compare the lag trend with source activity, such as bulk imports, large transactions, or long-running writes.

Common causes include a slow destination, source or pipeline resource limits, network latency, and stopped or disconnected pipelines.

Initial sync and table-sync slots

Pipelines uses one main slot plus up to one temporary slot per active table-sync worker. These slots retain changes made while rows are copied. After copying and catch-up finish, the temporary slot is removed and the table continues through the main slot.

During copying, the table's WAL backlog grows from its snapshot boundary. Copying more rows does not advance this WAL position. After copying finishes, the table-sync worker applies accumulated changes and acknowledges progress. The table state distinguishes copying from this catch-up phase; the main slot's lag covers ongoing replication separately.

If a table-sync slot is lost, that table must repeat its initial sync. Automatic retries can recover individual tables; a manual table reset temporarily stops the whole pipeline.

To improve copy throughput:

  • Increase Initial sync connections per table when one large table is the bottleneck.
  • Increase Table sync workers when several tables need to copy concurrently.
  • Reduce bulk writes until the table is Live and its lag has caught up.

Higher concurrency uses more source connections, and additional workers need more slots. Increase it only while the source database, network, and destination have capacity. See setting defaults and limits.

Respond based on the slot status

Slot statusAction
Reserved or ExtendedMonitor the trend. If lag keeps growing, investigate destination performance, source write volume, and logs.
UnreservedRestore connectivity or resolve throughput and write failures before Postgres removes required WAL. Contact support if lag continues to grow.
LostFor a table-sync slot, retry the affected table. For the main slot, use the recovery procedure that follows.
UnknownCheck logs and slot details. If the state persists, contact support with the pipeline ID and error details.

Recovering a lost main slot replaces every destination table. Existing source rows are copied only for tables selected for initial sync; excluded tables resume with new changes only. Data processed again is billed again.

To recover a lost main slot:

  1. In the Supabase Dashboard, open Edit pipeline > Advanced settings.
  2. Set Invalidated slot behavior to Recreate slot and save the changes.
  3. If the pipeline is running or failed, restart it. If it is stopped, start it.

Alternatively, stop and delete the pipeline, then create a new one. Deletion automatically removes that pipeline's main slot, table-sync slots, and saved replication state when the source database is reachable. It leaves source tables, existing destination data, and the shared Pipelines installation in place.

Reduce future lag risk

  • Review the WAL retention recommendation at creation and continue monitoring retention after startup.
  • Publish only the tables and operations you need.
  • Avoid prolonged stops while the source is receiving writes.
  • Schedule bulk writes and initial sync during quieter periods when possible.

Resetting tables

Use Reset table to rebuild a destination table from scratch, for example after an unsupported schema change or an unrecoverable error. Choose the action based on what needs to recover:

ActionEffect
Restart pipelineRestarts the process. Tables that completed initial sync resume from saved progress. Initial syncs interrupted by the restart start again from the beginning.
Reset tableClears the selected table's saved progress and rebuilds its destination data when replication resumes, even if its initial sync had completed.

Restarting during initial sync also repeats the copy when its rows finished copying but catch-up has not completed. See pipeline restart and recovery behavior.

When you reset tables:

  • All existing data in the affected destination tables is deleted when replication resumes. Source tables and their rows are unchanged. Append-only destination history is also erased.
  • Tables selected for initial sync copy their current published source rows again, then resume ongoing replication. Excluded tables receive new changes only.
  • Saved progress is reset only for the selected tables.
  • Data processed again is billed again.

An active pipeline stops temporarily and restarts automatically to apply the reset. Replication pauses for all tables, and other tables' unfinished initial syncs also start over. A stopped pipeline stays stopped. Start it explicitly when you are ready to rebuild the selected tables.

Before resetting, use Edit pipeline to check Initial sync. Include any affected tables whose existing source rows you need to copy again, then save the settings.

Reset a single table

  1. Open the table's actions menu and select Reset table.
  2. Review the table name, data replacement, and cost details.
  3. Confirm Reset table.

Reset multiple tables

  1. Click Reset all tables, or open More reset options and select Reset failed tables only.
  2. Review the affected tables, data replacement, and cost details. The failed-tables action affects every table that is failed when the request runs.
  3. Confirm Reset all tables or Reset failed tables, matching the scope you chose.

A successful reset prepares the tables for rebuilding; it does not mean their copies have finished. Monitor their progress after the pipeline resumes. If a reset fails, refresh the pipeline and table states before retrying.