docs: clarify parallelism migration guidance for existing jobs and new default strategies

[Copilot]

Users repeatedly hit confusion around whether system-level parallelism settings retroactively apply to existing streaming jobs — they do not. This adds a dedicated migration guide covering both the "future jobs" path (ALTER SYSTEM) and the "existing jobs" path (per-relation ALTER).

Description

operate/manage-a-large-number-of-streaming-jobs.mdx — new section: Migrate to recommended parallelism defaults

• Recommended defaults table — documents streaming_parallelism_strategy_for_source, streaming_parallelism_strategy_for_table, and adaptive_parallelism_strategy target values with an explicit callout that they apply to newly created jobs only.
• System defaults SQL — three ALTER SYSTEM SET statements to configure cluster-wide defaults for future jobs.
• Existing-relations migration playbook — three-step SQL workflow:
  1. Inspect current parallelism via rw_streaming_parallelism
  2. Generate ALTER … SET PARALLELISM = 4 for sources/tables deviating from target
  3. Generate ALTER … SET PARALLELISM = adaptive for unbounded adaptive MVs/sinks/indexes
• Operational safety — actor-count check, staged rollout, per-batch verification, capacity awareness.
• Version awareness — parameters (adaptive_parallelism_strategy, streaming_parallelism_strategy_for_source, streaming_parallelism_strategy_for_table) were introduced in v2.3.0; the recommended BOUNDED(4) / BOUNDED(64) defaults were introduced in v2.8.0. Clusters upgraded from versions before v2.8.0 do not automatically inherit the new defaults.

deploy/k8s-cluster-scaling.mdx — cross-link section at page end pointing to the new migration guide for clusters created before v2.8.0 or before the recommended defaults were applied.

Related code PR

risingwavelabs/risingwave#24678

Related doc issue

https://github.com/risingwavelabs/risingwave-docs/issues/

Checklist

• I have run the documentation build locally to verify the updates are applied correctly.
• For new pages, I have updated mint.json to include the page in the table of contents.
• All links and references have been checked and are not broken.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Clarify parallelism migration guidance: SQL for existing jobs and new default strategies</issue_title>
<issue_description>## Context
Slack thread (customer + internal triage):

• https://web.clearfeed.app/collections/6077?account=fb6b8016-a0a7-4415-8d9d-36ffcf3d3e77&request=1879
• https://risingwave-labs.slack.com/archives/C0846L0TZDH/p1771343093899839?thread_ts=1771248224.078289&cid=C0846L0TZDH
• https://risingwave-labs.slack.com/archives/C0846L0TZDH/p1771523030870329?thread_ts=1771248224.078289&cid=C0846L0TZDH

Related change referenced in discussion:

• Bound default adaptive parallelism to 64 risingwave#24678

Current docs pages involved:

• https://github.com/risingwavelabs/risingwave-docs/blob/main/operate/manage-a-large-number-of-streaming-jobs.mdx
• https://github.com/risingwavelabs/risingwave-docs/blob/main/deploy/k8s-cluster-scaling.mdx

Problem

Users are confused about whether they must manually update all existing MVs/streaming jobs when adopting newer recommended defaults (bounded(4) for source/table and bounded(64) system adaptive).

The current docs explain adaptive strategy and per-object ALTER commands, but do not clearly provide:

1. A migration playbook for clusters that were created before the new defaults.
2. SQL patterns to generate bulk ALTER statements for existing relations.
3. A clear split between:

• settings that affect future jobs only, and
• per-relation changes required for existing jobs.

This gap leads to repeated support questions and inconsistent operational changes.

Suggested Fix

Add a dedicated note/section in operate/manage-a-large-number-of-streaming-jobs.mdx (and cross-link from deploy/k8s-cluster-scaling.mdx) titled something like Migrate to recommended parallelism defaults.

Include:

1. Recommended defaults and scope

• streaming_parallelism_strategy_for_source = 'BOUNDED(4)'
• streaming_parallelism_strategy_for_table = 'BOUNDED(4)'
• adaptive_parallelism_strategy = 'BOUNDED(64)'
• Explicitly state these defaults affect newly created jobs (unless altered later).

2. SQL to set system defaults for future jobs

ALTER SYSTEM SET streaming_parallelism_strategy_for_source = 'BOUNDED(4)';
ALTER SYSTEM SET streaming_parallelism_strategy_for_table = 'BOUNDED(4)';
ALTER SYSTEM SET adaptive_parallelism_strategy = 'BOUNDED(64)';

3. SQL patterns to migrate existing relations

• Show how to inspect current parallelism and generate ALTER statements for existing relations that deviate from target values.
• Provide separate examples for source/table vs other streaming jobs where appropriate.
• Keep examples safe and explicit (generate SQL first, review, then execute).

4. Operational safety notes

• Recommend staged rollout and observation window.
• Call out actor-count/capacity checks before and after changes.
• Clarify there is no single switch that force-updates all existing jobs without per-relation ALTER.

5. Version-awareness note

• Mention that clusters on older versions may not have these defaults and should follow migration guidance.

This should reduce ambiguity around “existing vs future” behavior and make support guidance consistent with PR risingwavelabs/risingwave-docs#24678 defaults.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Clarify parallelism migration guidance: SQL for existing jobs and new default strategies #1012

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[kwannoel]

@copilot this should be v2.8.0

[Copilot]

Updated in 54c1211 — changed v2.3.0 to v2.8.0 in both k8s-cluster-scaling.mdx and the version-awareness section in manage-a-large-number-of-streaming-jobs.mdx. I also kept the existing v2.3.0 reference (when the parameters themselves were first introduced) and clarified that the recommended BOUNDED defaults were added in v2.8.0.