Electric 同步引擎的 PostgreSQL 权限配置全指南：三种模式、核心权限清单与手动发布配置

Electric 同步引擎的 PostgreSQL 权限配置全指南三种模式、核心权限清单与手动发布配置【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric本指南基于开源仓库electricAgent 平台的内置同步引擎核心实现位于 packages/sync-service官方文档与源码系统讲解如何为 Electric 创建和配置具备必要权限的 PostgreSQL 用户。读完本文你将掌握超级用户、Electric 托管发布自动模式与手动模式最小权限三种权限方案的适用场景与完整 SQL 配置理解ELECTRIC_MANUAL_TABLE_PUBLISHING、ELECTRIC_REPLICATION_STREAM_ID等关键配置项背后的源码实现并能够独立完成发布Publication与REPLICA IDENTITY FULL的手动配置与验证。你应该选择哪种权限方案Electric 需要通过 逻辑复制 读取 Postgres 的变更流并管理发布对象Publication。根据不同场景官方文档给出了三种由高到低的权限方案方案适用场景优点缺点连接配置 超级用户推荐用于开发本地开发、测试或简单的生产部署设置最简单Electric 全自动管理一切权限级别最高DATABASE_URLpostgresql://postgres:... Electric 托管发布自动模式生产推荐生产环境Electric 可以拥有数据库表Electric 自动管理发布与REPLICA IDENTITYElectric 必须拥有表应用失去表所有权创建专用用户并转移表所有权 手动模式最小权限高安全环境、应用必须拥有表、严格权限分离应用保留表所有权Electric 权限最小DBA 必须预配置发布新增表需手动加入仅REPLICATIONSELECTDBA 配置发布三种方案的详细配置步骤分别见下文 开发环境配置、Electric 托管发布配置 与 手动模式配置。自动 vs 手动发布管理Electric 在两种模式下运行其行为差异由配置项ELECTRIC_MANUAL_TABLE_PUBLISHING控制默认值为false。1. Electric 托管发布自动模式推荐当客户端请求某个表的 shape 时Electric 会在 Postgres 内自动创建发布publication并把表加入其中同时自动设置REPLICA IDENTITY FULL。这要求 Electric 的数据库用户具备数据库上的CREATE权限和表的所有权——PostgreSQL 规定只有表的所有者才能把表加入发布也只有表的所有者才能设置REPLICA IDENTITY FULL。从源码看该逻辑由 configurator.ex 中的PublicationManager.Configurator一个 GenServer实现。它维护一个目标关系集合收到 shape 订阅请求后去比对当前发布的实际状态并生成to_add加入发布、to_configure_replica_identity配置 replica identity、to_drop移除等动作清单最终通过 configuration.ex 中的configure_table_for_replication/4在一个事务内依次执行ALTER PUBLICATION ... ADD TABLE与ALTER TABLE ... REPLICA IDENTITY FULLdefp do_publication_update(:add_and_configure, filter, state) do with :ok - Configuration.configure_table_for_replication( state.db_pool, state.publication_name, filter ) do {:ok, :configured} end end值得注意的实现细节源码注释明确指出ALTER PUBLICATION ... ADD TABLE只持有表的SHARE UPDATE EXCLUSIVE锁与写入者不冲突因此在该事务内还会额外执行LOCK TABLE ... IN SHARE MODE作为屏障等待所有在途写入者结束从而保证加入发布之前的写入要么通过初始快照可见、要么通过复制流可见不会出现变更丢失。详见 configuration.ex。2. 手动模式手动模式下发布由 DBA 提前创建和维护Electric 只负责校验现有配置是否满足要求而不会自动增删表。启用方式ELECTRIC_MANUAL_TABLE_PUBLISHINGtrue该模式只需要REPLICATION和SELECT权限但你必须在请求 shape 之前预先创建发布、把表加入发布并为每张表设置REPLICA IDENTITY FULL。从源码看configurator.ex 中的can_update_publication?/1函数同时检查能否修改发布和是否手动模式两个条件defp can_update_publication?(%__MODULE__{ can_alter_publication?: can_alter, manual_table_publishing?: manual }) do can_alter and not manual end当手动模式开启时Electric 对缺失的配置会返回明确的错误而不是自行修复。例如表未加入发布时configurator.ex 会生成如下错误信息Database table public.items is missing from the publication ... and the ELECTRIC_MANUAL_TABLE_PUBLISHING setting prevents Electric from adding it这一行为有完整的测试与集成测试覆盖单元测试见 publication_manager_manual_test.exs分别验证表不在发布中报错与replica identity 非 FULL 报错两个场景端到端集成测试见 manual-table-publishing.lux它用一个low_privilege角色实际启动 Postgres 与 Electric逐级演示了缺表 → 加表 → 仍缺 replica identity → 设置 FULL → 缺 SELECT 权限的完整报错链路。核心权限要求一览根据模式不同Electric 所需的 PostgreSQL 权限如下权限用途Electric 托管手动模式REPLICATION启用逻辑复制流✅ 必需✅ 必需表上的SELECT读取表数据以生成初始 shape 快照✅ 必需✅ 必需数据库上的CREATE创建发布✅ 必需❌ 不需要表所有权设置REPLICA IDENTITY FULL并把表加入发布✅ 必需❌ 由 DBA 配置发布所有权修改发布增删表✅ 必需❌ 由 DBA 配置另外DATABASE_URL中的用户必须具有REPLICATION角色。可参考 配置参考 中关于DATABASE_URL的说明连接串的userspec部分指定的就是 Electric 连接 Postgres 所用的用户。设置示例开发环境配置For Development开发环境直接使用默认的postgres超级用户或其他超级用户角色DATABASE_URLpostgresql://postgres:your_passwordlocalhost:5432/your_databaseElectric 会自动创建发布、配置REPLICA IDENTITY FULL并管理一切。对于追求简便、安全性要求不高的简单生产部署同样适用。Electric 托管发布配置Electric-managed publications Setup创建一个专用 Electric 用户并授予自动表配置所需权限。Electric 会在 shape 被请求时自动创建发布、加入表-- 创建带 REPLICATION 的 Electric 用户 CREATE ROLE electric_user WITH LOGIN PASSWORD secure_password REPLICATION; -- 授予数据库级权限 GRANT CONNECT ON DATABASE mydb TO electric_user; GRANT USAGE ON SCHEMA public TO electric_user; GRANT CREATE ON DATABASE mydb TO electric_user; -- 创建发布所需 -- 授予表上的 SELECTElectric 只读仅需读数据 -- 所有表 GRANT SELECT ON ALL TABLES IN SCHEMA public TO electric_user; -- 未来新建的表自动获得 SELECTALTER DEFAULT PRIVILEGES ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO electric_user; -- 只授权特定表 -- GRANT SELECT ON public.users, public.posts TO electric_user;将表所有权转移给 ElectricPostgreSQL 要求表所有者才能把表加入发布并设置REPLICA IDENTITY FULL因此必须把表所有权转移给electric_user。针对特定表推荐做法ALTER TABLE public.users OWNER TO electric_user; ALTER TABLE public.posts OWNER TO electric_user; ALTER TABLE public.comments OWNER TO electric_user;或者将该 schema 下的所有表一次转移DO $$ DECLARE r RECORD; BEGIN FOR r IN SELECT tablename FROM pg_tables WHERE schemaname public LOOP EXECUTE ALTER TABLE public. || quote_ident(r.tablename) || OWNER TO electric_user; END LOOP; END$$;[!Warning] 所有权转移警告 转移表所有权会让原所有者失去所有权。如果应用必须保留表所有权请改用 手动模式由 DBA 预先配置发布与REPLICA IDENTITY FULL。配置完成后连接 ElectricDATABASE_URLpostgresql://electric_user:secure_passwordlocalhost:5432/mydb手动模式配置Manual Mode Setup对于有严格安全要求的环境可使用手动发布管理来最小化 Electric 的权限-- 创建带 REPLICATION但其他权限最小化的 Electric 用户 CREATE ROLE electric_user WITH LOGIN PASSWORD secure_password REPLICATION; -- 只授予连接与 usage 权限 GRANT CONNECT ON DATABASE mydb TO electric_user; GRANT USAGE ON SCHEMA public TO electric_user; -- 只对特定表授予 SELECT GRANT SELECT ON public.users TO electric_user; GRANT SELECT ON public.posts TO electric_user;然后以超级用户或数据库所有者身份按照下文 手动配置步骤 创建发布、加入表并配置 replica identity。配置 ElectricDATABASE_URLpostgresql://electric_user:secure_passwordlocalhost:5432/mydb ELECTRIC_MANUAL_TABLE_PUBLISHINGtrueAWS RDS 和 AuroraAWS RDS 与 Aurora 在复制权限方面需要特殊处理。参考 AWS 集成指南在自定义参数组中将rds.logical_replication1这会设置wal_levellogical然后重启实例默认的postgres用户已具备REPLICATION角色若需给其他用户授予复制权限通过rds_replication角色实现GRANT rds_replication TO someuser;手动配置步骤Manual Configuration Steps当你需要为ELECTRIC_MANUAL_TABLE_PUBLISHINGtrue手动配置发布与 replica identity 时按以下 5 步执行。1. 创建发布Create the Publication-- 创建空发布 CREATE PUBLICATION electric_publication_default; -- 或使用自定义名称需同时配置 ELECTRIC_REPLICATION_STREAM_ID 保持一致 CREATE PUBLICATION my_custom_publication;发布名称默认形如electric_publication_stream_id。默认的ELECTRIC_REPLICATION_STREAM_ID为default见 config.ex 中的replication_stream_id: default该配置项作为逻辑复制发布与 slot 名称的后缀详见 配置参考。2. 将表加入发布Add Tables to the PublicationALTER PUBLICATION electric_publication_default ADD TABLE public.users; ALTER PUBLICATION electric_publication_default ADD TABLE public.posts; ALTER PUBLICATION electric_publication_default ADD TABLE public.comments;[!Tip] 更精简的等价操作 配置参考 中给出了每次新增 shape 前的等价最小步骤可将两步合并到同一事务BEGIN; ALTER PUBLICATION electric_publication_default ADD TABLE my table; ALTER TABLE my table REPLICA IDENTITY FULL; COMMIT;3. 配置 Replica Identity每张要同步的表都必须把 replica identity 设置为FULLALTER TABLE public.users REPLICA IDENTITY FULL; ALTER TABLE public.posts REPLICA IDENTITY FULL; ALTER TABLE public.comments REPLICA IDENTITY FULL;这会让 Postgres 在复制流中输出所有列的值是 Electric 实现精确变更跟踪的前提。4. 设置发布所有权让 Electric 用户成为发布的所有者或确保发布由 Electric 连接所用的同一用户创建ALTER PUBLICATION electric_publication_default OWNER TO electric_user;5. 验证配置用下面的 SQL 检查发布是否配置正确-- 验证 Electric 角色具有 REPLICATION 权限 SELECT rolname, rolreplication FROM pg_roles WHERE rolname electric_user; -- 列出所有发布 SELECT * FROM pg_publication; -- 检查发布设置 SELECT pubname, pubinsert, pubupdate, pubdelete, pubtruncate FROM pg_publication WHERE pubname electric_publication_default; -- 列出发布中的表 SELECT schemaname, tablename FROM pg_publication_tables WHERE pubname electric_publication_default; -- 检查表的 replica identity SELECT schemaname, tablename, relreplident FROM pg_class JOIN pg_namespace ON pg_class.relnamespace pg_namespace.oid WHERE relreplident f; -- f 表示 FULL从源码看Electric 启动时正是通过类似的 SQL 来体检发布状态的。configuration.ex 中的check_publication_status!/2会查询pg_get_userbyid(p.pubowner) current_role—— 当前角色能否修改发布can_alter_publicationpubinsert AND pubupdate AND pubdelete AND pubtruncate—— 发布是否覆盖全部操作类型publishes_all_operationsPostgreSQL 18 上还会检查pubgencols是否发布生成列publishes_generated_columns。如果发布不存在或未发布全部操作configurator.ex 会判定为致命配置错误在自动模式下会尝试重启连接子系统自愈而在手动模式下则只记录警告提示你手动修正配置。常见权限错误排查以下内容摘录自 故障排查指南 的 Database permissions 一节insufficient privilege to create publication原因用户没有数据库上的CREATE权限。解决执行GRANT CREATE ON DATABASE mydb TO electric_user;或者改用手动发布管理由超级用户创建发布并设置ELECTRIC_MANUAL_TABLE_PUBLISHINGtrue。publication not owned by the provided user原因发布已存在但所有者是其他用户。解决转移发布所有权ALTER PUBLICATION electric_publication_default OWNER TO electric_user;table does not have its replica identity set to FULL原因表未配置REPLICA IDENTITY FULL。解决手动设置ALTER TABLE schema.tablename REPLICA IDENTITY FULL;permission denied for table原因Electric 用户没有该表的SELECT权限。解决授权GRANT SELECT ON schema.tablename TO electric_user;must be owner of table原因执行了需要所有权的操作如ALTER TABLE ... REPLICA IDENTITY FULL或把表加入发布。解决以表所有者或超级用户身份执行或转移所有权ALTER TABLE schema.tablename OWNER TO electric_user;从源码理解权限校验链路最后把上面提到的实现串成一条完整的调用链便于你深入阅读源码shape 订阅请求到达后PublicationManager向 ConfiguratorElectric.Replication.PublicationManager.Configurator发出更新请求Configurator 通过 ConfigurationElectric.Postgres.Configuration执行check_publication_status!/2检查发布存在性与操作覆盖度再执行determine_publication_relation_actions!/3计算需要的动作若can_update_publication?/1返回true可修改发布且非手动模式按排序后的动作清单依次执行add_table_to_publication/4、set_table_replica_identity_full/4、drop_table_from_publication/4否则对每个缺失的表返回relation_missing_from_publication或misconfigured_replica_identity错误上述校验逻辑由 publication_manager_manual_test.exs 与 manual-table-publishing.lux 双重验证。下一步查看 部署指南 了解生产环境部署方案阅读 安全最佳实践遇到问题参考 故障排查指南查看 配置参考 了解全部可用配置项如DATABASE_URL、ELECTRIC_POOLED_DATABASE_URL、ELECTRIC_REPLICATION_STREAM_ID等。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考