Improve CLEANUP_REPLICATION_SLOTS_ON_SHUTDOWN and ELECTRIC_TEMPORARY_REPLICATION_SLOT_USE_RANDOM_NAME documentation

[sdavids]

https://electric.ax/docs/sync/api/config#cleanup-replication-slots-on-shutdown
https://electric.ax/docs/sync/api/config#electric-temporary-replication-slot-use-random-name

Please document which permissions the database role needs to enable these two options.

While you are at it, the required permissions could be mentioned here as well:

https://electric.ax/docs/sync/api/config#electric-manual-table-publishing

Maybe link to: https://electric.ax/docs/sync/guides/postgres-permissions#automatic-vs-manual-publication-management

Please document how to use both in Manual Mode or if they cannot be used in that setup.

[alco]

Hi @sdavids. Have you hit a specific issue trying to use these configuration options?

The Permissions guide is quite detailed in terms of what is required for Electric to successfully set up replication connection and run DB queries on regular connections.

There are no particular permission implications to consider when using the configuration options you've mentioned AFAIK. The database role that Electric is configured with must have the REPLICATION attribute and have CREATE permission on the database.

[sdavids]

There are no particular permission implications to consider when using the configuration options you've mentioned AFAIK. The database role that Electric is configured with must have the REPLICATION attribute and have CREATE permission on the database.

In the description of the environment variables

https://electric.ax/docs/sync/api/config#cleanup-replication-slots-on-shutdown
https://electric.ax/docs/sync/api/config#electric-temporary-replication-slot-use-random-name
https://electric.ax/docs/sync/api/config#electric-manual-table-publishing

a link to

https://electric.ax/docs/sync/guides/postgres-permissions#core-permission-requirements

would be appreciated—I think that would make it clearer.

[sdavids]

There are no particular permission implications to consider when using the configuration options you've mentioned AFAIK. The database role that Electric is configured with must have the REPLICATION attribute and have CREATE permission on the database.

Currently, one can use the following setup:

CREATE USER electric WITH LOGIN PASSWORD 'electric' REPLICATION;
GRANT USAGE ON SCHEMA public TO electric;
GRANT CONNECT ON DATABASE mydb TO electric;
ALTER ROLE electric IN DATABASE mydb SET search_path = 'public';

CREATE PUBLICATION electric_publication_default;

ALTER TABLE mytbl REPLICA IDENTITY FULL;

GRANT SELECT ON mytbl TO electric;

ALTER PUBLICATION electric_publication_default ADD TABLE mytbl;

ALTER PUBLICATION electric_publication_default OWNER TO electric;

ELECTRIC_MANUAL_TABLE_PUBLISHING=true works in this setup.

---

Let's say I want to use CLEANUP_REPLICATION_SLOTS_ON_SHUTDOWN=true and/or ELECTRIC_TEMPORARY_REPLICATION_SLOT_USE_RANDOM_NAME=true

If I understand you correctly, the setup above (manual setup) does not work with these two options unless you give the role the CREATE permission:

GRANT CREATE, CONNECT ON DATABASE mydb TO electric;

But does this not defeat the purpose of ELECTRIC_MANUAL_TABLE_PUBLISHING=true?

[alco]

If I understand you correctly, the setup above (manual setup) does not work with these two options unless you give the role the CREATE permission:

Replication slot creation is permitted by the REPLICATION role attribute. The role does not need to have the CREATE permission on the database.

You can certainly use ELECTRIC_MANUAL_TABLE_PUBLISHING with a persistent replication slot, in which case Electric creates the slot on first connection attempt. Using CLEANUP_REPLICATION_SLOTS_ON_SHUTDOWN leads to creation of a new slot every time Electric reconnects but it doesn't carry any extra permissions requirements compared to the base case.

[alco]

Thanks for the feedback. I've opened a small docs PR that adds a cross-reference from the ELECTRIC_MANUAL_TABLE_PUBLISHING config option to the Manual Mode Setup guide: #4293

Regarding CLEANUP_REPLICATION_SLOTS_ON_SHUTDOWN and ELECTRIC_TEMPORARY_REPLICATION_SLOT_USE_RANDOM_NAME — these don't need additional permissions documentation because replication slot management is covered by the REPLICATION role attribute, which is already listed as a core requirement for all setups. There's no distinction between automatic and manual mode when it comes to slot operations.