fix(source): PostgreSQL/MySQL CDC source vs table relationship

[xiangjinwu]

Info

• Description

  • Initially, CDC can only be created as table but not source.
  • After #1754, there are 2 options:
    • Create a table directly, same as before.
    • Create a shared source first, and then table based on the shared source.
  • After #2023, the first syntax is deprecated and the second syntax is recommended.

• Fixes in this PR (using PostgreSQL as example but may apply to MySQL as well):

  • table or source is never the case. It is table(deprecated) or source + table (recommended).
  • Link to create table syntax reference is useless. That page does not contain FROM source_name TABLE syntax for shared PostgreSQL/MySQL CDC.
  • FROM source TABLE is updated to FROM source_name TABLE in the example, to keep consistent with CREATE SOURCE source_name above.

• Notes

  • Once @StrikeW confirmed the content above is accurate, we may apply the same fix from PostgreSQL to MySQL, and from dev version to current or even older applicable versions.

• Related code PR

  • [ Provide a link to the relevant code PR here, if applicable. ]

• Related doc issue

  Resolves [ Provide a link to the relevant doc issue here, if applicable. ]

For reviewers

• Preview

  • [ Paste the preview link to the updated page(s) here. Edit this item after the preview site is ready. To find the updated pages, scroll down to locate and open the Amplify preview link and select the dev version of the documentation. ]

• Key points

  • [ Parts that may need revision or extra consideration. ]

Before merging

• I have checked the doc site preview, and the updated parts look good.

• I have acquired the approval from the owner (and optionally the reviewers) of the code PR and at least one tech writer (emile-00, hengm3467, & WanYixian).

[xiangjinwu]

Btw is the |table.name| Name of the table that you want to ingest data from. | parameter still useful? If the source is tied to an upstream table, there would be no point to share the source for multiple RisingWave tables, right?

[aws-amplify-us-east-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2449.d2fbku9n2b6wde.amplifyapp.com

[StrikeW]

Thanks for the fix.

[fuyufjh]

Overall LGTM

[fuyufjh]

Better to clarify the logic first: need to create a source before creating table

Suggested change

	Syntax for creating a shared CDC source.
	Before creating a table, you need to first create a source to the upstream MySQL database using the following syntax. This source can be shared by multiple tables from the same MySQL database.

[hengm3467]

Better use a complete sentence.

Suggested change

	Syntax for creating a CDC table based on the shared source. Note that a primary key is required and must be consistent with the upstream table.
	Below is the syntax for creating a CDC table based on the shared source. Note that a primary key is required and must be consistent with the upstream table.

[hengm3467]

It's ok as of now in this PR, but I feel it would be more useful if we have a topic or section about "shared sources" that we can now point to. There are a few RisingWave-specific concepts that we may want to elaborate somewhere. In addition, the "Sources" term in Glossary should be updated. cc: @st1page @WanYixian

[st1page]

Good catch. The shared source is still in development by @xxchan and it is expected to release in v2.1. I think we will add the doc that time.