Schema changes during a live sync

How sluice keeps a running sync online while the source schema evolves — what forwards automatically, what refuses loudly, and how to recover.

A source schema rarely stands still. Columns get added, types get widened, indexes come and go while a continuous sync is running. sluice does not manage those migrations for you — tools like Atlas, sqitch, Flyway, and liquibase do that — but it does keep the stream online through them. By default it forwards the operator's own committed DDL onto the target, so a routine ALTER TABLE no longer wedges the sync. This page covers what forwards automatically, the narrow set of changes that still refuse loudly, and the drained-migrate recovery when one does.

The control: --schema-changes #

A single tristate flag on sync start (and per-sync in a sync run fleet spec) governs the behavior, introduced in ADR-0091:

What forwards, by source engine #

Under forward, the intercept can emit any shape's DDL, but a change only reaches the target if the source's CDC stream actually carries its detail on the wire. Postgres logical replication (pgoutput) carries less than MySQL's information_schema re-read, so the honest matrix differs by source engine. This is the ground-truth table from ADR-0091 §1d — do not assume a shape forwards without checking it:

¹ pgoutput's relation message carries only column name + type + the replica-identity key flag — no nullability flag, no secondary-index or CHECK metadata. The wire never signals these on a Postgres source, so they produce no boundary to forward. Nullability and CHECK changes are caught by the v0.156.0 door instead (⁶); a plain index change is not caught by anything.
² v0.158.0+ (ADR-0091 §4, amended). A reorder (MODIFY c … AFTER id) and a rename swap or rotation (RENAME COLUMN b TO c, RENAME COLUMN c TO b) produce the same boundary: every column keeps its name and type, and only the declared order changes. The old argument for a no-op — sluice decodes rows by column name, so a reorder needs no DDL — holds for a reorder and not for a swap, which leaves every row the target already holds under the wrong column names. So both refuse until the target's own column order has moved from its recorded order to the source's: run the same MODIFY … AFTER or RENAMEs on a target that can reorder in place (MySQL, PlanetScale, Vitess and MariaDB targets), or re-copy a Postgres target. From v0.99.45 through v0.157.2 both were forwarded as a no-op (see the v0.158.0 notice).
³ MySQL's CDC projection reads only {schema, name, columns, primary key} on a DDL boundary; it does not project secondary indexes or CHECK constraints. An index-only or CHECK-only DDL therefore produces no boundary at all and is never forwarded. For a plain index that is still the whole story — it is not refused and nothing is logged about it; the change simply never reaches the target, and you add it there out-of-band. A CHECK change, since v0.156.0, is caught by the door in ⁶ on a binlog source. Forwarding either would need a new catalog projection (perf-only for indexes; cross-engine expression-translation-hazardous for checks), so both are deferred.
⁴ A Postgres RENAME is proven via the stable pg_attribute.attnum — see RENAME COLUMN.
⁵ With two carve-outs, both below: a cast to or from a session-normalised timestamp always refuses (session-normalised timestamp), and on a Postgres source a change your projected type cannot express refuses under both modes (projection-invisible changes).
⁶ v0.156.0+, Postgres and MySQL/MariaDB binlog sources. Neither change stream describes these objects, so they never forward; through v0.155.1 they were dropped with no log line and the target stayed weaker than the source. Now the stream stops at the next write to that table with UNFORWARDED-SCHEMA-CHANGE, the refusal is recorded, and every later start refuses again until acknowledged — see below. Not covered: PlanetScale / Vitess (VStream) sources, where these changes are still silent, and the trigger-CDC engines (postgres-trigger, sqlite-trigger, d1-trigger), whose own readers this door does not reach (for postgres-trigger's DDL handling see below).
⁷ v0.156.1+. The column's DEFAULT is carried on the target's ADD COLUMN: a MySQL/MariaDB binlog source carries it in-band, and on a Postgres or PlanetScale/Vitess source — whose change streams have no field for it — the forward reads it through the source schema reader, the same value a cold-start migrate emits, and refuses if that read fails (through v0.156.0 it was dropped, so the target filled its pre-existing rows with NULL, NOT NULL columns included). The DEFAULT is read when the boundary reaches sluice, though, so it can differ from what the source filled its own rows with — hence the backfill, on by default. A non-constant DEFAULT the source still declares at that point refuses. The same applies under Shape A (--inject-shard-column). Toward a MySQL-family target a TEXT/BLOB/JSON/GEOMETRY DEFAULT that cannot be carried refuses the ADD COLUMN (LOB-DEFAULT-NOT-CARRIED).

Every forwarded DDL is logged at INFO as it lands, so the applied change is visible in the sync's log stream. Cross-engine type ALTERs are retargeted through the same translation path a cold-start CREATE TABLE uses; a widening ALTER forwards cleanly, while a narrowing or incompatible one is rejected by the target engine and surfaces as a loud, retryable refuse (position not advanced).

What always refuses, even under forward #

These shapes never auto-apply, because forwarding them would silently change or lose stored data:

A cast to or from a session-normalised timestamp #

An ALTER COLUMN TYPE where either side is a session-normalised timestamp — MySQL TIMESTAMP, Postgres timestamptz — refuses, in either direction and at any precision. Those types store UTC, so the server has to resolve them through the executing session's zone to render them as anything else (and to read anything else into them), and nothing on the binlog or the pgoutput wire carries which zone that was. The source operator's ALTER ran under their own session — MySQL's shipped default is time_zone=SYSTEM, the host zone — while sluice pins UTC on every connection it opens, so forwarding the same statement re-casts the target's pre-existing rows against a different zone. Row counts stay equal, every row applied after the ALTER is correct, and the sync exits 0: exactly the silent shape the refusals on this page exist for.

The original refusal was the TIMESTAMP ↔ DATETIME swap alone. Since v0.139.0 it covers the wider measured class. On MySQL 8.0.46 and PostgreSQL 16, a value stored at 2026-06-15 20:00:00 UTC and altered under a +09:00 session read back as 2026-06-16 05:00:00 through VARCHAR, 2026-06-16 through DATE (across midnight), 05:00:00 through TIME and 20260616050000 through BIGINT; the reverse casts into TIMESTAMP shifted the stored instant by the same nine hours, and PG timestamptz to text / date behaved identically. All of them forwarded unrefused before. The time and timetz pair is MEASURED asymmetric, and since v0.142.0 the refusal matches the measurement instead of covering both halves. time to timetz is session-dependent and still refuses: an offset is invented, and Postgres takes it from the executing session. timetz to time is not, and now forwards — timetz stores its offset alongside each value, so dropping it consults no session zone, measured byte-identical under UTC and Asia/Tokyo across negative and fractional offsets, 1-D arrays with NULL elements, and 2-D arrays checked with array_dims. Before v0.142.0 that direction was refused too, halting a stream you would expect to forward. The array shapes follow the scalars (time[] to timetz[] refuses, timetz[] to time[] forwards), and the timestamp family is unchanged and still refuses both ways, because timestamptz is stored normalised to UTC and re-renders through the session zone whichever way the cast runs. A precision-only change within one type (DATETIME(3) → DATETIME(6)) and a cast with no zoned side at all (DATETIME → VARCHAR) carry no zone conversion and keep forwarding.

Scope, stated precisely. The widened class is enforced at the pipeline door, which is reached when a boundary is forwarded — the mode that re-casts the target's existing rows, and so where the widening does its work. The reader-side checks that refuse at a table's first boundary after a cold start or a warm resume still carry only the original TIMESTAMP/DATETIME pair. Either way the remedy is the drained model below: stop with --wait, run the same ALTER on source and target from your own client so both casts happen under a session zone you chose, then restart with the same --stream-id.

RENAME COLUMN #

A column rename and a DROP x + ADD y of the same type are indistinguishable from the replication stream alone — both present as exactly one dropped column and one added column. Guessing RENAME when the truth is drop+add keeps stale data under the new name; guessing drop+add when the truth is RENAME drops the column's data on the target. The only safe disambiguation is a stable column identity that survives a rename:

• Postgres has one — pg_attribute.attnum is stable across a rename. The PG CDC reader carries it as the column's stable id; the intercept forwards a rename only when the before and after columns share the same non-zero attnum (proven rename, data preserved) and refuses otherwise. Because the proof is definitive, a bug here can only ever refuse safely, never mis-forward.
• MySQL has no equivalent — ORDINAL_POSITION changes on reorder and there is no creation id, so a MySQL-source rename is fundamentally unprovable from catalog state. It refuses, permanently. Drain and rename on both ends explicitly.

ADD COLUMN with a computed / volatile DEFAULT #

An ADD COLUMN whose DEFAULT is a non-deterministic function is refused, because evaluating it in the target's session diverges from the per-row values the source already inserted (ADR-0058 §2a). The refused functions include NOW() / CURRENT_TIMESTAMP / clock_timestamp(), nextval(), gen_random_uuid(), random(), and MySQL's UUID() / RAND() — matched schema-qualified or bare, and detected even when wrapped (e.g. COALESCE(NULL, NOW())). A constant DEFAULT forwards normally. If the probe of a column's default can't be read at all, sluice refuses on uncertainty rather than risk a wrong value.

The refusal looks at the DEFAULT the source still declares when the ADD COLUMN reaches sluice. A volatile DEFAULT that was dropped or changed before then — Django's AddField drops its default in the very next statement — is not refused: the forward carries whatever the source declares at that point, and the added-column backfill (on by default since v0.156.1) then overwrites the target's pre-existing rows with the values the source actually filled them with. Through v0.156.0, without the opt-in backfill, those rows kept the target's own fill. Since v0.156.1 the Shape A router (--inject-shard-column) applies the same refusal; before, on a MySQL-family source, it forwarded such a DEFAULT and every pre-existing row got the target's own evaluation of it.

A change your projected type cannot express (Postgres source) #

A consumer of pgoutput holds two representations of a column's type — the raw wire pair (type OID, typmod) and the projected IR type sluice maps engines into — and they can disagree about whether anything changed. interval precision/field restrictions and array-element modifiers are visible to the raw compare and vanish in projection, so the change classifies and there is no projected boundary to forward, while the source has already rewritten every stored value underneath it. Since v0.132.1 a detected change whose projected type is unchanged refuses under both modes, per column and keyed on column name (a middle-column DROP shifts every later ordinal, and pgoutput coalesces DML-quiet back-to-back DDL into one relation message of final state), with a catalog-derived enumeration gate holding the class closed. The refusal text is shape-aware: the two catalog-only shapes PostgreSQL applies without a rewrite — an unbounded varchar↔text swap, and an interval precision widening with the same range bits — say so instead of warning about divergence that did not happen.

More than one column's type or nullability in one ALTER #

v0.158.0+. Forward mode forwards one column's type or nullability change per boundary. Two or more columns changing in one statement — ALTER TABLE t ALTER b TYPE numeric(12,4), ALTER c TYPE numeric(12,4), or two MODIFYs in one MySQL statement — now refuse, naming every column. That includes two widens within one family, such as two VARCHAR widens. Through v0.157.2 the classifier read such a change as no change at all: a Postgres target kept numeric(10,2) and rounded every later value (1.2345 landed as 1.23, at exit 0, measured), while a MySQL target refused the first value that did not fit with DECIMAL-SCALE-EXCEEDED. Against the cold-start seed the target decides, as it does for one column, and at the first boundary after a cold start several nullability-only changes are skipped with a WARN, as a single one is. Recover with the drained model, applying every change on the target, or issue the changes as separate ALTER statements.

A change to a table's column order: COLUMN-ORDER-CHANGED #

v0.158.0+, every schema-changes mode. A column swap (RENAME COLUMN b TO c, RENAME COLUMN c TO b), a rotation of three or more names, and a MySQL/MariaDB reorder (MODIFY c … AFTER id / FIRST) produce the same schema boundary: every column keeps its name and its type, and only the order the source declares them in changes. A reorder needs nothing on the target. A swap leaves every row the target already holds under the wrong column names. A boundary across which two of a table's columns changed order now stops the stream with COLUMN-ORDER-CHANGED, naming those columns, before the boundary is recorded or any row after it is applied. On a Postgres source, DROP COLUMN b, RENAME COLUMN c TO b also refuses now, rather than reading as a plain drop.

The boundary is accepted once the target's own column order has moved from the order sluice recorded for that table to the source's new one, which is what applying the same change there does. A target that merely already declares the new order proves nothing. The record lives in the control table sluice_cdc_column_order. The check runs on the live forward path, at each table's first boundary after a restart (so a restart after the refusal refuses again), under --schema-changes=refuse and on multi-database streams (where the message is SCHEMA-CHANGE-REFUSED and also carries COLUMN-ORDER-CHANGED), and under --inject-shard-column. The refusal is codeless and exits 1; a sync run leg that hits it is marked failed rather than restarted (fleet). The message names one remedy:

• Apply the same change on the target, then restart with the same --stream-id: the same RENAME COLUMN statements for a swap or rotation, or the same MODIFY … AFTER/FIRST for a reorder on a target that can reorder in place (MySQL, PlanetScale, Vitess and MariaDB targets; MySQL rebuilds the table to do it). Do not update values instead: the check reads the target's column order.
• Re-copy: sluice sync start --reset-target-data --yes with the stream's other flags unchanged, which drops every table of the stream on the target and copies it again from a fresh snapshot (on a Postgres source, drop the stream's slot with sluice slot drop first). This is the remedy for a reorder on a target that cannot reorder in place (Postgres), and the only one offered when sluice cannot prove the target moved: the table has no record — as on a stream started before v0.158.0 that has not yet accepted a boundary changing that table's column list — or its recorded target order already disagreed with the source. schema add-table is deliberately not offered: it keeps the stream's position, so rows written before the change would be replayed onto the re-copied table under the old names.

COLUMN-ORDER-RECORD-UNAVAILABLE is a WARN at start: the target cannot keep the records, typically a PlanetScale safe-migrations branch or a Postgres role that cannot create tables. The stream runs, but every column-order change on it refuses with the re-copy remedy, even after you apply it on the target. To enable the records, have a role that can create tables run the sluice_cdc_column_order statement sluice control-tables ddl --engine <target engine> prints (on a safe-migrations branch, ship it with deploy-ddl).

The cost. A plain MySQL/MariaDB column reorder, which forwarded as a no-op since v0.99.45, now stops the stream until the target is reordered too, or re-copied on a Postgres target. Backup chains follow the same rule: chain restore, backup verify and sync from-backup refuse an incremental whose schema delta changed a table's column order (SLUICE-E-BACKUP-SCHEMA-DELTA-UNSUPPORTED), before applying anything of it; an ENUM label reorder is not a column-order change.

Which DDL halts the stream (postgres-trigger source) #

A Postgres event trigger is database-wide. There is no such thing as a schema-scoped one. Through v0.139.0 the DDL tier filtered by command tag alone, so it recorded a marker for an ALTER TABLE, CREATE TABLE or CREATE INDEX anywhere in the database — and a marker halts the stream with the restart-from-scratch remedy. A colleague creating an unrelated table, in a schema sluice never touches, stopped your sync.

Since v0.140.0 the tier asks the question the drop arm has asked since v0.136.0: does the command's relation carry this install's row-capture trigger? What that resolves to was measured on Postgres 16.15 rather than assumed, because it differs by shape and one shape could have failed quietly — an ALTER reports the table directly, ADD CONSTRAINT included, while a CREATE INDEX reports the index and has to resolve through it to the table.

• Still halts: ALTER TABLE on a captured table (ADD COLUMN, ALTER COLUMN TYPE, DROP COLUMN, ADD CONSTRAINT, RENAME COLUMN) and CREATE INDEX on one.
• No longer halts: anything on a table this install does not capture — another schema entirely, an uncaptured neighbour in the same schema, or a brand-new table. A table with no capture trigger emits no change rows, so it cannot make the applier write a wrong one; sluice schema add-table is how it joins the stream.

A DROP of a synced table (postgres-trigger source) #

Dropping a table a postgres-trigger install captures — directly, or through DROP SCHEMA … CASCADE / DROP OWNED BY — refuses the stream at the next poll since v0.136.0, naming the relation and carrying a drop-specific remedy (the usual one would be useless: sluice migrate reads the source schema and cannot land a drop). Through v0.135.x nothing recorded it at all — the ddl_command_end event trigger named DROP TABLE in its tag filter, and pg_event_trigger_ddl_commands() returns zero rows for a drop — so the stream carried on at exit 0 with the target holding the table's last-synced rows forever. An install created before v0.136.0 has no sql_drop arm and warns DROP-CAPTURE-ABSENT at every CDC open until sluice trigger setup is re-run. Two deliberate non-events: a DROP INDEX records nothing (sluice never forwards index DDL, so an index drop cannot change any row the applier writes), and a drop elsewhere in the database records nothing — the capture is scoped to tables carrying this install's own sluice_capture trigger.

Multi-shape combos (more than one structural change in a single boundary) also refuse — the IR delta can't be unambiguously ordered — as does a target DDL apply that fails on lock contention, permissions, or an unrecognized type. Every one of these leaves the CDC position un-advanced, so a retry replays the boundary once you've reconciled by hand. One exception since v0.156.1: a target ALTER that fails for a forwarded ADD COLUMN — even transiently — stops the stream with ADD-COLUMN-BACKFILL-INCOMPLETE unless the backfill is switched off, because the owed backfill was recorded before the ALTER ran; the automatic retry and every restart refuse until you check the column and acknowledge.

After a forwarded ADD COLUMN: the backfill from the source #

v0.156.1+, on by default. When sync forwards a source ADD COLUMN, the target fills every row it already holds with the column's DEFAULT as the forward carried it, and that DEFAULT is read when the boundary reaches sluice. It is not what the source filled its own rows with whenever the DEFAULT was dropped or changed in between (Django emits ADD COLUMN c … NOT NULL DEFAULT 'v' then ALTER COLUMN c DROP DEFAULT for every field with a default), or when a non-constant DEFAULT was dropped or changed before the ADD COLUMN reached sluice. So after the ALTER lands, sluice pages the table on the source by primary key, reading only the key and the added columns, and writes each row's value to the target, ahead of every change that follows the ALTER — a row the source updates after the ALTER still ends at its updated value. It covers Postgres, MySQL, MariaDB and PlanetScale/Vitess sources, single-stream and Shape A (each shard's stream fills only its own shard's rows, from its own source). A --where filter applies to its read. The trigger-CDC sources forward no ADD COLUMN, and a multi-database stream does not forward DDL, so neither has anything to backfill.

• The stream waits for it. The cost is one pass over the table on the source plus one UPDATE per pre-existing row on the target. On a Postgres target the updates are pipelined; on a MySQL, MariaDB or PlanetScale target each is its own round trip, so a large table over a slow link can put the stream far behind. It logs forward-add-column: backfilling the added columns … when it starts, forward-add-column: backfill in progress with the row count every 30 seconds, and forward-add-column: backfill complete with rows_backfilled at the end.
• It needs a primary key, read from the source catalog rather than the change stream (under Postgres REPLICA IDENTITY FULL the stream's key is every column; a VStream field event carries no key). Without one it refuses. It also refuses if the added column, or a primary-key column, has been renamed or dropped on the source by the time it reads; a later change to any other column does not affect it.
• Opting out: --no-backfill-added-column (fleet key no-backfill-added-column: true). The pre-existing rows then keep the target's fill, and a WARN (forward-add-column: backfill suppressed) names each column. --backfill-added-column, the old opt-in, is a deprecated no-op.

An interrupted backfill stops the stream: ADD-COLUMN-BACKFILL-INCOMPLETE #

A backfill does not resume: a restarted stream never sees the ADD COLUMN again, so the rows it had not reached would keep the target's fill with nothing to report it. So a run that ends before the backfill provably reached the target — a sync stop or Ctrl-C during it, a failed source read, an apply error, or a target ALTER that failed, even transiently — ends with ADD-COLUMN-BACKFILL-INCOMPLETE, naming the table and columns. It is an UNFORWARDED-SCHEMA-CHANGE refusal (the message begins UNFORWARDED-SCHEMA-CHANGE: ADD-COLUMN-BACKFILL-INCOMPLETE: …), recorded on the stream's sluice_cdc_state row the same way, so every restart refuses; like it, it exits 1 with no error code, and a fleet supervisor does not restart the leg. A process killed without running its exit path (SIGKILL, an OOM kill, power loss) is covered too: the owed backfill is written to that record before the ALTER is applied, and cleared (compare-and-clear, so it never removes a different refusal) only once the backfill is confirmed on the target — checked every 10 seconds while the stream runs and again at stop. If the record cannot be written, the ADD COLUMN is refused rather than forwarded without it.

The remedy differs from a plain UNFORWARDED-SCHEMA-CHANGE, where you apply a DDL to the target. Here the column is already there; its pre-existing rows may be wrong. Since v0.156.2 the refused restart and the fleet supervisor's ERROR line both lead with this repair; on v0.156.1 they printed the generic "apply the same change to the target" step, with the right one only inside the recorded text (Bug 289):

1. Copy the added column's values from the source to the target for the rows that predate the ADD COLUMN, keyed by primary key.
2. Start once with --accept-unforwarded-schema-change=<fingerprint>, using the fingerprint the refused start prints — or, instead of step 1, re-copy by passing --restart-from-scratch on that same acknowledged start.

The record is deliberately conservative, so it can also appear when nothing was lost: after a kill in the seconds between a backfill completing and being confirmed, after a kill between the record being written and the ALTER, or after an ALTER that failed. Check the column against the source before you acknowledge. On a PlanetScale/Vitess source the confirmation arrives with the next change whose position has advanced, so on an idle source a stop before one arrives refuses. Not covered: on the Shape A fan-in, a hard kill after a peer shard's ALTER has filled this shard's rows and before this stream has seen its own ADD COLUMN; and a hard kill before sluice reaches the ADD COLUMN at all. After a crash that follows a source schema change, compare the added column against the source (sluice verify compares real rows). Plan schema changes so a stream is not stopped mid-backfill: wait for the backfill complete line.

A change the stream cannot carry stops it: UNFORWARDED-SCHEMA-CHANGE #

v0.156.0+, Postgres and MySQL/MariaDB binlog sources. Some source DDL cannot reach the target through any change stream, because neither stream describes the object: pgoutput's relation message carries column names, type OIDs and key flags only, and after a DDL the binlog reader rebuilds a table from information_schema as columns plus primary key only. Through v0.155.1 these changes were dropped with no log line, so the target stayed weaker than the source — for a policy, that is a security boundary. The sharpest shape was a single statement, ALTER TABLE t ADD COLUMN x int, ADD CONSTRAINT fk FOREIGN KEY (x) REFERENCES p(id), which forwarded the column and silently dropped the foreign key, on both engines.

• Postgres: ADD/DROP CONSTRAINT (primary key, UNIQUE, foreign key, EXCLUDE, CHECK), ENABLE/FORCE ROW LEVEL SECURITY, CREATE/ALTER/DROP POLICY, SET/DROP NOT NULL, SET/DROP DEFAULT, and identity or generated-column changes.
• MySQL and MariaDB: primary key and UNIQUE changes (a prefix-length change included), foreign key changes (columns, referenced table and columns, ON UPDATE/ON DELETE), CHECK changes (NOT ENFORCED included, on MySQL), and DEFAULT, EXTRA (AUTO_INCREMENT, ON UPDATE) or generation-expression changes on an existing column. Nullability is not compared there, because the column forward already carries it.

When the stream starts, sluice records these objects for every table in scope (the baseline). At the next write to a table after such a DDL it re-reads that table's catalog and compares; on any difference sync and backup stream end with UNFORWARDED-SCHEMA-CHANGE, naming each change, before the post-DDL row lands. It is never retried automatically, and an automatic retry after some other transient error keeps the baseline it started with, so a change made just before a dropped connection is still refused. What does not refuse, because the pipeline already handles it: the attributes of a column added in the same statement (but a constraint added with a new column does refuse — that is the foreign-key shape above), a constraint that disappears because its column was dropped, and ADD … NOT VALID followed by VALIDATE (validity is not compared).

Expression text is compared by value on MySQL and MariaDB (v0.156.2). MySQL re-spells a CHECK's string literals on any later ALTER TABLE — a CHECK created from a latin1 client session, even a pure-ASCII one, reads _latin1'…' before an unrelated ADD COLUMN and _utf8mb4'…' after — so through v0.156.1 the stream could stop with UNFORWARDED-SCHEMA-CHANGE on a change nobody made, and the refusal displayed a non-ASCII clause as mojibake ('xé' for 'xé'), which following step 1 below would have copied onto the target. The door now compares and displays each expression's decoded, value-level text (introducers and identifier quoting stripped; see type mapping), falling back to the raw text only where the decode refuses — still an exact comparison. On MariaDB, whose catalog writes ? for a character beyond the Basic Multilingual Plane, the door reads the same recovered text, so a change between two such expressions is no longer invisible; its start-time baseline reads base tables only (a VIEW over such a table broke every sync start on the server) and only the stream's own databases.

It is recorded, and every restart refuses again #

A restarted reader would take its baseline from a catalog that already holds the change, so without a record a systemd Restart=on-failure, a pod restart or a supervisor would accept it silently, forever. So the refusal is persisted: sync writes it on the stream's row of the target's sluice_cdc_state table (column unforwarded_refusal), and backup stream writes it in the destination's stream_state.json (key unforwarded_schema_change_refusal). Every later start reads it before any change stream opens and refuses again — warm resume, multi-database resume, --restart-from-scratch and --reset-target-data included — replaying the recorded refusal with its fingerprint <12 hex> (the first 12 hex digits of the SHA-256 of the recorded text) and the exact flag to pass.

Recovering: apply it to the target, then acknowledge once #

The drained-migrate runbook below does not clear this refusal — a plain restart with the same --stream-id just replays it. Instead:

1. Apply the same change to the target yourself. For backup stream, take a new full backup instead: a chain restored from the old full would lack the change.
2. Start the stream without the flag once if you do not have the fingerprint yet — the replayed refusal prints it.
3. Start once with the same --stream-id and --accept-unforwarded-schema-change=<fingerprint> (the same flag exists on backup stream run). It clears that record, logs a WARN naming what was accepted, and takes a fresh baseline.

# the replayed refusal names the change and prints: ... fingerprint 3f9a0c1b7e22
sluice sync start \
    --stream-id app-prod \
    --source-driver postgres --source 'postgres://...source...' \
    --target-driver postgres --target 'postgres://...target...' \
    --accept-unforwarded-schema-change=3f9a0c1b7e22

The acknowledgement is bound to one refusal. Only the fingerprint of the refusal recorded now clears it; a value naming any other refusal is refused ("names a different refusal than the one recorded"), and an empty value keeps refusing. The recorded text is stamped with the moment it was recorded, so the same change recurring later gets a new fingerprint. On sync, once the flag has cleared the record it is spent for the rest of the process. That is what makes a copy left in a systemd ExecStart line or a wrapper script harmless — it cannot accept the next, different refusal on the next automatic restart — but take it out anyway: it belongs on a single manual start. It is deliberately not a syncs.yaml key, because standing config would pre-accept refusals. Fleet legs have their own procedure: acknowledging a fleet leg.

To avoid the refusal altogether, make such changes through the drained model: sluice sync stop --wait, apply the change on source and target, restart. A change made while the stream is stopped is part of the next start's baseline, so it does not refuse.

What it does not catch #

• A change made while the stream was not watching — while it was stopped, during the cold-start copy, a DDL a lagging stream had not reached when it stopped, or anything before you upgraded to v0.156.0. It is already in the baseline. Upgrading does not find an old gap: if a Postgres or MySQL/MariaDB binlog stream ran through such DDL on an earlier release, audit those tables by hand (on Postgres compare pg_constraint, pg_policy, pg_class.relrowsecurity/relforcerowsecurity, pg_attribute.attnotnull and pg_attrdef; on MySQL/MariaDB information_schema.table_constraints, check_constraints, referential_constraints and columns.COLUMN_DEFAULT/EXTRA), and for backup stream take a new full.
• A table nobody writes to again — detection needs a later write to the same table. A change reverted before that read is missed (net no change).
• On MySQL, a DDL run under an out-of-scope default database (USE other; ALTER TABLE db.t …), which does not clear the reader's schema cache.
• Plain (non-constraint) indexes, a non-key Postgres column's collation, and policies or RLS on a partitioned Postgres root. A key column's collation is a different check since v0.159.0: it is judged at the first schema boundary (KEY-COLLATION-CHANGED) and on every upsert (KEY-COLLATION-MERGE).
• backup incremental, which opens a fresh reader every run, so a change between two incrementals is in the next run's baseline.
• PlanetScale / Vitess (VStream) sources, and the postgres-trigger, sqlite-trigger and d1-trigger engines, which this door does not reach. On VStream the whole gap is still silent — audit the target by hand after such DDL.

Known false refusals, each costing one acknowledgement: on MySQL, a DROP COLUMN b shrinks a composite UNIQUE (a, b) to UNIQUE (a) while Postgres drops the whole index, and the reader cannot see which the target did; on Postgres, a constraint rename refuses as a drop plus an add.

A target unique key the source does not enforce refuses: SOURCE-UNIQUE-KEY-ABSENT #

v0.162.0+, every sync source. Every insert reaches a sluice target as an upsert (INSERT … ON DUPLICATE KEY UPDATE on a MySQL-family target, INSERT … ON CONFLICT … DO UPDATE on Postgres). On MySQL the upsert resolves a conflict through any unique key the table has; on Postgres through the table's ON CONFLICT key only (a conflict through another key raises an error). A target unique key the source does not enforce can therefore turn the source's next duplicate of it into an overwrite of a different row. The usual cause is a source DROP INDEX no stream saw: made while the stream was stopped (the door above baselines at start, so the drop is in its baseline), or on a postgres-trigger, sqlite-trigger, d1-trigger, PlanetScale or Vitess source, whose change streams carry no DDL at all.

The apply-time check: UNIQUE-KEY-CONFLICT-OTHER-ROW (v0.161.1+). Every guarded upsert checks, inside the statement, that the row it matched carries the incoming row's primary key; on a table without one that has two or more unique keys, the check is agreement on every unique key's columns, compared NULL-safely. A mismatch refuses before anything is written, naming the target key. The refusal is terminal, carries no SLUICE-E-* code (exit 1), and a sync run leg that hits it is marked failed rather than restarted. Its remedy is to drop that unique key on the target and start again, or a re-copy: --restart-from-scratch for sync start (from a Postgres pgoutput source, after dropping the stream's replication slot), --reset-target-data --yes for sync from-backup run, which has no --restart-from-scratch. Both are destructive. It refuses most such merges at the first colliding row, but two shapes look to it exactly like a re-delivery of the same row: a table with no primary key and one unique key, and two rows that differ only in a NULL or partial-index column. Those are why the check below exists.

When it runs #

• At every start, for each table the stream applies to: the target's unique keys (its primary key included) are compared with the source's current ones, read from both catalogs after the change stream opens and before the first change is applied. That covers cold start, warm resume, --restart-from-scratch, --reset-target-data, each namespace of a multi-database stream, and every sync run leg start.
• At a schema change that moves a table's columns, or loses a unique key with a column, for that table, on every source, whether or not the change is forwarded. A Postgres source drops an index outright with a column it covers; a forwarded DROP COLUMN narrows a MySQL-family key that included the column (UNIQUE (a, b) becomes UNIQUE (a)); and a DROP COLUMN at the first boundary after a cold start is not forwarded at all, so the target keeps the column and the key on it. Nothing after the change is applied before the check, and a check that cannot read a catalog stops the stream at once with SOURCE-UNIQUE-KEY-RECHECK-FAILED rather than let the change through unjudged.
• Every 15 seconds on a postgres-trigger, sqlite-trigger, d1-trigger, PlanetScale or Vitess source, over the tables whose target has a unique key besides the primary key. When a re-check is due, the next transaction is held until it writes one of those tables (the re-check runs first) or commits without writing one (it goes on unchecked). An idle stream, or one that only writes other tables, costs nothing. Postgres (pgoutput) and MySQL-family binlog sources are not re-checked this way, because the door above already refuses a live DROP INDEX before the next row of the table.
• In schema add-table, for a pre-created target table, before it is copied. It refuses if it cannot read either catalog, and takes the same acceptance flag.

A target key passes when a source key implies it: the same columns, in any order, or a subset of them (rows distinct on (a) are distinct on (a, b)); a prefix c(10) implies c(20) and the whole column; the same expression or partial-index predicate in the same SQL dialect; and, across dialects, a key of the same name as the target spells it (a Postgres target prefixes an index name with its table: uniq_email becomes users_uniq_email) and the same shape. A key column whose target collation equates values the source's keeps apart (case-, accent- or trailing-space-insensitive where the source's is not) does not count as implied, and the refusal names that column. Keys sluice adds itself pass: a key copied from the source, the --inject-shard-column composite, and a surrogate the target generates on every insert (AUTO_INCREMENT, an identity column, MySQL's invisible primary key). The full rules, including which engines judge collation direction, are in CDC streaming.

The refusal and its three remedies #

The refusal names each key under its target table name (the renamed namespace on a multi-database stream, --target-schema when set). It carries no SLUICE-E-* code, so the process exits 1; match on the marker. It is not retried, and a sync run leg that hits it is marked failed rather than restarted, because every start reads the same two catalogs and nothing is recorded.

1. Drop the key on the target and start again, when the key was dropped while no stream was reading, or the target was built with it by mistake. On a Postgres or MySQL-family source the message says nothing written after the drop has been applied. Drop that key on the target (DROP INDEX, or ALTER TABLE … DROP CONSTRAINT for a constraint, which the message names) and start again with the same --stream-id. The same applies to a refusal at a schema change.
2. Re-copy, when rows may already have merged. That is the case when the mid-stream re-check found it; when a source whose change stream carries no DDL dropped the key while a stream was running; when sluice v0.161.0 or earlier was streaming from a Postgres source when its plain unique index was dropped; or when sluice v0.161.1 or earlier was streaming across a DROP COLUMN of a key column (no release through v0.161.1 checked the keys at a schema change). Dropping the key alone keeps the merged rows, so re-copy from a clean target: sluice sync start --restart-from-scratch or --reset-target-data --yes, with the same --stream-id. Both drop and re-create the stream's target tables from the source, the key and any merged row with them (destructive). From a Postgres (pgoutput) source, drop the stream's replication slot first (sluice slot drop <slot> --source-driver=postgres --source <DSN> --yes, with the full name sluice slot list prints): the re-copy's fresh snapshot refuses to inherit it. Under --inject-shard-column do not use --reset-target-data: the target table is shared by every shard, and it drops that table with every shard's rows. Drop the key on the target and re-copy this shard with --restart-from-scratch, which there re-copies onto the shared table without clearing it (so it cannot remove a row a merge left behind; unmeasured).
3. Accept the key by its fingerprint, when the target is meant to have it because it was built with it on purpose. Pass --accept-target-only-unique-key <table>.<key>=<fingerprint> with the value the refusal prints beside the key, on every start (repeatable; <database>.<table>.<key>=<fingerprint> on a multi-database stream, by the source or the target database name spelled exactly, and <schema>.<table>.<key>=<fingerprint> with the --target-schema the refusal prints). The fleet spec key accept-target-only-unique-key takes the same list; since the key stays on the target, the acceptance is standing, not one-shot. The fingerprint hashes the key's definition as the target engine itself reports it together with the definition of every column the key depends on, and nothing is normalised, so any change to an input refuses until the new printed value is passed — a DROP COLUMN or MODIFY … COLLATE that reshapes the key, but also a size-only widening, a rename, a MySQL column comment, or a server upgrade that respells a type or collation. An acceptance is honoured only while the key still hashes to its fingerprint, at every check (the start, a schema change, the periodic re-check, schema add-table). A functional key part on a PlanetScale or Vitess target cannot be fingerprinted, so such a key cannot be accepted: drop it. On a multi-database stream, a <table>.<key> acceptance that matches the key in more than one database refuses at the start; name the database. The apply-time check still refuses a merge through an accepted key wherever it can tell the rows apart.

# a key the target was built with on purpose: accept it on every start
sluice sync start \
    --stream-id app-prod \
    --source-driver postgres --source 'postgres://...source...' \
    --target-driver mysql --target 'mysql://...target...' \
    --accept-target-only-unique-key 'users.uniq_email=<fingerprint the refusal prints>'

SOURCE-UNIQUE-KEY-RECHECK-FAILED is not the refusal. A periodic re-check that cannot read a catalog logs a WARN containing it, and the next due check tries again; four failures in a row stop the stream with that marker, because on the sources that carry no DDL the re-check is the only mid-stream protection. A failed read at a schema change stops the stream at once with the same marker. Either way it is an ordinary failure: a restart retries it, and a sync run leg is restarted under its failure cap.

What this does not catch #

• Mid-stream on the sources that carry no DDL, the transactions applied between the source's drop and the next due re-check (up to 15 seconds of them). For the two shapes the apply-time check cannot see, a merge in that window is applied; the re-check then refuses and names a re-copy. The trigger engines refuse a table without a primary key at setup, so on them those shapes cannot occur; a PlanetScale or Vitess source can carry one.
• A mid-stream primary-key change on those sources: only tables with a unique key besides the primary key are re-checked. The next start catches it.
• A source key dropped, a duplicate written and removed, and the key re-created, all between the stream's last position and its start: the key looks unchanged at start. The apply-time check refuses the replayed duplicate where it is armed; on the two shapes above it is silent.
• A cross-dialect functional or partial key redefined under its old name passes (pinned as a known miss). One renamed on either side refuses; accept it by name.
• Column collation direction from a Postgres or SQLite source into a MySQL-family target: a Postgres text key is byte-exact and the column sluice creates for it takes the target's case-insensitive default, so judging it would refuse every such stream; KEY-COLLATION-MERGE refuses that merge at apply time for a unique key beside a primary key. A Postgres nondeterministic collation counts as folding both case and accents (which one it folds is not recorded), so a MySQL _as_ci key against a Postgres ICU ks-level2 column refuses although only case folds there; accept it by name. Two collations with the same axes but different folding tables (MySQL utf8mb4_general_ci and utf8mb4_0900_ai_ci, which disagree on characters such as ß) count as equal; only an operator-built target can hold such a pair, since sluice copies or maps the source collation. On a PlanetScale or Vitess source the collation is judged at each start and, for a table whose target has a unique key besides its primary key, at each 15-second re-check, so a key column moved to a stricter collation mid-stream can merge up to one re-check interval of rows first (KEY-COLLATION-MERGE is unarmed on those sources).
• The source catalog is read when a check runs, so it can be ahead of the stream, and the check refuses any target key the source catalog does not enforce at that moment, at every start and every schema change. That includes a key the source will lose only through a DROP COLUMN the stream has not reached yet, which the check cannot tell apart from a key the source dropped on its own, earlier, with duplicates written before the column went (a real merge). Two cases refuse although replaying the stream would have forwarded the DROP COLUMN and dropped the key: a DROP COLUMN of a unique-key column made while the stream was stopped, refused at the start; and one the source has already made while the stream lags behind it, refused at the earlier schema change. A plain restart refuses again at the start, because the stream never gets past the change it stopped before. Drop the named key on the target and start again with the same --stream-id. That converges, and any duplicate the source wrote then lands as its own row (measured for both cases, into Postgres and MySQL). Re-copying works too.
• On a PlanetScale or Vitess source, whose change stream carries column changes but not index changes, a due 15-second re-check can read the target while a forwarded DROP COLUMN is still being applied there, and refuse a key that DROP is about to remove. It is loud, a restart clears it, and it needs a due re-check to coincide with such a DROP. The trigger engines forward no schema change at all, so it cannot occur on them.
• Tables added with schema add-table --no-drain while the stream runs join the re-check at the next start.
• The check needs the target tables to exist, so on a cold start into a pre-created target an extra key refuses after the copy, not before it (the copy itself cannot merge through such a key).
• sync from-backup run and sluice restore do not run this check. A backup chain records a source DROP INDEX as a schema change of the window it falls in, and both apply it to the target before that window's rows, so the duplicate lands as its own row (measured for a MySQL source). A target pre-created with an extra unique key is not judged there.

A table the stream never brought in refuses a warm resume: INCLUDE-TABLE-SCOPE-DRIFT #

Since v0.163.0, every sync source. A warm resume copies nothing: it continues the change stream from the persisted position. So a table that joins the stream's scope on a restart is never copied. On a Postgres pgoutput source a table outside the publication is not even streamed; a table the publication delivers anyway, or any table on a MySQL-family, VStream or trigger-CDC source whose target table exists, is streamed from the persisted position onto a target copy missing everything before it. Through v0.162.0 the stream came back green in every one of those shapes (Bug 321; see the v0.163.0 note). A table joins a running stream through sluice schema add-table, never through the flags of a restart.

The record each stream keeps #

Since v0.163.0 each stream keeps three records on its sluice_cdc_state row:

• established_tables: the tables each cold start actually copied (every lane; each namespace of a multi-database stream; --restart-from-scratch rewrites it), plus every schema add-table that completed, each with its engine-stable id. A cold start leaves it untouched until its point of no return — immediately before the target drop of --restart-from-scratch or --reset-target-data, or, when nothing is dropped, immediately before the copy's first write to the target — and there marks it cold start in progress; the copied set replaces the mark when the cold start finishes. (--reset-target-data then deletes the control row, mark and all, so its anchor records the copy as a first cold start's does.) So a cold start refused before that point (the "slot already exists" refusal, a schema preflight) leaves the record as it was, even though it may already have widened the publication, and one that stopped after it leaves a mark every warm resume refuses (COLD-START-INCOMPLETE, below). A stream that has a record never goes back to having none.
• dropped_tables: established tables a later restart's scope left out. Their changes are discarded from then on — on pgoutput the table stays in the publication and the stream drops its changes — so the target copy goes stale.
• pending_added_tables: each schema add-table in flight. It is written before the add changes anything, under a token unique to that add-table run; its heartbeat is refreshed every 30 seconds while it copies, and once the copy is handed to the stream the entry is removed and the table recorded as established in one transaction. Every write after the first compares the token, so an add whose entry was marked abandoned by --abandon, or taken over by another add-table of the same table, stops with PENDING-ADD-SUPERSEDED (a heartbeat that finds this cancels the copy) and records nothing; the target table may then hold a partial copy. A failed add marks its entry no longer running and, on a Postgres source, takes back the publication add it made. Heartbeats are stamped and compared in the control-table server's clock, never a host's; one more than a minute ahead of the server's clock counts as stale and is named in a WARN.

A stream cold-started by an earlier release has no record until its next cold start; sluice does not seed one from the current scope, which would record a never-copied table as copied. Until then the check falls back to the stream's publication on a pgoutput source, for literal includes, and only when no other sluice replication slot exists on the same database (a slot on another database of the server cannot read the publication, so it does not count). Otherwise every resume logs INCLUDE-TABLE-SCOPE-UNRECORDED and there is no evidence; to get full protection, run one --restart-from-scratch after upgrading. A first cold start that cannot bring the record's columns up to date (missing, or of a type sluice refuses, on a control table this role or branch cannot ALTER — see the safe-migrations ALTER) logs COLD-START-ANCHOR-UNRECORDED at its anchor and INCLUDE-TABLE-SCOPE-UNRECORDED at its record write, and runs without the record. Those are the only ways to have no record.

What refuses #

On every start — each sync start, and each start of a sync run leg, restarts included — before the reader opens, a warm resume refuses with a codeless exit-1 error containing INCLUDE-TABLE-SCOPE-DRIFT, naming each table and why, for:

• a table an --include-table entry names literally that the stream never copied. A literal entry has no *, ?, [ or \ (a backslash makes an entry a glob), is compared case-sensitively, and a schema-qualified entry such as app.t names no table (it admits none either);
• a dropped table that any scope re-admits — literal, glob or unfiltered;
• a never-copied table admitted by a glob or an unfiltered stream whose changes would be applied: its publication delivers it (shared with another stream, FOR ALL TABLES, a multi-schema stream's spanning publication, or a missing publication the reader would recreate FOR ALL TABLES), or, on a source with no publication, its target table exists;
• an established table that a FOR TABLE publication no longer lists — dropped and recreated on the source, or removed from it — shared or not;
• an established table that is no longer the same table on the source (TABLE-IDENTITY-CHANGED, below);
• an in-scope table whose add-table entry has gone stale (heartbeat older than five minutes: the add died);
• any stream whose record reads cold start in progress: a cold start passed its point of no return and did not finish, so the persisted position no longer describes the target. The message carries COLD-START-INCOMPLETE; re-run the cold start (--restart-from-scratch, or --reset-target-data, whichever was interrupted).

Nothing has been applied. Every restart repeats it and sync run does not restart the leg. A table whose add-table is still running (fresh heartbeat) is judged by that add alone: being never copied, or re-admitted after a drop, is exactly what the add's completion cures. When every refused table is such a table, the resume defers with INCLUDE-TABLE-ADD-IN-PROGRESS, which the fleet supervisor restarts, and once the add completes the stream resumes; a conviction on any other table — or an established table gone from the publication, which an add does not cure — keeps the terminal refusal.

A never-copied table whose changes are provably not applied — outside the publication, or with no target table (the applier already skips those loudly, sluice_cdc_skipped_tables, sync health) — does not refuse: it stays out until schema add-table brings it in, and every resume names such tables in an INCLUDE-TABLE-NOT-ESTABLISHED WARN. That is the whole cost of the rule: those tables are not replicated until you add them. A pending add for a table since dropped or renamed on the source is ignored with a WARN. Remedies, per named table:

1. With the stream stopped, empty the target table and run sluice schema add-table <table> with the stream's --source-driver, --source, --target-driver, --target and --stream-id, then the same sync start again. (Not on a multi-database stream: add-table cannot record a table there, and the refusal names only the re-copy.)
2. Take the table out of scope (--include-table / --exclude-table). For a table schema add-table brought in, neither flag does it — --include-table does not remove it and an --exclude-table naming it is refused — so run sluice schema add-table --abandon <table> --yes, then restart.
3. Re-copy every table with --restart-from-scratch. On a Postgres source that run first refuses because the stream's replication slot exists; drop it with sluice slot drop, then re-run. The re-copy rewrites the records and clears the pending entries of the tables it copied.

A table schema add-table brought in stays in scope #

Since v0.163.0 the add records the table in the stream's live-added set (live_added_tables on the control row), on every source and path — the mechanism MySQL's --no-drain path has used since v0.27.0. Every later start reads the set and admits its tables whatever --include-table says, so the staged-wave flow (an --include-table 'orders,order_items' stream, sluice schema add-table of users, then the same sync start command again) keeps streaming users. Through v0.162.0 only the MySQL --no-drain path recorded it, so on a Postgres source, or after any drained add, that restart dropped every change to users at the dispatch filter, silently. One thing takes an added table back out: sluice schema add-table --abandon <table> --yes, which for a completed add takes it out of the live-added set; the next start narrows it, below. A cold start — --restart-from-scratch, an interrupted copy's resume, or the re-snapshot after an invalid position — copies the live-added tables along with the ones the flags name: the copy covers exactly what the stream will apply. --reset-target-data is the exception, because it deletes the control row the set lives on: its copy and its stream cover only the flags' scope, and a WARN names each live-added table discarded, whose target table is left as it was and receives no further changes. Name such a table in --include-table, or schema add-table it again, to keep replicating it.

On a MySQL-family target, schema add-table refuses at its preflight, before it changes anything, a table whose name contains a comma or begins or ends with whitespace (a codeless exit 1): the live-added set there is a comma list, trimmed on read, so the name would read back as other tables. To stream such a table, name it in --include-table with a glob that matches it (? for each comma or edge space, for example foo?bar) and re-copy with --restart-from-scratch, or rename the table. A warm start that finds a live-added entry the source catalog does not hold logs LIVE-ADDED-TABLE-NOT-IN-CATALOG naming the entries. Either the table was dropped on the source, or, on a MySQL target, the entries are fragments of a comma name an older release recorded, which no longer admit that table. Check each, and sluice schema add-table <table> --abandon --yes (with the stream's flags) any entry that should not be there. A SQLite or D1 target keeps no live-added set or established-table record: schema add-table onto one WARNs that the table must be named in --include-table on every restart, and a restart that does not name it stops applying its changes with nothing at that restart saying so.

sync health reports a pending add-table that is still running as in progress with exit 0, so a cron probe does not page through every normal --no-drain add, and one whose heartbeat went stale as ADD-TABLE INCOMPLETE with exit 1; the text sync status lists both (fields and exit codes). For an entry no add-table can clear — its table was dropped on the source, or taken out of the stream's scope — run sluice schema add-table --abandon <table> --yes with the stream's driver, DSN and --stream-id flags. It refuses while the add is still running. Otherwise it takes the table out of a Postgres publication unless the stream established it or another sluice slot exists on the same database, drops the dead add's snapshot slot (sluice_addtable_<table>, or the --slot-name you pass) when it is inactive, and leaves the target table as it is, which may hold a partial copy. It does not remove the entry: it marks it abandoned, because a running stream may still be applying the table's changes onto that partial copy (the publication may still deliver it), and only a stream start judges the table. Until then sync health exits 1 with ADD-TABLE ABANDONED: restart the stream, and --abandon says the same. Restart the stream. A start that finds the table out of the stream's scope, gone from the source, or with changes provably not applied clears the entry; any other start refuses INCLUDE-TABLE-SCOPE-DRIFT naming the abandoned add, and the remedies above apply. A completed re-run of schema add-table for the table, or a cold start that copies it, also clears it.

An --exclude-table that names an added table refuses: LIVE-ADDED-TABLE-EXCLUDED #

Since v0.163.0. The add said the table is in the stream's scope, and the exclusion would apply none of its changes, so the target copy would go stale while the stream reported healthy. Every start refuses it before copying, dropping or applying anything (a codeless exit 1 carrying INCLUDE-TABLE-SCOPE-DRIFT, which the fleet supervisor does not restart), and so does a running stream: schema add-table cannot know the stream's flags, so a --no-drain add of a table the running stream excludes completes (or, if the stream sees it first, stops with PENDING-ADD-SUPERSEDED), and the stream stops when its live-added poll reads the add. Changes to the table that reached it between the add and that poll (at most one poll interval, 5 seconds — the window every live add has, ADR-0034) were dropped as excluded while other tables' changes moved the persisted position past them, so before stopping the stream writes that to its control row in one locked transaction: the table's add-table entry is marked abandoned (a still-running add stops and records nothing), the table moves to the dropped set, and it leaves the live-added set. From then on the table comes back only with a fresh copy — narrow --exclude-table, empty the target table and schema add-table it again, or --restart-from-scratch — and a restart that only narrows the exclusion refuses (INCLUDE-TABLE-SCOPE-DRIFT, dropped). Keeping the exclusion leaves the table out and the next start passes. If that control-row write fails — or commits but cannot record the table as dropped, because the stream has no established-table record (cold-started by an earlier release), keys a multi-database record, or is mid cold start — the stream still stops and logs it at ERROR; then nothing on record stops a restart that only narrows the exclusion, and the refusal says so — with the exclusion still in place every start keeps refusing. At a start (nothing streamed yet), decide which you meant: to keep the table, narrow --exclude-table so no pattern matches it; to take it out, --abandon it as above. Through v0.162.0 a MySQL --no-drain add silently won over the exclusion instead (ADR-0034's additive rule).

A table renamed while the stream was stopped is followed, not refused #

Since v0.163.0 the record keeps each established table's engine-stable id beside its name (Postgres and postgres-trigger sources: pg_class.oid; MySQL and MariaDB: InnoDB TABLE_ID). On a warm start, an established table whose name is gone from the source, whose id now belongs to a new in-scope name, is that table renamed: the record takes the new name and keeps the id, and nothing refuses — provided the target was renamed too: it holds the new name and no longer holds the old one, as the drained-model recovery leaves it. Otherwise the start refuses saying the target was not renamed — including when the target holds a table under the new name beside the stream's copy under the old one: that new-named table is some other table, and following the rename would apply onto it and strand the real copy. Drop or rename such a table away first. A table dropped and re-created under a new name has a new id and refuses as never copied. Where no id proves a rename — a PlanetScale or Vitess source (vtgate does not expose the InnoDB dictionary), a table name InnoDB stores in its filename encoding, every table of a database whose name is so encoded (for example my-db, which leaves the whole stream without ids), a partitioned table, or a record written without ids — the refusal names --accept-table-rename <old>=<new> on sync start: a human's statement that the new table is the old one renamed, after renaming the target too; the record then follows it, under the same target rule (new name present, old name gone). sluice cannot check what the target table under the new name holds, so with the flag it is trusted as-is. A pair that matches no rename only WARNs, so the flag does nothing once the rename is followed. It has no syncs.yaml key: take the leg out of the fleet for the one start that needs it.

A table that is no longer the same table: TABLE-IDENTITY-CHANGED #

Since v0.163.0 an established table whose engine id no longer matches the record refuses inside INCLUDE-TABLE-SCOPE-DRIFT. On a Postgres or postgres-trigger source any change of pg_class.oid under the same name counts — VACUUM FULL, CLUSTER, TRUNCATE and rewriting ALTERs keep the oid (only relfilenode changes), so a changed one means the table was dropped and re-created, or swapped with another, while the stream was stopped. On MySQL and MariaDB InnoDB gives a table a new TABLE_ID on OPTIMIZE TABLE, a copying or rebuilding ALTER and TRUNCATE, so a changed id alone is not refused there: the record takes the new id, and a WARN names the old and new id; a DROP and re-CREATE under the same name looks the same there (TABLE-RECREATED-WHILE-STOPPED, below). Both engines refuse a swap (RENAME TABLE t8 TO tmp, t9 TO t8, tmp TO t9, or the same in three ALTER … RENAMEs), proved by one name's recorded id now belonging to another, and the message says which table each name now holds. The remedy is a re-copy of the table: empty its target table and schema add-table it, or --restart-from-scratch.

A narrowing is logged and recorded, or the start refuses: INCLUDE-TABLE-NARROWING-UNRECORDED #

A start whose scope no longer holds an established table logs a WARN naming it — its changes are no longer applied, and bringing it back later refuses until it is copied again — and moves it to dropped_tables in one locked write. If that write cannot be made (the dropped_tables column missing on a control table this role cannot ALTER, a lost connection), the start refuses with INCLUDE-TABLE-NARROWING-UNRECORDED instead of going on, because a narrowing nobody recorded would let a later re-widen pass a table whose changes were discarded: restore the scope the stream had, or fix what the error names and start again. The three record columns are added together, in one first write, and a refusal for a missing one names the statement that brings them up to date, built from the columns the table has (on MySQL that includes live_added_tables, added if missing or widened to LONGTEXT CHARACTER SET utf8mb4); sluice control-tables ddl prints them (and live_added_tables) with the rest of the control table. A pre-existing record column of any type but LONGTEXT (MySQL family) or TEXT (Postgres) is refused with the ALTER that fixes it: a shorter type would cut a long record where nothing could tell.

A record that does not decode (hand-edited, truncated, corrupted) is never read as some other set. A start refuses INCLUDE-TABLE-SCOPE-DRIFT naming the column and the recovery. For established_tables or dropped_tables the recovery is a re-copy (--restart-from-scratch): the cold start overwrites the record without reading it (an ERROR line names the discarded value's length). The dropped set cannot be rebuilt from an unreadable value, so the cold start records as dropped every table the source catalog holds that the copy did not cover; a later start then refuses each of those if a scope re-admits it, while a table created after the re-copy is judged like any never-copied one. Only when the cold start cannot read the catalog does it record the catch-all "every table this copy did not cover counts as dropped", and the next cold start that can read the catalog replaces it. A pending add-table entry that does not decode is reported rather than failing the command: sync health exits 1 and prints its raw text, sync status lists it, and a start refuses the table it names; sluice schema add-table --abandon <table> --yes retires it. An entry with no readable table name, or a pending column that does not decode at all, is cleared with the SQL the message gives (UPDATE sluice_cdc_state SET pending_added_tables = NULL WHERE stream_id = '…'), after which the tables it named need schema add-table or a re-copy.

What the check still cannot see #

• A running stream. The check runs when a stream starts, and apart from LIVE-ADDED-TABLE-EXCLUDED (above) nothing re-checks a stream that is already running. Everything else in this section that arises while a stream runs — an add-table killed mid-copy, an abandon of an add whose table the stream is still applying, the window below between a cold start's anchor write and its record write — is caught at the next start, not before. sync health is the running-stream signal (ADD-TABLE INCOMPLETE, ADD-TABLE ABANDONED); alert on it.
• A process killed in the middle of schema add-table cannot take back its publication add, so a running stream keeps applying into the partial copy until sync health reports the entry stale or the stream restarts and refuses. The add's snapshot slot is persistent and survives the kill too, until --abandon (or sluice slot drop) removes it.
• A table dropped and re-created under the same name while the stream was stopped (TABLE-RECREATED-WHILE-STOPPED), where the record carries no id for it: on Postgres that is a record written before ids were recorded (until the stream's next cold start or schema add-table of the table), under a FOR ALL TABLES or FOR TABLES IN SCHEMA publication — a FOR TABLE publication drops the table on DROP TABLE, which the check catches without an id. On MySQL and MariaDB it is every such table, because a changed TABLE_ID there is as likely a rebuild (above); the binlog the resume replays carries the DROP/CREATE, and whether anything in that replay catches it has not been measured. A swap is caught on both engines wherever ids are recorded. On MySQL that excludes the tables listed above as having no id (filename-encoded table or database names, partitioned tables), so a swap made there while the stream was stopped is not seen.
• A Postgres table dropped and re-created while an interrupted cold start was stopped, before it resumed (RESUMED-COLD-START-CERTIFIES-RECREATED-TABLE, HIGH, silent; present since v0.149.0, not fixed in v0.163.0). The stopped-cold-start resume (COLD-START-RESUMED) tracks copy progress by table name and reads the ids it records after the stop, so it certifies the new table without re-copying it. See the v0.163.0 note.
• A process killed between a later cold start's anchor write and its record write (--restart-from-scratch, an interrupted copy's resume, the re-snapshot after an invalid position) leaves the in-progress mark, so the next warm resume refuses COLD-START-INCOMPLETE although the cold start had finished — loud, and a re-copy clears it. A stream's first cold start has no control row until that anchor, and neither has a --reset-target-data cold start, which deletes the row (its in-progress mark with it) before copying, so the anchor write itself records the copied tables with their engine ids, in the same transaction, and a kill after it warm-resumes on that record. Where the control table's record columns cannot be brought up to date (missing, or a type sluice refuses, such as a MySQL live_added_tables that is TEXT or not utf8mb4 and cannot be widened), the anchor is written alone, as before, and a WARN carrying COLD-START-ANCHOR-UNRECORDED names the error.
• On a multi-database stream, each database's cold-start refusals (a populated target, a pre-existing foreign key, the target-side preflights) run when that database's turn comes, after earlier databases were already copied — and, under --restart-from-scratch or --reset-target-data, dropped. A refusal there is loud and every re-run repeats it after re-copying the earlier databases; fix what it names. On a single-database stream every deterministic refusal runs before the record is marked and before anything is dropped.
• A LIVE-ADDED-TABLE-EXCLUDED stop that cannot record the table as dropped (above) leaves a restart that only narrows the exclusion unprotected, and its refusal says so.
• sync status --format json does not carry the pending record yet (sync health --format json does).
• An in-scope table with no capture trigger on a trigger-CDC source captures nothing, at cold start as well, which is a separate class.

After a restart, the first boundary is checked against the target: RESUME-SCHEMA-DIVERGENCE #

v0.156.10+, under --schema-changes=forward. When sync starts on a stream that already ran — a warm resume, a restart, a sync run leg restart, an automatic retry after a transient error — it has no record of a schema change made since: while it was stopped, or after it restarted and before the table's next row. So each table's first schema boundary on such a start is compared with the target table itself, column names and types. A column named by --type-override is compared by presence only (its type is yours), so an override changed between runs is not seen here. Postgres and PlanetScale/Vitess sources produce that boundary at each table's first change; MySQL and MariaDB binlog sources do too since v0.156.10, in every schema-changes mode.

• They match: nothing happens.
• The source has columns the target lacks: they are added and backfilled from the source, with the same ADD-COLUMN-BACKFILL-INCOMPLETE guarantee as a live ADD COLUMN.
• Exactly one column the source widened within its family (a temporal precision, a decimal's integer digits or scale, a CHAR/VARCHAR length, FLOAT → DOUBLE, an integer width of the same sign): the change is applied, logged at INFO as forwarding the difference (target-witnessed, GC-44) with a difference= attribute. An array column whose element widened refuses instead.
• Exactly one column the source narrowed, with proof: applied only when the stream's retained schema history proves it. That proof is possible only on a MySQL or MariaDB binlog source, where the boundary must lie strictly after that history version in the source's own position order; a narrowing back to a shape the table held before also counts. The INFO line's difference= says narrowed from.
• A column the target already holds wider, with no such proof: kept, with a WARN (the target column is WIDER than the source's), because it cannot be told apart from a target someone widened on purpose. Wider means within the family, or across families where the target's type holds every source value: TEXT for VARCHAR, a wide-enough NUMERIC with a non-negative scale for an integer, a wider signed integer for an unsigned one, or an ENUM/SET label superset (a SET's in the same order). CHAR across families and jsonb for json never count as wider. If the source really did narrow the column, the target's existing rows kept values the source's ALTER converted: narrow the target or re-copy the table.
• Columns only the target has: kept, with a WARN naming them (target_only_columns).
• A key column's collation or character set changed (v0.159.0+): judged against the source's own earlier shape of the table and forwarded; with no earlier shape on record, a key whose collation differs from the target's stops the stream with RESUME-SCHEMA-DIVERGENCE carrying KEY-COLLATION-CHANGED. A key-collation change together with any other difference in the same boundary also refuses.
• Anything else — columns added and removed together (a possible rename), more than one changed column, a cross-family change the target's type does not hold (a source VARCHAR → TEXT made while stopped), a decimal widened on one axis and narrowed on the other: the stream stops with RESUME-SCHEMA-DIVERGENCE, naming each column with both types, before anything after the boundary is applied or recorded.

The refusal carries no SLUICE-E-* code, so the process exits 1; alert on the marker. It is not retried automatically, and a sync run leg that hits it is marked failed rather than restarted (fleet). The check records nothing, so the next start checks again: make the target table match the source (the drained model), then start with the same --stream-id. Under --inject-shard-column (Shape A) a difference the check forwards goes through the shard-consolidation lease, so a change made on every shard's source while the fleet was stopped is applied once, and a column a peer shard added is backfilled on every shard's rows from that shard's own source.

Streams that forward no DDL: SCHEMA-CHANGE-REFUSED #

v0.156.10+. Four kinds of stream forward no source DDL: --schema-changes=refuse; a MySQL multi-database stream (--all-databases, --include-database, --map-database); a Postgres multi-schema stream (--all-schemas, --include-schema); and --inject-shard-column with --no-coordinate-live-ddl (Shape A's drained model). Since v0.161.0 a pgtrigger source gets the same check whatever --schema-changes says (below). Through v0.156.9 none of them checked schema changes either: a boundary went straight to the applier, which recorded it as history and carried on, so a DATETIME → DATETIME(6) or numeric(10,2) → numeric(10,4) was rounded into the target at exit 0 — measured on MySQL 8 and Postgres 16 under refuse, and on a MySQL 8 multi-database stream. A Postgres multi-schema stream produced boundaries only for the schema the source DSN names, so in every other selected schema even a change made while the stream ran went unchecked; it now produces them for every selected schema. Now every boundary — a DDL while the stream runs, and each table's first change after a start, which covers a change made while it was stopped — is compared with the target table, column names and types:

• They match: the boundary passes.
• The target's column holds every value the source can send — wider within its family, or across families by the rule above — and nothing says the source narrowed it: passes with a WARN. This is the drained model: the target was changed ahead of the source.
• A column only the target has, with no earlier shape on record showing the source had it: passes with a WARN (target_only_columns); it receives no values from this stream.
• A source column the target lacks, or a type the target's column cannot hold — DATETIME → DATETIME(6) against a timestamp(0) target, a larger decimal scale, a longer VARCHAR, a sign change at the same width: SCHEMA-CHANGE-REFUSED, naming each column with both types, before the boundary is recorded or any row after it is applied.
• The source narrowed a column, as the stream's own earlier shape of the table shows (its last boundary in this run, or its retained schema history): SCHEMA-CHANGE-REFUSED, the type marked narrowed from …. The source's ALTER converted the rows it stores; the target's copies never were. On a binlog source a boundary that lies after that earlier shape in position order is judged whatever it shows, a narrowing back to an earlier shape included; one that lies before it is a replay and never counts.
• A DROP COLUMN the target still holds, by the same evidence: SCHEMA-CHANGE-REFUSED, named as the likely RENAME COLUMN when a column the target lacks comes with it.
• A Postgres column replaced under the same name (its attnum changed between two boundaries of this run): SCHEMA-CHANGE-REFUSED. Drop and re-add it on the target, copy the source's values into it, and restart. On a MySQL/MariaDB binlog source the same replacement refuses COLUMN-IDENTITY-CHANGED instead, at the ALTER itself and when a resume replays it (v0.159.0+).
• A key column's collation or character-set change (v0.159.0+): SCHEMA-CHANGE-REFUSED carrying KEY-COLLATION-CHANGED. Apply the same change on the target and restart.

The refusal is codeless and exits 1, and a sync run leg that hits it is marked failed rather than restarted. Nothing is recorded, so — except in the AMBIGUOUS case — nothing needs acknowledging: apply the same change to the target table (sluice sync stop --wait first if the stream is still running), then start again with the same --stream-id. A single-database stream under refuse can instead switch to --schema-changes=forward; a multi-database or multi-schema stream and --inject-shard-column have no forward path. The drained model does not backfill: an ADD COLUMN you run on the target fills the rows it already holds with that ALTER's DEFAULT (or NULL), and only rows changed after the restart carry the source's values — copy the column's existing values across yourself if they matter (--schema-changes=forward does backfill a forwarded ADD COLUMN). A --type-override column is judged on width: a source type that outgrows the override refuses, and so does a source narrowing; the override's own deliberate narrowing passes while the source's type is unchanged since the table's last accepted shape or the cold start. On a Postgres source the reader's own gate still refuses first, with incompatible schema change mid-stream, an ALTER COLUMN TYPE, DROP COLUMN or RENAME COLUMN on a table it has already seen in the session; this check judges what that gate lets through.

A pgtrigger source: the first-touch boundary and TRIGGER-SOURCE-LIVE-DDL-COORDINATION (v0.161.0+) #

Since the fix for KEY-COLLATION-TRIGGER-CDC-NO-HISTORY, a postgres-trigger stream reads each table's shape from the source catalog at the table's first change of every session and hands it to the target ahead of that change. That is what lets a MySQL-family target refuse (KEY-COLLATION-MERGE) a row the source keeps apart from another only by case. The shape is also recorded in the target's sluice_cdc_schema_history and in a backup's manifest, as a native Postgres stream's is. On the event-trigger tier the table's columns and keys are read once per schema per session and each table's collations at its own first change; on the trigger setup --allow-polled-fingerprint tier each table is read at its own first change, and a change made after that is not seen until the next session.

Because the shape is read as the catalog stands, a schema change made while the stream was stopped can show in it before the stream reaches that change's own DDL marker. A trigger-CDC source therefore runs the same boundary check as --schema-changes=refuse, whatever that flag says: a table the target cannot hold stops the stream with SCHEMA-CHANGE-REFUSED. The remedy, which the reader's own observed-DDL refusal now gives too (it used to say to run sluice migrate first, which cannot run on a populated target): drain the stream, then re-run sluice sync start --restart-from-scratch, which drops and recreates the stream's tables on the target from the source's current schema and re-copies them. Under --inject-shard-column the consolidated table is shared and the restart does not drop it: apply the same change to it and delete this shard's rows from it first. Under --schema-already-applied the restart drops and recreates nothing either: apply the change on the target and empty the stream's tables first. With the DDL event triggers installed (the default tier), applying the change on the target and restarting at the same position is not enough, because the reader reaches the change's DDL marker and refuses again.

TRIGGER-SOURCE-LIVE-DDL-COORDINATION. Under --inject-shard-column, live cross-shard coordination would forward that first-touch shape to the consolidated target, so a postgres-trigger source refuses it at start. Pass --no-coordinate-live-ddl. sqlite-trigger and d1-trigger emit no such shape and are not refused.

Downgrading past v0.161.0. An older binary refuses to warm-resume a postgres-trigger stream whose target holds postgres-trigger rows in sluice_cdc_schema_history, because it cannot order them. Delete those rows (DELETE FROM sluice_cdc_schema_history WHERE source_engine = 'postgres-trigger', adding AND stream_id = '<stream-id>' to downgrade one stream) before starting the older binary, or restart from scratch.

A source DROP INDEX on a unique index. A postgres-trigger change stream carries no index DDL, so the target keeps a key the source dropped. Through v0.161.0 the source's next duplicate of that key merged into a different target row at exit 0 (HIGH, silent; SOURCE-DROPPED-UNIQUE-KEY-MERGE). v0.161.1's UNIQUE-KEY-CONFLICT-OTHER-ROW refuses most such merges at the first colliding row, and since v0.162.0 SOURCE-UNIQUE-KEY-ABSENT catches the dropped key itself at every start and, mid-stream, at the next due 15-second re-check. Not covered: the transactions applied between the source's drop and that re-check (up to 15 seconds of them). The two merge shapes the apply-time check cannot see need a table without a primary key, which the trigger engines refuse at setup, so on a postgres-trigger source those cannot occur. The full list is with the check.

On a Postgres source: AMBIGUOUS-SCHEMA-BOUNDARY #

Postgres schema boundaries are anchored at LSN 0/0, and their schema history keeps one shape per table (GC-44 F23), so position order cannot place a boundary after the stream's earlier shape. A narrowing or DROP COLUMN whose only evidence is that earlier shape is then one of two things: a replay — a transaction that wrote rows, ran ADD COLUMN (or a widen) and wrote again, re-delivered from its start after a restart or an automatic retry, presenting the table as it was before a change the target already holds — or a change made on the source that this stream has not applied. Accepting the second would be silent loss, so the stream still stops with SCHEMA-CHANGE-REFUSED; the refusal carries AMBIGUOUS-SCHEMA-BOUNDARY, names both readings, and offers no remedy that destroys data. Do not change the target yet:

1. Compare the source's current table definition (\d in psql) with the target's. If the source's column is narrower than the target's, or gone, it is a source change: apply it to the target and restart.
2. A match is consistent with a replay but does not prove one: a column narrowed and widened back, or dropped and re-added, while the stream was stopped matches too. So also confirm that nobody ran DDL on that table while the stream was stopped.
3. If both hold, change nothing on the target and start once with --accept-unforwarded-schema-change=<fingerprint>, the fingerprint the refusal prints. If you cannot rule the DDL out, re-copy the table (or the column's values) from the source instead, which is safe either way.

The fingerprint covers the table, the refused columns and the position the stream resumed from, so it accepts only the replay re-delivered from that position: a later boundary of the same shape — a genuine narrowing after the stream applied past the replay, say, with the flag left in a unit file — gets a different fingerprint and refuses. Within one process the value is dropped as soon as a retry resumes from a later position, and nothing is recorded for it. If the stream persisted progress before reaching the boundary, the next refusal prints a new fingerprint; acknowledge that one. Under sync run the fleet spec has no acknowledgement key, so start an AMBIGUOUS leg once outside the fleet. A boundary that also names a column the target lacks (a replayed RENAME COLUMN) cannot be acknowledged: its recovery is the pre-ALTER replay wedge's.

MySQL-family binlog sources: decoding rows behind the head (DEFERRED-SCHEMA-CHANGE) #

v0.158.0+. A binlog reader that is behind the head reads events recorded under an older shape of a table. That covers every backup incremental window, every backup stream start, a warm-resumed or lagging sync start, and the CDC phase after a cold copy. Each row event is now decoded by the shape it was recorded under, or refused before any row of the table is decoded (through v0.157.2 it was decoded by the table's current definition — Bug 301, see the v0.158.0 notice). What that means depends on the source's binlog_row_metadata:

• FULL (recommended). Every event carries its column names and sluice decodes by them: add, drop, reorder, rename, an ENUM label reorder and two changes close together decode exactly. Set it with SET PERSIST binlog_row_metadata = 'FULL' on MySQL. MariaDB has no SET PERSIST: use SET GLOBAL binlog_row_metadata = 'FULL' and put binlog_row_metadata = FULL under [mariadbd] in its option file so a restart keeps it. Binlog written before the setting cannot be decoded by name, so take a new backup full or re-snapshot the sync (--restart-from-scratch) after setting it. FULL still refuses (SLUICE-E-CDC-SCHEMA-REPLAY-MISMATCH) for a column the binlog cannot describe on its own — a dropped signed TINYINT, a spatial column, a binary column on MariaDB — and for a schema change between the stream and the head on a table with a GENERATED column or a MariaDB UUID/INET4/INET6 column. A row whose recorded shape includes a column dropped or retyped later never becomes a schema boundary, so sluice holds it to the table's previous shape: it refuses with DEFERRED-SCHEMA-CHANGE if a shared column's type or collation changed (or the stream has no typed shape of the table to compare with), and with COLUMN-ORDER-CHANGED if two shared columns reversed order. DEFERRED-SCHEMA-CHANGE is codeless, exits 1, is not restarted under sync run, and its remedy is a re-copy. The same type change on its own still forwards. Since v0.159.0 a character column's collation is compared too: the binlog records it as an ID, which sluice names from the source's own collation table (MariaDB's FULL_COLLATION_NAME, otherwise information_schema.COLLATIONS; never a static table, because MySQL and MariaDB give the same high IDs to different collations). An ID the source's table cannot name refuses too. Through v0.158.1 the collation was named by character set only and then cleared, so a key's collation change folded behind a later retype could merge a row on the target before the stream refused (DEFERRED-KEY-COLLATION).
• MINIMAL (MySQL's default) or NO_LOG (MariaDB's default). sluice proves the catalog shape holds at the stream's position by reading the schema changes logged between the two with SHOW BINLOG EVENTS, and refuses a table one of them reshapes. Behind the head, these now refuse where they used to decode: any schema change of a streamed table other than an index, a table option, a TRUNCATE or an in-place redefinition. That includes an ENUM/SET label append via MODIFY, the RENAME TABLE cutover of gh-ost, pt-online-schema-change and LHM (even for an index-only migration), a no-op CREATE TABLE IF NOT EXISTS of a streamed table, and CONVERT TO CHARACTER SET on a table with ENUM/SET columns. An in-place MODIFY of a YEAR column refuses under MINIMAL, and on MariaDB's NO_LOG any in-place redefinition refuses (a VARCHAR widen included), because that format records no charset or signedness. The remedy for each is FULL. The refusal names the statement for its source (the MySQL SET PERSIST, or MariaDB's SET GLOBAL plus the [mariadbd] option-file line) on sync start, and since v0.158.1 on backup incremental and backup stream too; on v0.158.0 a refused backup said only to set binlog_row_metadata=FULL, without the MariaDB option-file line that keeps it across a restart (Bug 302). Since v0.160.0 the look-ahead skips a leading run of plain session SET assignments (no quotes, parentheses or comments before its ;) and classifies the statement after it, so a binlog text such as set foreign_key_checks=0; CREATE TABLE IF NOT EXISTS ... no longer reads as reaching every table; through v0.159.3 one such statement anywhere on the server made every stream behind the head refuse SLUICE-E-CDC-SCHEMA-REPLAY-MISMATCH (v0.160.0 notice).

Recorded collations (v0.159.2+, MINIMAL or FULL). Every row event's TABLE_MAP records the collation each character column was written under, under MySQL's default MINIMAL as well as FULL. The reader now decodes and reports each row under that recorded collation and character set, so a stream that reads a collation change after the fact (a backup incremental, a warm-resumed sync start) emits the schema boundary at the change with the shape the rows were written under: a sync forwards it ahead of them (or refuses it under --schema-changes=refuse), and a backup records it for chain restore to guard them under (v0.159.2 notice). MariaDB's default NO_LOG records no collation, so nothing is stamped there. That rests on a collation change being a logged DDL, and two refusals check it:

• DEFERRED-SCHEMA-CHANGE marked COLLATION-CHANGE-UNANNOUNCED. A row whose recorded collation differs from the shape this stream last decoded the table with, when no DDL that can reach that table was logged in between, for example an ALTER run with sql_log_bin=0, which changes the catalog and the row images and writes nothing a boundary could follow. It fires under MINIMAL or FULL, before any row of it is decoded, and is scoped per table: a logged ALTER of another table does not silence it. Like every DEFERRED-SCHEMA-CHANGE it is codeless, exits 1, repeats on a restart and is not restarted under sync run. The remedy is destructive: sync start --reset-target-data --yes for a sync, a fresh backup full for a backup chain; run such DDL with binary logging on. A stream that starts from a seeded shape (a backup's parent manifest, a sync's starting schema) whose first row of a table differs from that shape records a schema boundary at the stream's start instead of refusing.
• COLLATION-NAMES-UNAVAILABLE. A row carrying, on any character column, a collation ID the source's information_schema.COLLATIONS could not be read to name or does not list. Every character column, not only the primary key, because the reader does not know a table's UNIQUE keys. It is a new uncoded refusal, and it is retryable: a restart retries the read, and sync run restarts the leg.

Grants. The look-ahead's SHOW BINLOG EVENTS needs REPLICATION SLAVE on MySQL, which a CDC account already holds, and BINLOG MONITOR on MariaDB 10.5+, which REPLICATION CLIENT includes there. An account without it is refused with SLUICE-E-CDC-REPLICATION-PERMISSION, naming GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO <account>. Whether managed MySQL providers (RDS, Aurora, Cloud SQL, Azure) permit SHOW BINLOG EVENTS to an account that can stream is not verified: it is expected, but no measurement is recorded. If one does not, the reader stops rather than decode an unproven shape.

SLUICE-E-CDC-BINLOG-LOOKAHEAD-SHORT. The look-ahead could not read the binlog up to the position the source reported with its catalog read, for about ten seconds. It never treats binlog it did not read as checked. Retry; if it recurs, check the source's sync_binlog and binlog_group_commit_sync_delay. Since v0.159.3 a page that tore at the active binlog's tail (MySQL error 1220, binlog truncated in the middle of event, measured on about one read in a hundred under eight concurrent writers) is read as ending where the server stopped rather than stopping the stream; when the look-ahead still cannot get past such a tear, this refusal carries the server's 1220 and no longer suggests sync_binlog. A tear in a file the server has already rotated away from still fails as before (v0.159.3 notice). Cost: the look-ahead reads the binlog between the stream and the head at most once per window, and nothing for a stream at the head.

Not covered: PlanetScale and Vitess (VStream) sources are unverified for Bug 301. Their lanes were not changed, on the premise that each row is decoded against the field list Vitess emits for it, and that premise is not measured. A VStream row event carries no collation, so the key-collation checks do not arm there either.

MySQL-family binlog sources: a column name that now holds another column (COLUMN-IDENTITY-CHANGED) #

v0.159.0+, every schema-changes mode, any binlog_row_metadata setting, at the head or behind it. Some ALTER sequences end with the same column names and order they started with, and no comparison of the table's shape can see them, because a MySQL column has no stable id — not even under FULL, whose per-event names are the same before and after:

• DROP COLUMN c, ADD COLUMN c of the same type, in one ALTER or two;
• RENAME COLUMN c TO tmp, ADD COLUMN c;
• DROP COLUMN b, RENAME COLUMN c TO b, in one ALTER or two;
• a rename swap (RENAME COLUMN b TO c, RENAME COLUMN c TO b, or the CHANGE spelling) followed, before the table's next row, by a MODIFY … AFTER that restores the old order;
• a swap spelled as three renames through a temporary name (RENAME COLUMN b TO tmp; RENAME COLUMN c TO b; RENAME COLUMN tmp TO c), which refuses at its second statement, where it cannot be told from DROP b; RENAME c TO b.

Through v0.158.1 each produced no schema boundary, and the target kept every existing row's old values under the reused name at exit 0 (notice above). sluice now reads the ALTER TABLE statements in the binlog, which reach the reader in binlog order whatever the metadata setting or lag, and keeps a per-table ledger of what each did to column identity. When a name now holds another column, the stream refuses with COLUMN-IDENTITY-CHANGED at the ALTER itself, so a position persisted past it followed by a restart cannot skip it, and again at the table's next row. A plain swap or rotation in one statement is still left to COLUMN-ORDER-CHANGED, whose remedy is to apply the same renames on the target. A no-op CREATE TABLE IF NOT EXISTS or a DROP TEMPORARY TABLE does not reset the ledger.

The refusal reaches every lane that reads the binlog: sync start (live and warm), backup incremental, backup stream and the broker. It is codeless, exits 1, and repeats on every restart; a sync run leg that hits it is marked failed rather than restarted (fleet). There is no acknowledgement flag. The remedy is a re-copy: sluice sync start --reset-target-data --yes with the stream's other flags unchanged, or a fresh backup full for a chain.

MariaDB. IF EXISTS / IF NOT EXISTS on a column clause is read as if the clause took effect, so a no-op DROP COLUMN IF EXISTS c, ADD COLUMN c refuses too. A statement sluice cannot parse (for example one adding a MariaDB UUID column) refuses, marked COLUMN-IDENTITY-UNREAD, when it names an in-scope table and either spells DROP, CHANGE or RENAME or follows a statement that vacated a name of that table. Otherwise it logs a WARN with that marker and the stream continues, so a routine ADD COLUMN u UUID keeps flowing. COLUMN-IDENTITY-UNREAD is handled exactly like COLUMN-IDENTITY-CHANGED.

Not covered: PlanetScale and Vitess (VStream) sources, whose reader does not read the DDL text (unmeasured), and Postgres sources, where a column replaced under the same name is caught by attnum only within one run (F22). Under lower_case_table_names 1 or 2, an ALTER that spells an in-scope table in another case is judged out of scope at the DDL, so the refusal that holds across a restart does not fire for it; the row path still judges the table (not measured). Table identity — a RENAME TABLE swap, or DROP + CREATE of one name — is not covered, nor is a pure permutation followed by a persisted position, a restart and a MODIFY … AFTER.

A key column's collation: KEY-COLLATION-CHANGED, KEY-COLLATION-MERGE #

v0.159.0+. A collation decides which key values are equal. When a primary-key or unique column's collation on the target equates two values the source keeps apart ('A' and 'a' under _ci; 'a ' and 'a' under PAD SPACE), an upsert of the second row lands on the first: on a PRIMARY KEY the first row vanishes, on a UNIQUE column it is overwritten. Through v0.158.1 that happened at exit 0 whenever a stream did not forward a key's collation change (notice above). It is now handled in four layers:

• At the schema boundary: KEY-COLLATION-CHANGED. A key column's collation or character-set change met as a table's first schema boundary after a start, or on a --schema-changes=refuse stream, is judged against the source's own earlier shape of the table (the cold-start read, or the stream's retained schema history). Under forward it is forwarded to the target column, as the same change seen live always was. Under refuse it stops the stream with SCHEMA-CHANGE-REFUSED; with no earlier shape on record, a key whose collation differs from the target's stops the stream with RESUME-SCHEMA-DIVERGENCE. Each refusal carries KEY-COLLATION-CHANGED and names the column and both collations; apply the same change on the target and restart. Under forward, a key-collation change together with any other difference in the same boundary refuses. A stream between two engines of the same name whose target key was deliberately created with a different collation now refuses its first boundary for that table when no earlier shape is on record.
• In the applier: KEY-COLLATION-MERGE. The backstop for whatever no boundary shows. Where the source key's current collation distinguishes values the target's collation equates, every upsert carries a check inside the statement, which adds no round trip. An upsert whose key matched an existing target row that is equal under the target's collation but different under the source's refuses with KEY-COLLATION-MERGE before anything is written. A table whose source and target key collations agree carries no check, and a _ci source re-delivering a case-only change still converges. It covers MySQL, MariaDB, PlanetScale/Vitess and Postgres targets on every change-apply path (serial, batched and lanes), for live sync start and chain restore, which deliver the source's schema versions it arms from, and since v0.160.1 for the broker (sync from-backup), which seeds it from each incremental's recorded schema. On v0.159.0 through v0.160.0 the broker applied every incremental with this check unarmed (v0.160.1 notice). A trigger-CDC source records no schema versions, so a pgtrigger live sync or chain restore into a MySQL-family target is still not checked (not covered). The remedy is to give the target key column the collation the message names and restart; where the message says the key that identifies the row is itself compared differently, or the table has no primary key, it leads with a re-copy, because a re-delivered case-only change refuses on every start there. Since v0.159.1 the message names, per armed column, the collation the key needs: a binary collation such as utf8mb4_bin for a Postgres-source key on a MySQL-family target, and the NO PAD utf8mb4_uca1400_nopad_* form for a MySQL 8 key on MariaDB (not the source's 0900 name, which MariaDB 10.11 lacks). A key armed to compare bytes (a Postgres source collation on a MySQL-family target) gets no re-copy offer: the message says a re-copy would not converge, because it recreates the key under the target's default collation, which equates the values.
• In the copy phase (v0.159.1+): KEY-COLLATION-MERGE again. The copy phase's idempotent writer, the copy that tolerates a row already on the target, carries the same in-statement check, armed from the copied table's source collation, on MySQL-family and Postgres targets. It serves a resumed or chunk-resumed migrate or sync cold start, --force-cold-start, schema add-table, the VStream COPY (serial and fanned out) and restore of a rotated chain. A merge refuses with KEY-COLLATION-MERGE and the statement is rolled back; a re-sent row with the same source key, such as a resumed chunk, still converges. Unlike the applier, the copy also arms a Postgres default-collation or nondeterministic key inside the primary key. A plain fresh copy is not guarded this way: its first pass uses the plain bulk path, where the same pair fails as a loud duplicate-key error. A copy resumed over a live source whose key value changed case or accent between attempts can also refuse; the refusal names both readings (if the source equates the two values, re-copy the table from scratch; if it keeps them apart, the target key needs the collation the message names). On MySQL's plain bulk load, a retry after a transient (the reparent and storage-grow ride-out) on a table whose key is compared differently on the two sides is handled per core. The batched core re-sends a retried batch that meets a duplicate key as the guarded upsert, so its own lost-ack rows converge and only a real merge refuses. LOAD DATA has no upsert form, so a replayed segment that skipped rows (rows inserted short of the segment, or a duplicate-key warning) refuses with KEY-COLLATION-REPLAY-AMBIGUOUS, including a genuine committed-but-unacknowledged transient that used to ride through, because LOAD DATA cannot tell its own re-sent row from a second source row. That refusal is MySQL-family only (LOAD DATA runs on a vanilla MySQL or MariaDB target; PlanetScale/Vitess and any target without LOAD DATA use the batched path). Nothing is wrong with the data yet: run the copy again, and a genuine collision then surfaces on the first attempt as a plain duplicate key; or give the target key the collation the message names. A replay whose only warnings are something else, such as a clamp under --mysql-sql-mode='', skipped nothing and passes.
• In chain restore. backup incremental records a collation-only change to a key column as a column-collation delta, and chain restore and the broker apply it to the target before the window's rows. An older binary reads that delta as no change, so since v0.159.1 such a segment is stamped FormatVersion 13 and every older binary refuses it. Chains v0.159.0 captured carry no stamp: restore them with v0.159.0 or later. Since v0.159.2 chain restore releases each schema version a window recorded just before the first change recorded at or after it, in the source engine's position order, and, ahead of a window that changes a table's key collation, the shape the previous link recorded for that table, so rows are guarded under the collation they were written under. A window that changed a key's collation and changed it back, or loosened it, now refuses KEY-COLLATION-MERGE instead of merging (v0.159.2 notice); restarting refuses again. On v0.159.2 a loosened window armed nothing when no row of the table followed the loosening inside it, and merged at exit 0 (Bug 306, fixed in v0.159.3). A chain records only what its capture saw: a key changed and changed back inside a window that backup incremental on v0.159.1 or earlier read after the revert left no trace of the intermediate collation, so no release can refuse it (Bug 307); check such a restore against the source and take a fresh full backup. Postgres windows (v0.160.0+): a Postgres change stream anchors every schema version at one position, so a window keeps one version per table; a later version whose key collation is not established weakens the kept one, so the whole window compares that key byte for byte, and a window whose two shapes of a table disagree on a key column's collation is refused at capture with KEY-COLLATION-SAME-ANCHOR rather than recorded. Where the versions cannot be ordered, see KEY-COLLATION-HISTORY-UNORDERED below.
• On a functional unique-key part (v0.161.0+): KEY-COLLATION-FUNCTIONAL-KEY-PART. On a MySQL-family target a functional key part (UNIQUE ((lower(k)), x)) compares under the collation of the index's hidden column, which the expression text does not record. Through v0.160.4 the guard skipped every functional part, so a Postgres UNIQUE (lower(email)), created on MySQL under utf8mb4_0900_ai_ci where lower('e') and lower('é') are one key, let the second row replace the first through ON DUPLICATE KEY UPDATE at exit 0, at CDC apply and on every idempotent copy path (schema add-table, resumed and chunk-resumed copies, the VStream COPY, restore; measured on MySQL 8.4). Now a part passing one column through LOWER, UPPER, TRIM, LTRIM, RTRIM, a character CAST or COLLATE is compared per row on the target as the index compares it, under the collation read off the hidden column, and on the source as the bytes of the columns it reads; any other collated part is taken to match on the target, so it refuses only a conflict between rows whose columns differ. Where the hidden column cannot be read (vtgate on Vitess and PlanetScale), the part is assumed to match and the guard refuses when the target matched two rows whose columns differ. A merge refuses KEY-COLLATION-MERGE, naming the key to recreate comparing byte for byte (COLLATE utf8mb4_0900_bin, or utf8mb4_nopad_bin on MariaDB). FUNCTIONAL-CAST-HIDDEN-COLLATION: a charset-less CAST or a string literal takes the creating session's collation_connection, and an ALTER … MODIFY of the column leaves the hidden column on its old collation, so a MySQL → MySQL key rebuilt from its text alone could merge rows the source kept apart ('a'/'A', 'ss'/'ß', 'e'/'é'; released versions are exposed too). From a vanilla MySQL source sluice now reads each part's hidden-column collation and emits it on the keys it creates (((expr) COLLATE <it>)); a backup that records it is stamped FormatVersion 15. The cost: where the guard arms, a conflict between byte-different values that the source would equate now refuses instead of converging, mostly on Vitess and PlanetScale and on MySQL → MySQL CDC apply, whose change-stream shape carries no secondary indexes, so every collated functional key arms there. A Postgres target is not exposed: its upsert never arbitrates on an expression index, so a conflict through one is a loud 23505.

KEY-COLLATION-GUARD-UNSUPPORTED. If the target cannot express the source's collation for the comparison (the collation or character set does not exist there), the stream refuses at its first write to the table rather than apply unguarded, naming the source's collation and the comparison collation the target lacks. Since v0.159.1 the copy phase's idempotent writer refuses the same way, before any row of the table is written. Create the collation on the target, or align the key column's collation on both sides. A MySQL-family key on a Postgres column with a nondeterministic collation refuses this way, because Postgres has no collation to compare it as. So does a MySQL 8 utf8mb4_0900_* key on a MariaDB target older than 10.10 (details). A second cause, since v0.161.0: a functional key part whose columns sluice cannot resolve. No collation change fixes it, so the table is refused before any row of it is written, and the message names each part with its own remedy: a part naming a column the table does not have (for example from a non-ASCII column name): recreate the key over ASCII-named columns; a string literal sluice cannot scan: write it plainly, or key a stored generated column instead; generated columns nested more than eight deep: key a shallower expression. An armed key whose columns are still not all in the insert is refused the same way. Or leave the table out with --exclude-table.

KEY-COLLATION-HISTORY-UNORDERED (v0.159.2+). sync from-backup places no schema version between a window's changes, so it cannot tell which rows were written under which collation of a key. It refuses, before applying any of it, every window that changes a key column's collation: a schema delta that does, two consecutive recorded versions of a table that disagree, or a version that disagrees with the segment's recorded schema. That includes a forward change it used to replay correctly, because it cannot tell a forward change from a reverted or loosened one. Chain restore from a trigger-CDC source (pgtrigger, sqlite-trigger, d1-trigger), which records no schema versions and has no position order, refuses the same way for any window whose schema delta changes a key column's collation, including a forward, tightening change it used to restore correctly. Since v0.160.0 it also refuses a window that records a Postgres key collation not established for its rows, because the broker's applier is never armed from a window's versions and so cannot compare that key byte for byte; take a new full backup to replay past it. This refusal is what makes the broker's guard sound (v0.160.1+). The broker arms the applier's KEY-COLLATION-MERGE check from each incremental's recorded schema, handed to the applier in memory before the incremental replays and never persisted, rather than from the window's versions; that one shape is correct for every row of the window because any window whose versions disagree with it on a key collation has already been refused here. Through v0.160.0 the broker armed nothing at all (v0.160.1 notice). The marker arrives inside a KEY-COLLATION-MERGE refusal. Restarting refuses again, and changing the target key's collation does not help. Remedy: take a new backup full after the key change, then sluice sync from-backup run --reset-target-data --yes against the new chain (destructive), or restore that full on its own. A VStream (Vitess/PlanetScale) window replays as before: a VStream schema version records no collation and is not read as a change. See also Sync from a backup chain.

The chain-restore remedy (v0.159.3+, Bug 308). restore neither resumes nor accepts --restart-from-scratch, so a chain restore's KEY-COLLATION-MERGE replaces the applier's remedy with one it can run, by command and key:

• Inside a window that itself changes a key column's collation: take a fresh full backup after the key change and restore it into an empty target. For the sync from-backup run --reset-target-data cold start, which runs the same chain restore, the remedy is sluice sync from-backup run --reset-target-data --yes against the new chain.
• Outside such a window, when sluice creates the key under a target default collation that treats the two values as equal (for example, a byte-compared Postgres key restored onto a MySQL-family target): the table cannot be restored onto that target as it is. Leave it out with sluice restore --exclude-table, or use a target that keeps the source's comparison.
• Outside such a window, for a key sluice would create correctly: the table most likely existed before the restore, because the restore's CREATE TABLE is IF NOT EXISTS. Drop the restored tables and restore again, or leave the table out.
• Where the engine cannot say what the key needs (the Postgres applier): both of the previous two remedies, each with the condition under which it applies.

The applier's own remedy, which sync start and sync from-backup run show, names the re-copy for each: sluice sync start --restart-from-scratch, or sluice sync from-backup run --reset-target-data --yes for a backup replay (through v0.159.2 it named --restart-from-scratch alone, which sync from-backup run does not accept).

KEY-COLLATION-VERSION-NAMESPACE (v0.159.3+). A MySQL or MariaDB backup records its tables with no database name while its change rows name the database; the shape a chain-restore window starts from takes the name its rows carry. A row naming no database at all — the ADD COLUMN fill a backup window records, one update per row by primary key, which names what the manifest names — neither sets nor contradicts it. A row of that table naming a different database than the shape was filed under, or arriving after the shape has already gone out naming none, refuses KEY-COLLATION-VERSION-NAMESPACE rather than let the lookup miss. It arrives inside a KEY-COLLATION-MERGE refusal (no new error code), refuses before that change is applied, and names its remedy: take a fresh full backup and restore from it. It is the check on the premise that a single-database backup's rows name one database: no real chain is known to reach it. It exists because of Bug 306.

KEY-COLLATION-SAME-ANCHOR (v0.160.0+). Where: a Postgres backup stream or backup incremental capture. A Postgres change stream anchors every schema version at LSN 0/0, and a backup keeps one schema version per table and position, so a window that wrote a row of a table and then saw that table's key collation change records two shapes of the table at one position, and keeping either would leave a restore unable to tell which rows were written under which collation (v0.160.0 notice). When two shapes of a table recorded at one position disagree on a key column's collation, the capture refuses to record the window: KEY-COLLATION-MERGE: KEY-COLLATION-SAME-ANCHOR: <table>: …, with no error code, exit 1. Remedy: take a new full backup after the key change (sluice backup full) and continue the chain from it; restarting the capture from the same position re-reads the catalog and is expected to refuse again. The cost: a forward-only key collation change in a window that already holds a row of the table refuses too, where it used to restore correctly — unless the first shape the window recorded was already not established, which compares the key byte for byte and needs no refusal. Under REPLICA IDENTITY FULL the change stream reports every column as part of the key, so a column added inside the window is not treated as a new key column unless a unique index names it; a real all-column primary key extended to a column added inside the window reads the same way. A cancelled backup stream whose last flush hits this refusal exits non-zero with it, not with an abandoned-window WARN (details).

All eight markers are codeless and exit 1. KEY-COLLATION-CHANGED rides inside RESUME-SCHEMA-DIVERGENCE or SCHEMA-CHANGE-REFUSED, KEY-COLLATION-HISTORY-UNORDERED, KEY-COLLATION-VERSION-NAMESPACE, KEY-COLLATION-SAME-ANCHOR and KEY-COLLATION-DELTA-FAILED (v0.160.2+, details) ride inside KEY-COLLATION-MERGE, and KEY-COLLATION-MERGE (with KEY-COLLATION-GUARD-UNSUPPORTED) is a refusal of its own; under sync run a leg that stops on any of these three is marked failed rather than restarted (fleet). KEY-COLLATION-REPLAY-AMBIGUOUS (v0.159.1+) is not on that list: sync run restarts the leg, and running the copy again is its remedy. KEY-COLLATION-PRE0159-2-UNVERIFIABLE (v0.160.2+) is a WARN, not a refusal: chain restore, sync from-backup and backup verify log it for every MySQL-family incremental captured before v0.159.2 that records a character column in a primary or unique key (details). Postgres sources: pgoutput carries no collation, so the CDC reader now reads each column's collation from pg_attribute.attcollation at every Relation message — one catalog query per table per session and per schema change, with no new privilege. Both Postgres readers record the database default collation as deterministic. Not-established key collations (v0.160.0+). The collation read at a Relation message is the one in force now, not necessarily the one the rows were written under, so the reader also reads the column's pg_attribute row, which altering the column rewrites. When a key column's catalog row is newer than the transaction being decoded, or was written by that same transaction (whose DDL may have run after its rows), and its collation is nondeterministic (an ICU case- or accent-insensitive collation), the reader records the collation as not established for those rows, and both appliers compare that key byte for byte: an incoming row whose key matches a byte-different existing key refuses KEY-COLLATION-MERGE instead of merging onto it. A byte comparison is stricter than the collation's, so the cost is loud: a conflict the collation would have equated also refuses, and the same happens after any other change to that column's catalog row made after, or in the same transaction as, the replayed rows — a rename, SET NOT NULL, a column-level GRANT, or a CREATE TABLE with its seed rows in one transaction. The comparison has a lower bound, because a frozen catalog row keeps its raw xmin, so a column's catalog row more than 2³¹ xids old does not read as newer than every row. A backup segment that records such a key is stamped FormatVersion 14.

Not covered:

• VStream sources (PlanetScale/Vitess). The stream carries no collation, so none of these checks arm. After changing a key column's collation there, apply the same change on the target before any row distinct only under the new collation is written, or re-copy the table.
• At CDC apply, a Postgres-source PRIMARY KEY (or a UNIQUE key on a table without one) on the database default collation or a nondeterministic collation, landing on a MySQL-family target. That key is created under the target's default collation, usually case-insensitive, and a second source row distinct only in case merges. The applier deliberately leaves it unarmed, because arming it would refuse a re-delivered case-only change that converges today. A UNIQUE key beside a primary key on the same pairing is checked (a nondeterministic one since v0.159.1), and the copy phase arms the primary key too.
• A SQLite or D1 source key, including the sqlite-trigger and d1-trigger streams (HIGH, silent when reached; open, KEY-COLLATION-SQLITE-SOURCE-UNSTAMPED). Its reader records no collation, so plain key columns are not checked. Since v0.161.0 a functional unique key part on a MySQL-family target arms for these sources too. Measured with a --type-override that lands a BINARY text key as varchar under a MySQL _ci collation, and with a hand-made _ci target table.
• A trigger-CDC source (KEY-COLLATION-TRIGGER-CDC-NO-HISTORY; fixed for pgtrigger in v0.161.0). Through v0.160.4 the trigger-CDC readers emitted no schema versions, so the applier had nothing to arm from and applied every change unchecked, in steady state: a pgtrigger UNIQUE key that MySQL creates under a _ci default could take a second source row distinct only in case onto the first at exit 0, at live sync start (cold start and warm resume) and in a chain restore (measured on Postgres 16 → MySQL 8). Since v0.161.0 the pgtrigger reader emits a schema version at each table's first change of a session (first-touch boundary; v0.161.0 notice). sqlite-trigger and d1-trigger record no collation and stay unarmed (previous item).
• A Postgres-source backup chain written before v0.159.0, restored into a MySQL-family target, with a key on the database default collation. Such a manifest cannot tell that key from a source that records no collation, so it stays unchecked. A key with a named collation in such a chain is checked since v0.159.1, compared byte for byte in every key.
• Two residuals of the Postgres not-established check (v0.160.0+). A DDL whose transaction was assigned its xid before the replayed one, but committed after it, reads as older, so it is not caught. A table or key column renamed or dropped after the replayed rows misses the catalog lookup, which is by name, and stays unguarded, as before. Through v0.159.3 any Postgres key made stricter and then looser again while the stream lagged, or inside one transaction, could merge (v0.160.0 notice).
• Functional key parts (v0.161.0+). A Vitess or PlanetScale source's hidden collation cannot be read through vtgate, so such a key arms as unknown (loud on a respelled conflict only). A hidden collation changed and changed back inside one backup window is not seen (FUNCTIONAL-HIDDEN-COLLATION-WINDOW-REVERT). A target whose column character set differs from the source's (a --type-override that changes it, say) can make the pinned COLLATE fail with ERROR 1253 at the index build, after the copy, loudly (FUNCTIONAL-HIDDEN-COLLATION-TARGET-CHARSET). Open, MEDIUM by code-reading, silent: a generated column whose expression has a charset-less CAST or a literal comparison takes the creating session's collation, which nothing reads, so a target that recreates it computes different values; it reaches a functional key over that column and a plain UNIQUE on it (GENERATED-EXPR-SESSION-COLLATION). And a plain UNIQUE key on a generated column is armed only on the generated column's own declared collation, so a base column whose collation differs on the target (a --type-override, a target MODIFY) changes its value unchecked (PLAIN-UNIQUE-GENERATED-COLUMN-BASE-COLLATION, open, MEDIUM by code-reading, silent).
• MySQL 8 → MariaDB is compared under MariaDB's NO PAD uca1400 collations, so MariaDB's UCA 14.0.0 weights stand in for MySQL's UCA 9.0.0 ones.
• A non-key column's collation-only change is not judged at a boundary and not applied by chain restore (no merge is possible there), and a chain whose incremental was captured before v0.159.0 carries no collation delta.

Postgres sources: the pre-ALTER replay wedge (PRE-ALTER-REPLAY-WEDGE) #

Loud, no data loss (GC-44 F24); the marker and the recovery text are new in v0.156.10, the wedge is not. On the four kinds of stream above, and under Shape A's coordinated router, the Postgres reader still refuses an ALTER COLUMN TYPE, DROP COLUMN or RENAME COLUMN on a table it has already seen in the session. A source transaction that writes a table, changes a column and writes the table again is therefore refused on its first delivery and on every restart, whatever the target holds, because each replay caches the pre-ALTER relation first. Nothing the transaction wrote after the ALTER reaches the target; rows it wrote before may already be there, and the recovery re-applies them. When the refused relation's transaction had already written the table, the reader's refusal carries PRE-ALTER-REPLAY-WEDGE and names the recovery for the case. After applying the change to the target:

• A type widening on a stream over a single database and schema, without --inject-shard-column: start once with --schema-changes=forward, then return to refuse. This is the only change a forward start passes (GC-44 F26: a DROP COLUMN or RENAME COLUMN wedge cannot pass it).
• Any other change, or a multi-database or multi-schema stream: drop the stream's replication slot with sluice slot drop <slot> --source-driver=postgres --source <source DSN> --yes (the literal name sluice slot list prints), then start once with --restart-from-scratch, which re-copies every table in scope from a fresh snapshot past that transaction.
• --inject-shard-column: the target tables hold the sibling shards' rows too. First delete this shard's rows from each in-scope target table (DELETE FROM <schema>.<table> WHERE <shard column> = '<this shard's value>'), then drop the slot, then start once with --restart-from-scratch. Never use --reset-target-data here: it drops every sibling shard's rows.

Each recovery is pinned end to end, with rows read back exact and the stream resuming in its own mode. An ALTER run in its own transaction followed by writes — the drained model's own shape — recovers with a plain restart. After the drained model, a DROP COLUMN or RENAME COLUMN wedge's restart may instead stop at the check above as SCHEMA-CHANGE-REFUSED, naming the column the target now lacks; adding the column back does not pass it either, so use the re-copy. Under sync run this refusal is not in the not-restarted list: a wedged leg is restarted and refuses again each time (GC-44 F27). Alert on a leg that keeps restarting with this marker, and apply the recovery outside the fleet.

Known residuals (GC-44) #

• F23 (Postgres source, silent): on a stream under --schema-changes=forward, a column narrowed on the source while the stream was stopped is kept with a WARN (the target column is WIDER than the source's). The target is not narrowed, and its existing rows keep values the source's ALTER rounded, because Postgres schema history cannot prove the boundary comes after its earlier shape, so the narrowing cannot be told from a crash replay. If you see that WARN, narrow the target or re-copy the table. On a stream that forwards no DDL the same case refuses as AMBIGUOUS-SCHEMA-BOUNDARY.
• F22 (silent, narrow; Postgres and VStream sources only since v0.159.0): a DROP plus ADD of the same column name and type, both made while the stream was stopped, is not seen; the target keeps the old column's values. Within one run it is caught. On a MySQL/MariaDB binlog source the same change now refuses COLUMN-IDENTITY-CHANGED when the resume replays its ALTER from the binlog, which a warm resume and a backup incremental always do (a binlog purged past it means a re-copy instead), except where lower_case_table_names lets the ALTER spell the table in another case.
• F17 (fixed in v0.159.0 and v0.159.1 for key columns, with named residuals): a key column's collation or character-set change met as the first schema boundary of a run, on a refuse stream, in a chain restore, or on any Postgres source, merged rows the source keeps apart. It is now judged at the boundary and checked on every upsert, the copy phase's idempotent writer included since v0.159.1 (KEY-COLLATION-*). Still uncovered: VStream sources, a Postgres default-collation or nondeterministic primary key on a MySQL-family target at CDC apply (deliberate), the two residuals of the Postgres not-established check (a DDL whose xid predates but whose commit follows the replayed transaction, and a table or key column renamed or dropped after the rows), SQLite and D1 source keys (no collation recorded), and MySQL 8 → MariaDB compared under UCA 14.0.0 weights. A backup window that changes a key's collation and changes it back, or loosens it, restored or replayed merged through v0.159.1; v0.159.2 fixed both for MySQL and MariaDB binlog sources (KEY-COLLATION-REVERTED-WINDOW-RESTORE, KEY-COLLATION-LOOSENED-WINDOW) for the chains it writes, not for a backup incremental chain written by v0.159.1 or earlier, which recorded no evidence of the window (Bug 307), and its loosened-window restore armed only when a row of the table followed the loosening inside the window (Bug 306, fixed in v0.159.3). The Postgres twins (KEY-COLLATION-PG-SAME-ANCHOR, KEY-COLLATION-PG-LOOSENED-REPLAY, both HIGH) were fixed in v0.160.0 (v0.160.0 notice). A non-key column's collation is still not judged.
• F24, F26 and F27 (loud): the pre-ALTER replay wedge stays open (F24); a forward start cannot pass a DROP COLUMN or RENAME COLUMN wedge, so for those the re-copy is the only recovery (F26); and the fleet supervisor restarts a wedged leg rather than marking it failed (F27).

The other open GC-44 items — among them a geometry SRID or an interval(p) precision changed while the stream was stopped (F16, F20), and type pairs that refuse on every start (F25, F15) — are listed in the v0.156.10 release notes.

The refusal message #

When a change refuses, the error is deliberately greppable and names the specific offending object plus the operator action. It carries three parts: the classify error (which shape / how many changes), a structured drift diff that names the exact columns / indexes / constraints that differ, and a recovery hint. The hint spells out the drained model:

• Run sluice sync stop --wait to drain in-flight changes.
• Apply the schema change on the target — manually, or through a governed channel such as sluice deploy-ddl (PlanetScale deploy requests) or sluice schema add-table when the change is a whole new table.
• Resume by re-running sluice sync start with the same --stream-id — it warm-resumes from the persisted position.
• It also notes that --schema-changes=refuse keeps the drained model as the default for any subsequent source DDL. Since v0.156.10 that mode is target-checked: it applies no source DDL, and every schema boundary is compared with the target, stopping with SCHEMA-CHANGE-REFUSED where the target cannot hold what the source now sends.

Operator runbook: recovering a refused change #

When a change refuses — or when you run --schema-changes=refuse deliberately — the recovery is the drained-schema-migrate sequence. Stop the stream with --wait so the CLI blocks until the streamer confirms a graceful drain (the in-flight batch is committed and the CDC position is persisted past the last applied event), apply the DDL to whichever side needs it, then resume from the persisted position. (One refusal is the exception: UNFORWARDED-SCHEMA-CHANGE is recorded on the target, so this sequence alone just replays it — apply the change to the target and acknowledge it with --accept-unforwarded-schema-change instead.)

# 1. Drain and stop — --wait blocks until the drain is confirmed
sluice sync stop --wait \
    --stream-id app-prod \
    --target-driver postgres --target 'postgres://...target...'

# 2. Apply the schema change on source and/or target as appropriate
psql "$SOURCE_DSN" -c 'ALTER TABLE accounts RENAME COLUMN label TO name;'
psql "$TARGET_DSN" -c 'ALTER TABLE accounts RENAME COLUMN label TO name;'

# 3. Resume — the same --stream-id warm-resumes from the persisted CDC position
sluice sync start \
    --stream-id app-prod \
    --source-driver mysql    --source 'root:rootpw@tcp(localhost:3306)/app' \
    --target-driver postgres --target 'postgres://...target...'

There is no resume flag to pass: re-invoking sync start with the same --stream-id finds that stream's persisted CDC position (source LSN / GTID set / VStream cursor) and continues from it, so pre-stop events apply cleanly and the first event after resume sees the new shape on both sides. It does not re-run the snapshot, and it never bulk-copies into the populated target. The order "stop → ALTER source → ALTER target → start" is robust regardless of which side commits the DDL first, as long as both sides carry the new shape before resume. On a Postgres source the persisted position is the last committed transaction's end LSN — the first byte after its commit record — so the resumed stream begins at the next transaction rather than re-delivering the one it closed (v0.138.0; through v0.137.4 a Postgres warm resume replayed the last applied transaction with its pre-DDL relation shape, and a refusal re-fired on the restart this runbook prescribes). A schema change applied to the source only, while the stream was stopped, is checked at resume against the target since v0.156.10 — forwarded, kept with a WARN, or refused with RESUME-SCHEMA-DIVERGENCE or SCHEMA-CHANGE-REFUSED (through v0.156.9 it was not classified at all). Applying it on both sides before restarting remains the predictable path.

A table rename done this way resumes on its own (v0.163.0). Rename the table on both sides while the stream is stopped (ALTER TABLE t RENAME TO t2 on Postgres, RENAME TABLE t TO t2 on MySQL-family), then restart: the stream's record of the tables it copied keeps each table's engine-stable id (Postgres pg_class.oid, InnoDB TABLE_ID), recognises t2 as t renamed, and follows it — provided t2 is in the stream's scope: with a literal --include-table, the restart must name t2 (otherwise t2 is out of scope, nothing follows, and t leaves the stream's record as gone from the source). If the target was not renamed — it still holds t, or lacks t2 — the restart refuses INCLUDE-TABLE-SCOPE-DRIFT saying so; a target that holds an unrelated t2 beside the stream's t refuses the same way (drop or rename that t2 away, then rename t). A table dropped and re-created under the new name is a different table (a new id) and refuses as never copied. Where no id proves the rename — a PlanetScale/Vitess source, a table name InnoDB stores encoded, or a stream whose record has no ids — the refusal names --accept-table-rename <old>=<new>: pass it once on that restart, after renaming the target too, and the record follows the rename; the target t2 is then trusted as-is (details).

A table swap is not a rename the stream follows. Swapping two tables while the stream is stopped (RENAME TABLE a TO tmp, b TO a, tmp TO b, or three ALTER TABLE … RENAMEs) leaves every name present, and the restart refuses TABLE-IDENTITY-CHANGED naming which table each name now holds: the target copies are under the old names, so applying would mix the two. Re-copy the swapped tables (empty each target table and sluice schema add-table it), or the whole stream with --restart-from-scratch. On Postgres a table dropped and re-created under the same name refuses the same way; on MySQL-family it does not, because InnoDB gives a table a new id on routine rebuilds (OPTIMIZE TABLE, a copying ALTER, TRUNCATE) — there the record takes the new id.

Next steps #

• sync start reference — the --schema-changes row and the full sync flag set.
• Migrate MySQL to Postgres — the one-shot migration the drained model resumes onto.
• schema preview / diff — pre-flight the drift, then apply the target-side change yourself (or via deploy-ddl).