---
url: /docs/integrations/planetscale.md
description: How to use Electric with PlanetScale Postgres.
---

# PlanetScale

[PlanetScale](https://planetscale.com) provides managed Postgres hosting with high-availability clusters.

## Electric and PlanetScale

You can use Electric with [PlanetScale for Postgres](https://planetscale.com/docs/postgres).

> \[!Tip] Need context?
> See the [Deployment guide](/docs/guides/deployment) for more details.

## Setup Overview

PlanetScale has several unique characteristics that require special attention:

1. **Logical replication** - Not enabled by default, must configure cluster parameters
2. **Connection limits** - Default of 25 is too low for Electric's pool of 20
3. **Failover requirements** - Replication slots must support failover
4. **Table ownership** - The database user Electric connects as must own the tables it syncs

For general PostgreSQL user and permission setup, see the [PostgreSQL Permissions guide](/docs/guides/postgres-permissions).

> \[!Warning] Table ownership is critical
> On PlanetScale, you typically **cannot** transfer table ownership after the fact. Run your database migrations using the **same database user** that Electric connects as, so that user owns the tables from the start. See [Table Ownership](#table-ownership) below.

## Deploy Postgres

[Sign up to PlanetScale](https://planetscale.com) and [create a Postgres database](https://planetscale.com/docs/postgres/tutorials/planetscale-postgres-quickstart).

### Enable Logical Replication

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.

**Verify current configuration:**

```sql
SHOW wal_level; -- Should return 'logical'
```

**If not enabled, configure in PlanetScale Console:**

1. Go to your database → [**Settings → Cluster configuration → Parameters**](https://planetscale.com/docs/postgres/settings)

2. Set these parameters:
   * `wal_level` = `logical`
   * `max_replication_slots` = `10` (or higher)
   * `max_wal_senders` = `10` (or higher)
   * `max_slot_wal_keep_size` = `4096` (4GB minimum)
   * `sync_replication_slots` = `on` (for failover support)
   * `hot_standby_feedback` = `on` (for failover support)

3. Apply changes (may require cluster restart)

> \[!Important] Failover Requirement
> PlanetScale requires replication slots to support failover. Electric creates failover-enabled slots automatically, but your cluster must have `sync_replication_slots = on` configured.

### Increase Connection Limits

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)).

> \[!Warning] Connection Limit Issue
> With a low connection limit, you may have limited headroom remaining for:
>
> * Your application
> * Database migrations
> * Admin tools
> * Connection poolers (Cloudflare, etc.)
>
> **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).

To increase connection limits in PlanetScale:

1. Go to your database → [**Settings → Cluster configuration → Parameters**](https://planetscale.com/docs/postgres/settings)
2. Find `max_connections` parameter
3. Increase based on your expected concurrent work (Electric pool size + application + admin tools + buffer)

Alternatively, reduce Electric's pool size if you have limited connections:

```shell
ELECTRIC_DB_POOL_SIZE=10
```

## Table Ownership

Electric needs to **own** the tables it syncs in order to add them to publications and set `REPLICA IDENTITY FULL`. On PlanetScale, the default role cannot run `ALTER TABLE ... OWNER TO`, so you cannot transfer ownership after tables are created.

**Run your migrations as the same database user that Electric will connect as.** This way, that user owns the tables from the start and Electric can manage them automatically.

For example, if your PlanetScale connection string uses `postgres.abc123`:

```shell
# Use the same user for migrations that Electric will connect as
DATABASE_URL=postgresql://postgres.abc123:password@host:5432/db npx prisma migrate deploy
```

> \[!Tip] Already have tables owned by a different user?
> If your tables were created by a different user and you **can't** transfer ownership (common on PlanetScale), you have three options:
>
> 1. **Reassign objects in PlanetScale Console** — go to your database role's menu (three dots) and select **"Reassign objects"** to transfer table ownership from the old migration role to the Electric user
> 2. **Re-create the tables** using the correct user by running your migrations with the Electric user's credentials
> 3. **Use Manual Mode** — set `ELECTRIC_MANUAL_TABLE_PUBLISHING=true` and have an admin pre-configure the publication and replica identity. See [Manual Mode](/docs/guides/postgres-permissions#manual-mode-setup) in the PostgreSQL Permissions guide.

## Database User Setup

Follow the [PostgreSQL Permissions guide](/docs/guides/postgres-permissions) to set up the Electric user with proper permissions.

> \[!Important] PlanetScale-Specific Note
> PlanetScale's default `postgres` role includes the `REPLICATION` attribute. You can use it directly for both migrations and Electric's connection. If you create a dedicated replication role instead, make sure to also run your migrations as that role so it owns the tables.

## Connect Electric

Get your [connection string from PlanetScale](https://planetscale.com/docs/postgres/connection-strings):

> \[!Important] Connection String Requirements
>
> * Use the **direct connection** (port 5432), not PgBouncer (port 6432)
> * Include `sslmode=require` (PlanetScale requires SSL/TLS)
> * See [Table Ownership](#table-ownership) for user requirements
> * See [PlanetScale connection strings documentation](https://planetscale.com/docs/postgres/connection-strings)

### Using Electric Cloud

The simplest way to connect is via [Electric Cloud](/cloud). Use the **direct connection string** (port 5432) with `sslmode=require`. The database user must be the same one that ran your migrations (see [Table Ownership](#table-ownership)).

### Self-hosted

```shell
docker run -it \
    -e "DATABASE_URL=postgresql://postgres.abc123:password@aws-us-east-1.connect.psdb.cloud:5432/your_db?sslmode=require" \
    -p 3000:3000 \
    electricsql/electric:latest
```

> \[!Note] FOR ALL TABLES Limitation
> PlanetScale requires tables to be [added to publications individually](https://planetscale.com/docs/postgres/integrations/logical-cdc) and does not 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.

## Troubleshooting

For general PostgreSQL permission and configuration errors, see the [PostgreSQL Permissions guide](/docs/guides/postgres-permissions#troubleshooting).

### PlanetScale-Specific Issues

#### Error: "must be owner of table"

**Cause:** The database user Electric connects as does not own the table. This commonly happens when tables were created by a different user than the one Electric is using.

**Solution:** Run your migrations as the same database user that Electric connects as. See [Table Ownership](#table-ownership) for details, or use [Manual Mode](/docs/guides/postgres-permissions#manual-mode-setup) (`ELECTRIC_MANUAL_TABLE_PUBLISHING=true`) if you cannot re-run migrations.

#### Error: "too many connections"

**Cause:** Electric's connection pool plus other connections exceed PlanetScale's limit.

**Solution:** [Increase PlanetScale's max\_connections](#increase-connection-limits) to 50+ or reduce `ELECTRIC_DB_POOL_SIZE`.

#### Error: "replication slot does not support failover"

**Cause:** PlanetScale requires failover-enabled replication slots.

**Solution:** Ensure your cluster has `sync_replication_slots = on` and `hot_standby_feedback = on` configured. Electric creates failover-enabled slots automatically.

## Best Practices

1. **Plan connection capacity** - Set max\_connections to at least 3x Electric's pool size
2. **Monitor connections** - Track connection usage in PlanetScale dashboard
3. **Use direct connections** - Port 5432 (direct), not 6432 (PgBouncer) for replication
4. **Enable monitoring** - Track WAL usage and replication lag in PlanetScale

For general PostgreSQL and Electric best practices, see:

* [PostgreSQL Permissions guide](/docs/guides/postgres-permissions)
* [Deployment guide](/docs/guides/deployment)

## Additional Resources

**PlanetScale Documentation:**

* [PlanetScale for Postgres Quickstart](https://planetscale.com/docs/postgres/tutorials/planetscale-postgres-quickstart)
* [Logical Replication and CDC](https://planetscale.com/docs/postgres/integrations/logical-cdc)
* [Database Settings and Parameters](https://planetscale.com/docs/postgres/settings)
* [Connection Strings](https://planetscale.com/docs/postgres/connection-strings)
* [High Availability with CDC](https://planetscale.com/blog/postgres-ha-with-cdc)

**Electric Documentation:**

* [PostgreSQL Permissions Guide](/docs/guides/postgres-permissions)
* [Electric Deployment Guide](/docs/guides/deployment)