docs: add in-progress note w.r.t. supporting upstream table schema ch… (#32436)

…anges

Author: kay-kim

doc/user/content/sql/create-source/mysql.md

@@ -206,11 +206,13 @@ debugging related issues, see [Troubleshooting](/ops/troubleshooting/).
 
 ## Known limitations
 
-##### Schema changes
+### Schema changes
+
+{{< include-md file="shared-content/schema-changes-in-progress.md" >}}
 
 {{% schema-changes %}}
 
-##### Supported types
+### Supported types
 
 Materialize natively supports the following MySQL types:
 
@@ -259,7 +261,7 @@ The specified columns will be treated as `text`, and will thus not offer the
 expected MySQL type features. For any unsupported data types not listed above,
 use the [`EXCLUDE COLUMNS`](#excluding-columns) option.
 
-##### Truncation
+### Truncation
 
 Tables replicated into Materialize should not be truncated. If a table is
 truncated while replicated, the whole source becomes inaccessible and will not
@@ -272,15 +274,15 @@ DELETE FROM t;
 
 ## Examples
 
-{{< warning >}}
+{{< important >}}
 Before creating a MySQL source, you must enable GTID-based binlog replication in the
 upstream database. For step-by-step instructions, see the integration guide for
 your MySQL service: [Amazon RDS](/ingest-data/mysql/amazon-rds/),
 [Amazon Aurora](/ingest-data/mysql/amazon-aurora/),
 [Azure DB](/ingest-data/mysql/azure-db/),
 [Google Cloud SQL](/ingest-data/mysql/google-cloud-sql/),
 [Self-hosted](/ingest-data/mysql/self-hosted/).
-{{< /warning >}}
+{{< /important >}}
 
 ### Creating a connection
 
@@ -409,6 +411,8 @@ CREATE SOURCE mz_source
 
 ### Handling errors and schema changes
 
+{{< include-md file="shared-content/schema-changes-in-progress.md" >}}
+
 To handle upstream [schema changes](#schema-changes) or errored subsources, use
 the [`DROP SOURCE`](/sql/alter-source/#context) syntax to drop the affected
 subsource, and then [`ALTER SOURCE...ADD SUBSOURCE`](/sql/alter-source/) to add

doc/user/content/sql/create-source/postgres.md

@@ -196,11 +196,13 @@ ingestion progress and debugging related issues, see [Troubleshooting](/ops/trou
 
 ## Known limitations
 
-##### Schema changes
+### Schema changes
+
+{{< include-md file="shared-content/schema-changes-in-progress.md" >}}
 
 {{% schema-changes %}}
 
-#### Publication membership
+### Publication membership
 
 PostgreSQL's logical replication API does not provide a signal when users remove
 tables from publications. Because of this, Materialize relies on periodic checks
@@ -217,7 +219,7 @@ To mitigate this issue, if you need to drop and re-add a table to a publication,
 ensure that you remove the table/subsource from the source _before_ re-adding it
 using the [`DROP SOURCE`](/sql/drop-source/) command.
 
-##### Supported types
+### Supported types
 
 Materialize natively supports the following PostgreSQL types (including the
 array type for each of the types):
@@ -264,7 +266,7 @@ example:
 * [`money`]: the resulting `text` value cannot be cast back to e.g. `numeric`,
   since PostgreSQL adds typical currency formatting to the output.
 
-##### Truncation
+### Truncation
 
 Tables replicated into Materialize should not be truncated. If a table is
 truncated while replicated, the whole source becomes inaccessible and will not
@@ -275,7 +277,7 @@ using an unqualified `DELETE`.
 DELETE FROM t;
 ```
 
-##### Inherited tables
+### Inherited tables
 
 When using [PostgreSQL table inheritance](https://www.postgresql.org/docs/current/tutorial-inheritance.html),
 PostgreSQL serves data from `SELECT`s as if the inheriting tables' data is also
@@ -297,7 +299,7 @@ non-) that unions the new table.
 
 ## Examples
 
-{{< warning >}}
+{{< important >}}
 Before creating a PostgreSQL source, you must set up logical replication in the
 upstream database. For step-by-step instructions, see the integration guide for
 your PostgreSQL service: [AlloyDB](/ingest-data/postgres-alloydb/),
@@ -306,7 +308,7 @@ your PostgreSQL service: [AlloyDB](/ingest-data/postgres-alloydb/),
 [Azure DB](/ingest-data/postgres-azure-db/),
 [Google Cloud SQL](/ingest-data/postgres-google-cloud-sql/),
 [Self-hosted](/ingest-data/postgres-self-hosted/).
-{{< /warning >}}
+{{< /important >}}
 
 ### Creating a connection
 
@@ -431,6 +433,8 @@ CREATE SOURCE mz_source
 
 ### Handling errors and schema changes
 
+{{< include-md file="shared-content/schema-changes-in-progress.md" >}}
+
 To handle upstream [schema changes](#schema-changes) or errored subsources, use
 the [`DROP SOURCE`](/sql/alter-source/#context) syntax to drop the affected
 subsource, and then [`ALTER SOURCE...ADD SUBSOURCE`](/sql/alter-source/) to add

doc/user/content/sql/create-source/sql-server.md

@@ -123,11 +123,13 @@ ingestion progress and debugging related issues, see [Troubleshooting](/ops/trou
 
 ## Known limitations
 
-##### Schema changes
+### Schema changes
+
+{{< include-md file="shared-content/schema-changes-in-progress.md" >}}
 
 {{% schema-changes %}}
 
-##### Supported types
+### Supported types
 
 Materialize natively supports the following SQL Server types:
 
@@ -176,7 +178,7 @@ Columns with the specified types need to be excluded because [SQL Server does no
 the "before"](https://learn.microsoft.com/en-us/sql/relational-databases/system-tables/cdc-capture-instance-ct-transact-sql?view=sql-server-2017#large-object-data-types)
 value when said column is updated.
 
-#### Timestamp Rounding
+### Timestamp Rounding
 
 The `time`, `datetime2`, and `datetimeoffset` types in SQL Server have a default
 scale of 7 decimal places, or in other words a accuracy of 100 nanoseconds. But
@@ -201,10 +203,10 @@ SELECT * FROM my_timestamps;
 
 ## Examples
 
-{{< warning >}}
+{{< important >}}
 Before creating a SQL Server source, you must enable Change Data Capture and
 `SNAPSHOT` transaction isolation in the upstream database.
-{{< /warning >}}
+{{</ important >}}
 
 ### Creating a connection
 
@@ -305,6 +307,8 @@ CREATE SOURCE mz_source
 
 ### Handling errors and schema changes
 
+{{< include-md file="shared-content/schema-changes-in-progress.md" >}}
+
 To handle upstream [schema changes](#schema-changes) or errored subsources, use
 the [`DROP SOURCE`](/sql/alter-source/#context) syntax to drop the affected
 subsource, and then [`ALTER SOURCE...ADD SUBSOURCE`](/sql/alter-source/) to add

doc/user/shared-content/schema-changes-in-progress.md

@@ -0,0 +1,7 @@
+{{< note >}}
+
+Work to more smoothly support ddl changes to upstream tables is currently in
+progress. The work introduces the ability to re-ingest the same upstream table
+under a new schema and switch over without downtime.
+
+{{</ note >}}