docs: document source behavior on upstream schema changes and destructive operations

[claude]

Requested by Pranshu Maheshwari · Slack thread

Motivation

A customer asked what happens to a Materialize source when the upstream table undergoes schema changes or destructive operations. This documents that behavior on the primary Postgres, MySQL, and SQL Server ingestion pages.

Description

Added a single reusable include — a new parameterized Hugo shortcode doc/user/layouts/shortcodes/upstream-schema-change-behavior.html — describing add-column / drop-column / constraint changes / error-state operations, and wired it into the three _index.md primary pages (postgres, mysql, sql-server) under a new ## Upstream schema changes and destructive operations section placed after ## Considerations. The shortcode takes a connector param and is called as {{% upstream-schema-change-behavior connector="..." %}}; source-versioning links are built from the connector so each page links to its own guide. This keeps a single source of truth for the prose (modeled on the existing source-versioning-disambiguation.html "parameterize by variant" pattern) rather than three copies.

PUBLICATION and REPLICA IDENTITY operations, and EXCLUSION constraints, are gated with {{ if eq (.Get "connector") "postgres" }} to render only on the Postgres page, since MySQL (GTID binlog) and SQL Server (CDC capture instances) have no such concepts.

The "Changing a column's data type" error-state bullet now renders per-connector, since the behavior differs by upstream. Postgres errors on any type change except changing it to text. MySQL only errors when the new type maps to a different Materialize type. Changes within the same Materialize type (for example tinyint ↔ smallint, the text/tinytext/mediumtext/longtext family, or adjusting bit(n) precision) do not error, and appending values to an existing enum is safe while removing enum values errors. SQL Server errors on any ALTER COLUMN. This was clarified by the MySQL and SQL Server SME.

Resolved caveat:

1. Whether a truncation error case applies to SQL Server CDC. Confirmed by the SQL Server SME (Marty Kulma): SQL Server prevents TRUNCATE against a CDC-enabled upstream table, which fails with error 4711 ("Cannot truncate table ... because it is published for replication or enabled for Change Data Capture"). The truncate-error path is therefore not reachable on SQL Server, so the "Truncating a table" bullet is intentionally omitted from the SQL Server page. It stays on the Postgres and MySQL pages, which both allow the operation and have documented truncation restrictions.

Verification

Built the site locally with the pinned Hugo extended v0.152.2 (hugo from doc/user). Build succeeded with exit 0, 604 pages rendered, no template/shortcode errors. Grepped the generated public/ output per connector to confirm the gating:

• ingest-data/postgres/index.html: PUBLICATION, REPLICA IDENTITY, and EXCLUSION all present; rendered constraint line reads "foreign key and CHECK and EXCLUSION constraints"; DROP TABLE bullet includes the ALTER PUBLICATION ... DROP TABLE / DROP PUBLICATION clause.
• ingest-data/mysql/index.html and ingest-data/sql-server/index.html: PUBLICATION, REPLICA IDENTITY, and EXCLUSION all absent (0 occurrences); constraint line reads "foreign key and CHECK constraints".
• All three pages render the new section and link to their own source-versioning guide (/ingest-data/{connector}/source-versioning/#handle-upstream-column-{addition,drop}).

[martykulma]

SQL server prevents users from running truncate against the upstream table when CDC is enabled, so that path is not reachable. If a user attempt to truncate a CDC enabled table, the command fails with error 4711 - Cannot truncate table '%.*ls' because it is published for replication or enabled for Change Data Capture.

[claude]

Thanks — updated: dropped the TRUNCATE bullet from the SQL Server page since CDC-enabled tables can't be truncated (error 4711). It stays on the Postgres and MySQL pages, which do allow the operation. Pushed in ccabc87.

---

Generated by Claude Code

[maheshwarip]

Read through all the documentation carefully and validate that it makes sense. For instance, the page for MySQL now has two sections for schema changes. Think about how to incorporate this gracefully @claude . Bear in mind the legacy syntax and the new syntax.

[claude]

Claude finished @maheshwarip's task in 2m 42s —— View job

---

Reviewing documentation for duplication issues

• Read all changed files and existing content
• Identify duplicate sections
• Fix duplication gracefully
• Validate all three pages look correct

Finding: All three pages (Postgres, MySQL, SQL Server) already had a ### Schema changes section inside ## Considerations. That section covers the legacy CREATE SOURCE ... FOR ... (subsource-based) syntax — both its compatible-change bullets and its "Incompatible schema changes" note are about recreating subsources via ALTER SOURCE...ADD SUBSOURCE. The new PR added ## Upstream schema changes and destructive operations for current behavior, resulting in two schema-change sections on each page with no clear distinction.

Fix (pushed in cb0d018): Renamed ### Schema changes → ### Schema changes (legacy source syntax) in:

• doc/user/content/headless/mysql-considerations.md
• doc/user/content/headless/sql-server-considerations.md
• doc/user/data/postgres_source_details.yml (the postgres-considerations block)

Readers now see clearly that the Considerations block covers the old subsource-based syntax, while the new top-level section covers current CREATE TABLE FROM SOURCE behavior. No content was removed.
· Branch

[maheshwarip]

@claude please also expand the "Type changes" into its own subheading, much like "Add a column" and "Drop a column"

[claude]

Claude finished @maheshwarip's task in 56s —— View job

---

Tasks

• Read current shortcode structure
• Expand "Type changes" into its own ### Changing a column's data type subheading
• Commit and push

Done. Pushed in 060b9c7. The type-change bullet is now a proper ### Changing a column's data type section sitting between ### Changing constraints and ### Operations that require recreating the table. Each connector gets its own prose:

• Postgres: errors on any type change except to text
• MySQL: errors only when the new type maps to a different Materialize type; safe cases (same-MZ-type casts, enum appends) listed in a follow-on paragraph
• SQL Server: any ALTER COLUMN errors
  ·