estuary-connector-restart

Restart a Connector — Disable and Re-enable via flowctl

Temporarily pause a capture or materialization by disabling its shards, then re-enable it. The connector resumes from its last checkpoint — no data is lost. Works for both captures and materializations.

Prerequisites

flowctl auth login

Step 1: Pull the current spec

flowctl catalog pull-specs --name <task-name>

This creates a flow.yaml and a directory with the task's YAML spec.

Step 2: Disable the connector

Edit the task's YAML file (under <task-name>/flow.yaml) and add a shards block at the same level as endpoint and bindings:

captures:
  acmeCo/source-postgres:
    endpoint:
      connector:
        image: ghcr.io/estuary/source-postgres:v1
        config: ...
    bindings:
      - resource: ...
        target: ...
    # Add this block to disable:
    shards:
      disable: true
    # To re-enable: remove the shards block and any expectPubId line

If a shards section already exists, just add disable: true to it.

Publish to apply:

flowctl catalog publish --source flow.yaml --auto-approve

Confirm it's disabled:

flowctl catalog status <task-name> --output json | jq '.status.type'
# Expected: "TASK_DISABLED"

Step 3: Re-enable the connector

Edit the same file and:

1. Remove disable: true (or the entire shards block if it only contained that) — do not set it to false (an explicit false is treated as a setting and may cause unexpected behavior)
2. Remove the expectPubId line if present — it's stale after the disable publish and will cause errors

Publish again:

flowctl catalog publish --source flow.yaml --auto-approve

Verify it's running:

flowctl catalog status <task-name> --output json | jq '.status.type'
# Expected: "WARNING" initially (shards starting), then "OK" after 30-120 seconds

Activation timing varies: small connectors take 30-60 seconds, large connectors (100+ bindings) take 60-120 seconds.