Schema Changes

Schema drift occurs when columns are added, renamed, dropped, or type-changed on the source database while a pipeline is running. Nanosync detects these changes via the WAL (Postgres) or CDC change tables (SQL Server) and responds according to configured policy.

---

Default behaviour by change type

Change	Default behaviour
Column added	Auto-adds column to destination on next batch
Column dropped	Pipeline pauses with SCHEMA_DRIFT alert
Column renamed	Treated as drop + add — pipeline pauses
Type changed (compatible)	Applied automatically
Type changed (breaking)	Pipeline pauses

Compatible type changes are promotions the destination can absorb without data loss — for example, int → bigint or varchar(100) → varchar(500) in Postgres. Breaking changes include narrowing casts, precision changes, and type-family changes (e.g., int → text).

---

schema_drift_mode

Control how the pipeline responds to schema drift via properties.schema_drift_mode:

source:
  connection: prod-postgres
  tables: [public.orders]
  properties:
    schema_drift_mode: pause   # default

Value	Behaviour
pause	Stop processing on any breaking change. Fire a SCHEMA_DRIFT alert. Wait for manual resolution. (Default)
ignore	Silently skip events for columns not present in the current destination schema. Pipeline continues.
fail	Hard error on any breaking change. Pipeline stops permanently and must be reconfigured and resumed.

pause is the default because it’s recoverable — the pipeline stops accumulating lag, alerts fire, and you can fix the destination schema before resuming. fail is appropriate when you want drift treated as a fatal condition that requires explicit operator action to clear.

---

Checking pipeline status when paused

nanosync monitor
# NAME              SOURCE        DESTINATION  STATUS    LAG      EV/S
# orders-pipeline   prod-postgres bigquery     ● paused  SCHEMA_DRIFT: column 'discount' dropped on public.orders

The drift detail — which column changed on which table — is included in the status line. The same information appears in pipeline logs and in the SCHEMA_DRIFT alert sent to configured notification channels.

---

Resuming after a schema change

After you’ve resolved the mismatch at the destination (e.g., dropped the column from BigQuery, or added a replacement):

nanosync pipeline resume orders-pipeline

The pipeline picks up from its last checkpoint. No data is lost and no re-snapshot is needed — it resumes exactly where it paused.

---

Excluding columns proactively

If there are columns you never want replicated, exclude them in the source config. Nanosync will never emit events for those columns, and schema changes to excluded columns won’t trigger drift detection.

source:
  connection: prod-postgres
  tables: [public.orders]
  properties:
    schema_drift_mode: pause
  exclude_columns:
    public.orders: [internal_notes, legacy_id]

exclude_columns is a per-table map. Keys are schema.table and values are lists of column names to suppress. This is the right approach for columns that are known to change frequently or that contain data you deliberately don’t want at the destination.

---