Skip to content

Commit 7b3e50c

Browse files
KyleAMathewsclaude
KyleAMathews
and
claude
authored
docs: Add PlanetScale Postgres integration guide (#3279)
## Summary Adds a comprehensive integration guide for PlanetScale Postgres, addressing common setup issues reported by users in the community. ## Problem Solved A user recently shared their struggles getting Electric working with PlanetScale: - Had to increase max_connections from 25 to 50 (Electric needs 20 by default) - Couldn't use standard PlanetScale roles - needed custom role with REPLICATION - Electric couldn't create snapshots without table ownership - Required workarounds that weren't documented This guide provides clear, step-by-step solutions to all these issues. ## What's Included ### Core Setup Topics - **Connection Limits**: Clear warning that PlanetScale's 25 default is too low, recommend 50+ - **Replication Role**: How to create custom role with REPLICATION privilege - **Table Ownership**: Why Electric needs it and how to transfer ownership - **Manual Publication**: Alternative approach for restricted permission environments ### Additional Content - Failover configuration (PlanetScale-specific requirement) - SSL/TLS connection requirements - Troubleshooting section with common errors - Best practices for production use - Links to relevant PlanetScale and Electric documentation ## Structure Follows the same pattern as other integration guides (Neon, Supabase, Crunchy): - Overview of requirements - Step-by-step setup - Connection examples - Troubleshooting - Best practices ## References - PlanetScale logical replication docs - Zero/Rocicorp's PlanetScale notes (publication limitations) - User-reported issues from community 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <[email protected]>
1 parent 980218e commit 7b3e50c

File tree

2 files changed

+148
-0
lines changed

2 files changed

+148
-0
lines changed

‎website/.vitepress/config.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -292,6 +292,7 @@ export default defineConfig({
292292
{ text: 'GCP', link: '/docs/integrations/gcp' },
293293
{ text: 'Neon', link: '/docs/integrations/neon' },
294294
{ text: 'Netlify', link: '/docs/integrations/netlify' },
295+
{ text: 'PlanetScale', link: '/docs/integrations/planetscale' },
295296
{ text: 'Render', link: '/docs/integrations/render' },
296297
{ text: 'Supabase', link: '/docs/integrations/supabase' },
297298
],

‎website/docs/integrations/planetscale.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
outline: deep
3+
title: PlanetScale - Integrations
4+
description: >-
5+
How to use Electric with PlanetScale Postgres.
6+
image: /img/integrations/electric-planetscale.jpg
7+
---
8+
9+
# PlanetScale
10+
11+
[PlanetScale](https://planetscale.com) provides managed Postgres hosting with high-availability clusters.
12+
13+
## Electric and PlanetScale
14+
15+
You can use Electric with [PlanetScale for Postgres](https://planetscale.com/docs/postgres).
16+
17+
> [!Tip] Need context?
18+
> See the [Deployment guide](/docs/guides/deployment) for more details.
19+
20+
## Setup Overview
21+
22+
PlanetScale has several unique characteristics that require special attention:
23+
24+
1. **Logical replication** - Not enabled by default, must configure cluster parameters
25+
2. **Connection limits** - Default of 25 is too low for Electric's pool of 20
26+
3. **Failover requirements** - Replication slots must support failover
27+
28+
For general PostgreSQL user and permission setup, see the [PostgreSQL Permissions guide](/docs/guides/postgres-permissions).
29+
30+
## Deploy Postgres
31+
32+
[Sign up to PlanetScale](https://planetscale.com) and [create a Postgres database](https://planetscale.com/docs/postgres/tutorials/planetscale-postgres-quickstart).
33+
34+
### Enable Logical Replication
35+
36+
Logical replication **may not be enabled** on your cluster. Verify and configure as needed. See the [PlanetScale Logical Replication guide](https://planetscale.com/docs/postgres/integrations/logical-cdc) for detailed background.
37+
38+
**Verify current configuration:**
39+
```sql
40+
SHOW wal_level; -- Should return 'logical'
41+
```
42+
43+
**If not enabled, configure in PlanetScale Console:**
44+
1. Go to your database → [**Settings → Cluster configuration → Parameters**](https://planetscale.com/docs/postgres/settings)
45+
2. Set these parameters:
46+
- `wal_level` = `logical`
47+
- `max_replication_slots` = `10` (or higher)
48+
- `max_wal_senders` = `10` (or higher)
49+
- `max_slot_wal_keep_size` = `4096` (4GB minimum)
50+
- `sync_replication_slots` = `on` (for failover support)
51+
- `hot_standby_feedback` = `on` (for failover support)
52+
53+
3. Apply changes (may require cluster restart)
54+
55+
> [!Important] Failover Requirement
56+
> PlanetScale requires replication slots to support failover. Electric creates failover-enabled slots automatically, but your cluster must have `sync_replication_slots = on` configured.
57+
58+
### Increase Connection Limits
59+
60+
Small PlanetScale clusters may start with a low `max_connections` limit. Electric uses **20 connections** for its connection pool by default (configurable via [`ELECTRIC_DB_POOL_SIZE`](/docs/api/config#electric-db-pool-size)).
61+
62+
> [!Warning] Connection Limit Issue
63+
> With a low connection limit, you may have limited headroom remaining for:
64+
> - Your application
65+
> - Database migrations
66+
> - Admin tools
67+
> - Connection poolers (Cloudflare, etc.)
68+
>
69+
> **Recommendation:** Plan connection capacity for your expected concurrent database work. A good rule of thumb is **≥ 3× Electric's pool size** to ensure adequate headroom (e.g., if Electric uses 20 connections, set `max_connections` to at least 60).
70+
71+
To increase connection limits in PlanetScale:
72+
1. Go to your database → [**Settings → Cluster configuration → Parameters**](https://planetscale.com/docs/postgres/settings)
73+
2. Find `max_connections` parameter
74+
3. Increase based on your expected concurrent work (Electric pool size + application + admin tools + buffer)
75+
76+
Alternatively, reduce Electric's pool size if you have limited connections:
77+
```shell
78+
ELECTRIC_DB_POOL_SIZE=10
79+
```
80+
81+
## Create Replication User
82+
83+
Follow the [PostgreSQL Permissions guide](/docs/guides/postgres-permissions) to set up the Electric user with proper permissions.
84+
85+
> [!Important] PlanetScale-Specific Note
86+
> PlanetScale's default `postgres` role includes the `REPLICATION` attribute. You can use it directly, or create a dedicated replication role for least-privilege access per your organization's security policy.
87+
88+
## Connect Electric
89+
90+
Get your [connection string from PlanetScale](https://planetscale.com/docs/postgres/connection-strings):
91+
92+
> [!Important] Connection String Requirements
93+
> - Use the **direct connection** (port 5432), not PgBouncer (port 6432)
94+
> - Include `sslmode=require` (PlanetScale requires SSL/TLS)
95+
> - See [PlanetScale connection strings documentation](https://planetscale.com/docs/postgres/connection-strings)
96+
97+
```shell
98+
docker run -it \
99+
-e "DATABASE_URL=postgresql://electric:[email protected]:5432/your_db?sslmode=require" \
100+
-p 3000:3000 \
101+
electricsql/electric:latest
102+
```
103+
104+
> [!Note] FOR ALL TABLES Limitation
105+
> Some sources suggest PlanetScale doesn't support `CREATE PUBLICATION ... FOR ALL TABLES`. If you encounter this issue, explicitly list tables in your publication. See [Manual Publication Management](/docs/guides/postgres-permissions#manual-configuration-steps) in the PostgreSQL Permissions guide.
106+
107+
## Troubleshooting
108+
109+
For general PostgreSQL permission and configuration errors, see the [PostgreSQL Permissions guide](/docs/guides/postgres-permissions#troubleshooting).
110+
111+
### PlanetScale-Specific Issues
112+
113+
#### Error: "too many connections"
114+
115+
**Cause:** Electric's connection pool plus other connections exceed PlanetScale's limit.
116+
117+
**Solution:** [Increase PlanetScale's max_connections](#increase-connection-limits) to 50+ or reduce `ELECTRIC_DB_POOL_SIZE`.
118+
119+
#### Error: "replication slot does not support failover"
120+
121+
**Cause:** PlanetScale requires failover-enabled replication slots.
122+
123+
**Solution:** Ensure your cluster has `sync_replication_slots = on` and `hot_standby_feedback = on` configured. Electric creates failover-enabled slots automatically.
124+
125+
## Best Practices
126+
127+
1. **Plan connection capacity** - Set max_connections to at least 3x Electric's pool size
128+
2. **Monitor connections** - Track connection usage in PlanetScale dashboard
129+
3. **Use direct connections** - Port 5432 (direct), not 6432 (PgBouncer) for replication
130+
4. **Enable monitoring** - Track WAL usage and replication lag in PlanetScale
131+
132+
For general PostgreSQL and Electric best practices, see:
133+
- [PostgreSQL Permissions guide](/docs/guides/postgres-permissions)
134+
- [Deployment guide](/docs/guides/deployment)
135+
136+
## Additional Resources
137+
138+
**PlanetScale Documentation:**
139+
- [PlanetScale for Postgres Quickstart](https://planetscale.com/docs/postgres/tutorials/planetscale-postgres-quickstart)
140+
- [Logical Replication and CDC](https://planetscale.com/docs/postgres/integrations/logical-cdc)
141+
- [Database Settings and Parameters](https://planetscale.com/docs/postgres/settings)
142+
- [Connection Strings](https://planetscale.com/docs/postgres/connection-strings)
143+
- [High Availability with CDC](https://planetscale.com/blog/postgres-ha-with-cdc)
144+
145+
**Electric Documentation:**
146+
- [PostgreSQL Permissions Guide](/docs/guides/postgres-permissions)
147+
- [Electric Deployment Guide](/docs/guides/deployment)

0 commit comments

Comments
 (0)