Add opt-in auto re-sync on schema incompatibility

[orware]

Problem

IsBinlogsExpirationError drops the saved position and lets the next loop iteration run a historical sync, so the connection recovers on its own. The schema-incompatibility path added in #89 returns an error instead.

So a deploy that changes the layout of a replicated table stalls the connection until a human triggers a historical re-sync. Until they do, every subsequent sync retries from the same saved position, hits the same undecodable binlog event, and fails again. And because a Read() error returns out of the whole Sync handler rather than skipping the affected table, one table in this state stalls every table in the connection.

In the incident that prompted this, replication was stalled for hours across six tables before anyone noticed, and the eventual fix was a manual full re-sync of the entire connection.

Why this is opt-in rather than just mirroring the binlog path

Unlike expired binlogs, the operator has a real choice here: the data is still readable from the saved position once the projection is rebuilt, and an automatic historical sync costs monthly active rows. #73 shows MAR is already a consideration in this connector, so silently re-syncing a large table isn't a call this PR should make on a user's behalf.

New auto_resync_on_schema_change configuration field, defaulting to false, which preserves current behaviour exactly — the error is surfaced with recovery guidance and the sync waits for an operator-triggered re-sync. The message now also mentions the flag, so anyone hitting this finds the option.

With it enabled, the cursor is reset and the stream recovers unattended.

It follows the existing convention for booleans here (use_replica, treat_tiny_int_as_boolean): a ["true","false"] dropdown parsed with strconv.ParseBool, so an absent key leaves it false with no special-casing. SDK v2 also has a ToggleField which would render more naturally — happy to switch if you'd prefer to start migrating.

Change

• auto_resync_on_schema_change form field, config parsing, and PlanetScaleSource field
• when enabled, clear Position and LastKnownPk, mark the cursor, and continue, exactly as the binlog-expiration branch does — the copy phase reads the live table, so it re-anchors past the DDL
• the cursor carries a distinct SCHEMA_INCOMPATIBILITY_ERROR code rather than reusing BINLOG_EXPIRATION_ERROR, so the two causes stay distinguishable downstream and an unexpected historical sync remains attributable

Tests

TestRead_ReturnsVStreamSchemaIncompatibilityErrors asserted the old contract, so it becomes two tests covering both sides of the flag:

• TestRead_SchemaIncompatibilityResetsCursor — opt-in enabled; mirrors TestRead_BinlogExpirationReturnsResetCursor. Verifies the position is cleared, LastKnownPk is nil, and the code and message are set. Verified to fail against the current Read().
• TestRead_SchemaIncompatibilityWithoutOptInReturnsError — default; the original contract, plus an assertion that the message points at the flag.

TestRead_ReturnsGenericNonTimeoutErrors and TestRead_BinlogExpirationReturnsResetCursor are unchanged and still pass, confirming no over-reach into other error paths. TestVStreamSchemaIncompatibilityReturnsFailedPrecondition in sync_test.go mocks Read directly, so it still exercises the handler mapping and is untouched.

Full go test ./... passes, cmd/... included.

Relationship to #96

Independent, and they compose. #96 determines what counts as a schema incompatibility — it currently misses three of the five inner causes vstreamer can raise. This PR decides what to do once one is detected. Either can merge first.

🤖 Generated with Claude Code

[orware]

Validated end-to-end against a live PlanetScale branch rather than mocks.

Setup reproduces the production failure this is aimed at: capture a cursor, write rows, apply a trailing ADD COLUMN, write more rows, then resume from the now-stale cursor with the new column in the projection. Schema-version tracking off, matching the configuration the original incident occurred under. Same database, same data, same DDL — the only variable is the flag.

	auto_resync_on_schema_change=false (default)	=true
error	column v97_false not found in table repro	none
rows delivered	0 — sync stalls, needs manual re-sync	7 — full table, unattended

The 7 rows are the entire table, since the reset drops the position and the copy phase re-reads it. That is the intended behaviour and also a fair illustration of why this is opt-in rather than default: the recovery is a full historical sync, with the monthly-active-row cost that implies.

Worth noting the default path is unchanged and still surfaces the error with recovery guidance, so this is purely additive for anyone who doesn't opt in.

For completeness, the same harness was used to reproduce all four schema-incompatibility shapes across direct ALTER and deploy requests, with and without schema tracking — 16 cells, and every deploy-request result was identical to its direct-ALTER equivalent. Details in the #96 thread.