docs: clarify alter source add subsource (#34123)

Author: kay-kim

doc/user/content/ingest-data/_index.md

@@ -78,6 +78,11 @@ operation completes. Once the initial snapshot has been ingested, you can start
 querying your (sub)sources and Materialize will continue ingesting any new data
 as it arrives, in real time.
 
+### Modifying an existing source
+
+{{< include-md file="shared-content/alter-source-snapshot-blocking-behavior.md"
+>}}
+
 ## Running/steady-state
 
 Once snapshotting completes, Materialize transitions to Running state. During

doc/user/content/ingest-data/troubleshooting.md

@@ -98,6 +98,18 @@ also be necessary to support increased memory usage during the process. For more
 information, see [Use a larger cluster for upsert source
 snapshotting](/ingest-data/#use-a-larger-cluster-for-upsert-source-snapshotting).
 
+## Adding a new subsource to an existing source blocks replication. Should I just create a new source instead?
+
+It depends. Materialize provides transactional guarantees for subsource of the
+same source, not across different sources. So, if you need transactional
+guarantees across the tables between the two sources, you cannot use a new
+source. In addition, creating a new source means that you are reading the
+replication stream twice.
+
+To use the same source, consider resizing the cluster to speed up the
+snapshotting process for the new subsource and once the process finishes, resize
+the cluster for steady-state.
+
 ## See also
 
 - [Monitoring data ingestion](/ingest-data/monitoring-data-ingestion/)

doc/user/content/sql/alter-source.md

@@ -31,7 +31,8 @@ menu:
 Field   | Use
 --------|-----
 _name_  | The identifier of the source you want to alter.
-**ADD SUBSOURCE** ... | Add the identified tables from the upstream database (`table_name`) to the named PostgreSQL or MySQL source, with the option of choosing the name for the subsource in Materialize (`subsrc_name`). Supports [additional options](#add-subsource-with_options).
+**ADD SUBSOURCE** ... | Add the identified tables from the upstream database (`table_name`) to the named PostgreSQL/MySQL/SQL Server source, with the option of choosing the name for the subsource in Materialize (`subsrc_name`). Supports [additional options](#add-subsource-with_options). <br><br>{{< include-md file="shared-content/alter-source-snapshot-blocking-behavior.md"
+>}}
 _retention_period_ | ***Private preview.** This option has known performance or stability issues and is under active development.* Duration for which Materialize retains historical data, which is useful to implement [durable subscriptions](/transform-data/patterns/durable-subscriptions/#history-retention-period). Accepts positive [interval](/sql/types/interval/) values (e.g. `'1hr'`). Default: `1s`.
 
 ### **ADD SUBSOURCE** `with_options`
@@ -42,12 +43,17 @@ Field                                | Value           | Description
 
 ## Context
 
-### Adding subsources to a PostgreSQL or MySQL source
+### Adding subsources to a PostgreSQL/MySQL/SQL Server source
 
 Note that using a combination of dropping and adding subsources lets you change
-the schema of the PostgreSQL or MySQL tables that are ingested.
+the schema of the PostgreSQL/MySQL/SQL Server tables that are ingested.
 
-### Dropping subsources from a PostgreSQL or MySQL source
+{{< important >}}
+{{< include-md file="shared-content/alter-source-snapshot-blocking-behavior.md"
+>}}
+{{< /important >}}
+
+### Dropping subsources from a PostgreSQL/MySQL/SQL Server source
 
 Dropping a subsource prevents Materialize from ingesting any data from it, in
 addition to dropping any state that Materialize previously had for the table
@@ -67,6 +73,11 @@ You cannot drop the "progress subsource".
 ALTER SOURCE pg_src ADD SUBSOURCE tbl_a, tbl_b AS b WITH (TEXT COLUMNS [tbl_a.col]);
 ```
 
+{{< important >}}
+{{< include-md file="shared-content/alter-source-snapshot-blocking-behavior.md"
+>}}
+{{< /important >}}
+
 ### Dropping subsources
 
 To drop a subsource, use the [`DROP SOURCE`](/sql/drop-source/) command:

doc/user/shared-content/alter-source-snapshot-blocking-behavior.md

@@ -0,0 +1,6 @@
+When you add a new subsource to an existing source ([`ALTER SOURCE ... ADD
+SUBSOURCE ...`](/sql/alter-source/)), Materialize starts the snapshotting
+process for the new subsource. During this snapshotting, the data ingestion for
+the existing subsources for the same source is temporarily blocked. As such, if
+possible, you can resize the cluster to speed up the snapshotting process and
+once the process finishes, resize the cluster for steady-state.

doc/user/shared-content/mysql-considerations.md

@@ -20,3 +20,8 @@ truncating, you can use an unqualified `DELETE` to remove all rows from the tabl
 ```mzsql
 DELETE FROM t;
 ```
+
+### Modifying an existing source
+
+{{< include-md file="shared-content/alter-source-snapshot-blocking-behavior.md"
+>}}

doc/user/shared-content/postgres-considerations.md

@@ -10,3 +10,8 @@ replication slots:
 
 {{< include-md file="shared-content/postgres-remove-unused-replication-slots.md"
 >}}
+
+### Modifying an existing source
+
+{{< include-md file="shared-content/alter-source-snapshot-blocking-behavior.md"
+>}}

doc/user/shared-content/sql-server-considerations.md

@@ -54,3 +54,8 @@ system table. For each table, Materialize picks the capture instance with the
 most recent `create_date`.
 
 If two capture instances for a table share the same timestamp (unlikely given the millisecond resolution), Materialize selects the `capture_instance` with the lexicographically larger name.
+
+### Modifying an existing source
+
+{{< include-md file="shared-content/alter-source-snapshot-blocking-behavior.md"
+>}}