Re: Fixing the docs for ALTER SUBSCRIPTION ... ADD/DROP PUBLICATION

On Sat, May 22, 2021 at 1:49 AM Mark Dilger
<mark(dot)dilger(at)enterprisedb(dot)com> wrote:
>
> -hackers,
>
> I think commit 82ed7748b710e3ddce3f7ebc74af80fe4869492f created some confusion that should be cleaned up before release. I'd like some guidance on what the intended behavior is before I submit a patch for this, though:
>
> +ALTER SUBSCRIPTION mysubscription SET PUBLICATION nosuchpub WITH (copy_data = false, refresh = false);
> +ALTER SUBSCRIPTION mysubscription ADD PUBLICATION nosuchpub WITH (copy_data = false, refresh = false);
> +ALTER SUBSCRIPTION mysubscription DROP PUBLICATION nosuchpub WITH (copy_data = false, refresh = false);
> +ERROR: unrecognized subscription parameter: "copy_data"
> +ALTER SUBSCRIPTION mysubscription SET (copy_data = false, refresh = false);
> +ERROR: unrecognized subscription parameter: "copy_data"
>
> First, it's quite odd to say that "copy_data" is unrecognized in the third and fourth ALTER commands when it was recognized just fine in the first two.

For ALTER SUBSCRIPTION ... DROP PUBLICATION, copy_data option is not
required actually, because it doesn't add new publications. If the
concern here is "why refresh is allowed but not copy_data", then the
answer is "with the refresh option the updated publications can be
refreshed, this avoids users to run REFRESH PUBLICATION after DROP
PUBLICATION". So, disallowing copy_data makes sense to me.

For ALTER SUBSCRIPTION ... SET, allowed options are slot_name,
synchronous_commit, binary and streaming which are part of
pg_subscription catalog and will be used by apply/sync workers.
Whereas copy_data and refresh are not part of pg_subscription catalog
and are not used by apply/sync workers (directly), but by the backend.
We have ALTER SUBSCRIPTION .. REFRESH specifically for refresh and
copy_data options.

> More than that, though, the docs in doc/src/sgml/ref/alter_subscription.sgml refer to this part of the grammar in the first three ALTER commands as a "set_publication_option", not as a "subscription_parameter", a term which is only used in the grammar for other forms of the ALTER command. Per the grammar in the docs, "copy_data" is not a valid set_publication_option, only "refresh" is.

set_publication_option - options are refresh and copy_data (this
option comes implicitly, please see the note "Additionally, refresh
options as described under REFRESH PUBLICATION may be specified.",
under refresh_option we have copy_data)

subscription_parameter - options are slot_name, synchronous_commit,
binary, and streaming. This is correct.

> Should the first three ALTER commands fail with an error about "copy_data" being an invalid set_publication_option? Should they succeed, in which case the docs should mention that "refresh" is not the only valid set_publication_option?

No that's not correct. As I said above, set_publication_option options
are both refresh and copy_data.

> Something else, perhaps?

Unless I misunderstood any of your concerns, I think the existing docs
and the code looks correct to me.

With Regards,
Bharath Rupireddy.
EnterpriseDB: http://www.enterprisedb.com