docs: Add comprehensive PostgreSQL permissions guide (#3278)

KyleAMathews · claude · web-flow · commit 980218e7df6b · 2025-10-15T14:36:35.000-06:00
## Summary https://deploy-preview-3278--electric-next.netlify.app/docs/guides/postgres-permissions Adds a comprehensive guide for setting up PostgreSQL users with the necessary permissions for Electric. This documentation addresses a common setup question by providing clear, actionable guidance for different deployment scenarios. ## What's included - **Quick start** example for common use cases - **Three setup scenarios**: - Global setup (full database access) - Table-scoped setup (restricted to specific tables) - Minimum privilege setup (manual publication management) - **Core permission requirements** explained: - REPLICATION role - CREATE, SELECT, ALTER TABLE privileges - Publication ownership - **Automatic vs manual publication management** modes - **AWS RDS/Aurora** specific configuration - **Manual configuration steps** for publications and replica identity - **Troubleshooting section** with common errors and solutions - **Security best practices** ## Why this is needed Based on investigation of the sync-service codebase (particularly `Electric.Postgres.Configuration` and `Electric.Postgres.ReplicationClient.ConnectionSetup`), Electric requires specific PostgreSQL permissions that aren't fully documented in one place. This guide consolidates that information with practical examples. ## Test plan - [ ] Verify documentation renders correctly on the docs site - [ ] Check all SQL examples for syntax correctness - [ ] Validate links to other documentation pages 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts
@@ -231,6 +231,10 @@ export default defineConfig({
             { text: 'Shapes', link: '/docs/guides/shapes' },
             { text: 'Writes', link: '/docs/guides/writes' },
             { text: 'Installation', link: '/docs/guides/installation' },
+            {
+              text: 'PostgreSQL Permissions',
+              link: '/docs/guides/postgres-permissions',
+            },
             { text: 'Deployment', link: '/docs/guides/deployment' },
             { text: 'Security', link: '/docs/guides/security' },
             { text: 'Troubleshooting', link: '/docs/guides/troubleshooting' },
diff --git a/website/docs/guides/installation.md b/website/docs/guides/installation.md
@@ -48,6 +48,8 @@ docker run \
 
 You can use any Postgres (new or existing) that has [logical replication](https://www.postgresql.org/docs/current/logical-replication-config.html) enabled. You also need to connect as a database user that has the [`REPLICATION`](https://www.postgresql.org/docs/current/logical-replication-security.html) role.
 
+See the [PostgreSQL Permissions guide](/docs/guides/postgres-permissions) for detailed instructions on configuring database users with the necessary permissions for Electric.
+
 ## Advanced
 
 You can also choose to build and run Electric [from source](https://github.com/electric-sql/electric) as an [Elixir](https://elixir-lang.org) application.
diff --git a/website/docs/guides/postgres-permissions.md b/website/docs/guides/postgres-permissions.md
@@ -0,0 +1,244 @@
+---
+title: PostgreSQL Permissions - Guide
+description: >-
+  How to create and configure PostgreSQL users with the necessary permissions for Electric.
+outline: [2, 3]
+---
+
+# PostgreSQL Permissions
+
+This guide explains how to create PostgreSQL users with the necessary permissions for Electric to work correctly. Electric requires specific database privileges to enable [logical replication](https://www.postgresql.org/docs/current/logical-replication.html) and manage publications.
+
+## Quick Start
+
+Choose the approach that fits your needs:
+
+**For Development:**
+Use the default `postgres` superuser. Electric will automatically configure everything.
+
+```shell
+DATABASE_URL=postgresql://postgres:your_password@localhost:5432/your_database
+```
+
+This is often fine for production too. See [For Development](#for-development) below for details.
+
+**For Production (Automatic Mode):**
+Create a dedicated Electric user with automatic table configuration.
+→ See [Automatic Mode Setup](#automatic-mode-setup)
+
+**For Production (Manual Mode / Least-Privilege):**
+Pre-configure tables manually and use minimal Electric privileges.
+→ See [Manual Mode Setup](#manual-mode-setup)
+
+## Core Permission Requirements
+
+Electric needs the following PostgreSQL permissions:
+
+| Permission | Purpose | Required For |
+|------------|---------|--------------|
+| [`REPLICATION`](https://www.postgresql.org/docs/current/sql-createrole.html) | Enable logical replication streaming | Creating [replication slots](https://www.postgresql.org/docs/current/warm-standby.html#STREAMING-REPLICATION-SLOTS) and consuming the [WAL](https://www.postgresql.org/docs/current/wal-intro.html) |
+| [`CREATE`](https://www.postgresql.org/docs/current/ddl-priv.html) on database | Create publications | Automatic publication management |
+| [`SELECT`](https://www.postgresql.org/docs/current/sql-grant.html) on tables | Read table data | Initial shape snapshots |
+| [Table ownership](https://www.postgresql.org/docs/current/ddl-priv.html) | Set replica identity | Configuring [`REPLICA IDENTITY FULL`](https://www.postgresql.org/docs/current/sql-altertable.html) |
+| [Publication ownership](https://www.postgresql.org/docs/current/sql-createpublication.html) | Modify publications | Adding/removing tables from publication; you must also own each table you add to the publication |
+
+## Automatic vs Manual Publication Management
+
+Electric can operate in two modes:
+
+### 1. Automatic Mode (Recommended)
+
+Electric automatically creates the publication and adds tables to it as shapes are requested. Requires `CREATE` privilege on the database and either table ownership or pre-configured `REPLICA IDENTITY FULL` on tables.
+
+### 2. Manual Mode
+
+You manually manage the publication and Electric only validates the configuration. Enable this with [`ELECTRIC_MANUAL_TABLE_PUBLISHING=true`](/docs/api/config#electric-manual-table-publishing). Requires only `REPLICATION` and `SELECT` privileges, but you must pre-configure the publication and `REPLICA IDENTITY FULL`.
+
+**When to use manual mode:**
+- When Electric's database user doesn't have `CREATE` privileges
+- When you want explicit control over which tables are replicated
+- In security-sensitive environments with strict privilege separation
+
+## Setup Examples
+
+### For Development
+
+Use the default `postgres` superuser or another superuser role:
+
+```shell
+DATABASE_URL=postgresql://postgres:your_password@localhost:5432/your_database
+```
+
+Electric will automatically create publications, configure `REPLICA IDENTITY FULL`, and manage everything for you. This is often fine for production too, especially for smaller deployments.
+
+### Automatic Mode Setup
+
+Create a dedicated Electric user with automatic table configuration. Electric will create publications and add tables as shapes are requested.
+
+```sql
+-- Create the Electric user with REPLICATION
+CREATE ROLE electric_user WITH LOGIN PASSWORD 'secure_password' REPLICATION;
+
+-- Grant database-level privileges
+GRANT CONNECT ON DATABASE mydb TO electric_user;
+GRANT USAGE, CREATE ON SCHEMA public TO electric_user;
+GRANT CREATE ON DATABASE mydb TO electric_user;
+
+-- Grant SELECT on tables (Electric is read-only, only needs to read data)
+-- For all tables:
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO electric_user;
+
+-- Grant SELECT on future tables automatically (https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html)
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+  GRANT SELECT ON TABLES TO electric_user;
+
+-- For specific tables only:
+-- GRANT SELECT ON public.users, public.posts TO electric_user;
+```
+
+**Handling REPLICA IDENTITY FULL - Choose one option:**
+
+**Option A: Pre-configure as DBA (Recommended)**
+
+Have your DBA or a superuser set `REPLICA IDENTITY FULL` before Electric runs, keeping table ownership with your application:
+
+```sql
+-- As superuser/DBA, set REPLICA IDENTITY on tables that will be synced
+ALTER TABLE public.users REPLICA IDENTITY FULL;
+ALTER TABLE public.posts REPLICA IDENTITY FULL;
+ALTER TABLE public.comments REPLICA IDENTITY FULL;
+```
+
+**Option B: Transfer Ownership to Electric**
+
+Transfer table ownership so Electric can manage `REPLICA IDENTITY` automatically:
+
+```sql
+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] Ownership Transfer
+> Transferring table ownership removes ownership from the previous owner. If you prefer to keep table ownership with your application or DBA role, use Option A instead.
+
+Then connect Electric:
+
+```shell
+DATABASE_URL=postgresql://electric_user:secure_password@localhost:5432/mydb
+```
+
+### Manual Mode Setup
+
+For environments with strict security requirements, you can use manual publication management to minimize Electric's privileges.
+
+```sql
+-- Create the Electric user with REPLICATION (but minimal other privileges)
+CREATE ROLE electric_user WITH LOGIN PASSWORD 'secure_password' REPLICATION;
+
+-- Grant only connection and usage privileges
+GRANT CONNECT ON DATABASE mydb TO electric_user;
+GRANT USAGE ON SCHEMA public TO electric_user;
+
+-- Grant SELECT only on specific tables
+GRANT SELECT ON public.users TO electric_user;
+GRANT SELECT ON public.posts TO electric_user;
+```
+
+Then, as a superuser or database owner, follow the [Manual Configuration Steps](#manual-configuration-steps) below to create the publication, add tables, and configure replica identity.
+
+Configure Electric with:
+
+```shell
+DATABASE_URL=postgresql://electric_user:secure_password@localhost:5432/mydb
+ELECTRIC_MANUAL_TABLE_PUBLISHING=true
+```
+
+## AWS RDS and Aurora
+
+AWS RDS and Aurora require special handling for replication permissions. See the [AWS integration guide](/docs/integrations/aws) for details on enabling logical replication and granting the `rds_replication` role.
+
+## Manual Configuration Steps
+
+If you need to manually configure the publication and replica identity (for use with `ELECTRIC_MANUAL_TABLE_PUBLISHING=true`):
+
+### 1. [Create the Publication](https://www.postgresql.org/docs/current/sql-createpublication.html)
+
+```sql
+-- Create an empty publication
+CREATE PUBLICATION electric_publication_default;
+
+-- Or with a custom name (configure with ELECTRIC_REPLICATION_STREAM_ID)
+CREATE PUBLICATION my_custom_publication;
+```
+
+### 2. [Add Tables to the Publication](https://www.postgresql.org/docs/current/sql-alterpublication.html)
+
+```sql
+-- Add specific tables
+ALTER 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;
+```
+
+### 3. [Configure Replica Identity](https://www.postgresql.org/docs/current/sql-altertable.html)
+
+For each table you want to sync, you must set the replica identity to `FULL`:
+
+```sql
+ALTER TABLE public.users REPLICA IDENTITY FULL;
+ALTER TABLE public.posts REPLICA IDENTITY FULL;
+ALTER TABLE public.comments REPLICA IDENTITY FULL;
+```
+
+This tells Postgres to include all column values in the replication stream, which Electric requires for accurate change tracking.
+
+### 4. Set Publication Ownership
+
+Make the Electric user the owner of the publication (or ensure the publication was created by the same user Electric connects as):
+
+```sql
+ALTER PUBLICATION electric_publication_default OWNER TO electric_user;
+```
+
+### 5. Verify the Configuration
+
+Check that your publication is correctly configured:
+
+```sql
+-- List all publications
+SELECT * FROM pg_publication;
+
+-- Check publication settings
+SELECT pubname, pubinsert, pubupdate, pubdelete, pubtruncate
+FROM pg_publication
+WHERE pubname = 'electric_publication_default';
+
+-- List tables in the publication
+SELECT schemaname, tablename
+FROM pg_publication_tables
+WHERE pubname = 'electric_publication_default';
+
+-- Check replica identity for tables
+SELECT schemaname, tablename, relreplident
+FROM pg_class
+JOIN pg_namespace ON pg_class.relnamespace = pg_namespace.oid
+WHERE relreplident = 'f';  -- 'f' means FULL
+```
+
+## Troubleshooting
+
+For common permission errors and their solutions, see the [Database permissions section](/docs/guides/troubleshooting#database-permissions-how-do-i-configure-postgresql-users-for-electric) in the main Troubleshooting guide.
+
+## Next Steps
+
+- Review the [Deployment guide](/docs/guides/deployment) for production setup
+- Learn about [Security](/docs/guides/security) best practices
+- See [Troubleshooting](/docs/guides/troubleshooting) for common issues
+- Check the [Configuration reference](/docs/api/config) for all available options
diff --git a/website/docs/guides/security.md b/website/docs/guides/security.md
@@ -39,7 +39,7 @@ This API is [public by default](#public-by-default). It should be secured in pro
 
 ### Public by default
 
-Electric connects to Postgres as a normal [database user](https://www.postgresql.org/docs/current/user-manag.html). It then exposes access to **any&nbsp;data** that its database user can access in Postgres to **any&nbsp;client** that can connect to the Electric HTTP API.
+Electric connects to Postgres as a normal [database user](https://www.postgresql.org/docs/current/user-manag.html). See the [PostgreSQL Permissions guide](/docs/guides/postgres-permissions) for details on configuring database users with the necessary permissions. Electric then exposes access to **any&nbsp;data** that its database user can access in Postgres to **any&nbsp;client** that can connect to the Electric HTTP API.
 
 You generally do _not_ want to expose public access to the contents of your database, so you **must** secure access to the Electric HTTP API.
 
diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md
@@ -113,6 +113,63 @@ If you're stopping Electric for the weekend, we recommend removing the `electric
 
 You can also control the size of the WAL with [`wal_keep_size`](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-KEEP-SIZE). On restart, Electric will detect if the WAL is past the resume point too.
 
+### Database permissions &mdash; how do I configure PostgreSQL users for Electric?
+
+Electric requires specific PostgreSQL permissions to function correctly, including the `REPLICATION` role and appropriate table permissions.
+
+##### Solution &mdash; see the PostgreSQL Permissions guide
+
+See the [PostgreSQL Permissions guide](/docs/guides/postgres-permissions) for detailed instructions on:
+- Quick start setup for development and production
+- Different permission levels (superuser, dedicated user, least-privilege)
+- How to handle `REPLICA IDENTITY FULL` requirements
+
+##### Common permission errors
+
+**Error: "insufficient privilege to create publication"**
+
+**Cause:** The user doesn't have `CREATE` privilege on the database.
+
+**Solution:** Either:
+- Grant `CREATE` privilege: `GRANT CREATE ON DATABASE mydb TO electric_user;`
+- Or use manual publication management (create the publication as a superuser and set `ELECTRIC_MANUAL_TABLE_PUBLISHING=true`)
+
+**Error: "publication not owned by the provided user"**
+
+**Cause:** The publication exists but is owned by a different user.
+
+**Solution:** Change the publication owner:
+```sql
+ALTER PUBLICATION electric_publication_default OWNER TO electric_user;
+```
+
+**Error: "table does not have its replica identity set to FULL"**
+
+**Cause:** The table hasn't been configured with `REPLICA IDENTITY FULL`.
+
+**Solution:** Set replica identity manually:
+```sql
+ALTER TABLE schema.tablename REPLICA IDENTITY FULL;
+```
+
+**Error: "permission denied for table"**
+
+**Cause:** The Electric user doesn't have `SELECT` permission on the table.
+
+**Solution:** Grant appropriate permissions:
+```sql
+GRANT SELECT ON schema.tablename TO electric_user;
+```
+
+**Error: "must be owner of table"**
+
+**Cause:** You attempted an operation that requires ownership (e.g., `ALTER TABLE ... REPLICA IDENTITY FULL` or adding the table to a publication).
+
+**Solution:** Run as the table owner (or superuser), or transfer ownership:
+```sql
+ALTER TABLE schema.tablename OWNER TO electric_user;
+```
+
 ## IPv6 support
 
 If Electric or Postgres are running behind an IPv6 network, you might have to perform additional configurations on your network.
diff --git a/website/docs/integrations/aws.md b/website/docs/integrations/aws.md
@@ -29,7 +29,7 @@ If you already run Postgres in AWS, potentially using RDS or Aurora, then it's a
 
 AWS provides Postgres hosting via RDS and Aurora. Electric works with either. You need to configure them to enable logical replication and connect with the right user.
 
-The default `wal_level` is `minimal` for RDS and `replica` for Aurora. It can be changed to `logical` by creating a [custom parameter group](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithParamGroups.html) for the RDS instance (or the Aurora DB cluster) and setting the value of the `rds.logical_replication` parameter to `1` and rebooting the instance.
+Enable logical replication by setting `rds.logical_replication=1` in your [custom parameter group](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithParamGroups.html) for the RDS instance (or the Aurora DB cluster) and rebooting the instance. This sets `wal_level` to `logical`. The PostgreSQL default `wal_level` is `replica`.
 
 The default `postgres` user has the `REPLICATION` role. If you need to add it to another user you can do so by granting the `rds_replication` role, e.g.:
 
