Connecting to Postgres

In the future, Zero will work with many different backend databases. Today only Postgres is supported. Specifically, Zero requires Postgres v15.0 or higher, and support for logical replication.

Here are some common Postgres options and what we know about their support level:

Postgres	Support Status
Postgres.app	✅
AWS RDS	✅
postgres:16.2-alpine docker image	✅
Fly.io Postgres	✅
Supabase, Neon, Render, Heroku	🤷‍♂️ Partial support with the auto-reset flag. Schema changes trigger full resync. See “Schema Changes”, below.
AWS Aurora	❌ Unsupported due to SQL differences. Let us know if you need this – we can likely figure it out.

Schema Changes

Zero uses Postgres “Event Triggers” to implement high-quality, efficient schema migration. Event Triggers typically requires superuser access to Postgres.

Hosted Postgres provides like Supabase and Neon don’t provide superuser access.

Zero can still works without Event Triggers, but for correctness, any schema change triggers a full rebuild of all server-side and client-side state. For small databases (< 1GB) this can be OK, but for bigger databases we recommend choosing a provider that grants access to Event Triggers.

To enable support for these databases, use the auto-reset flag.

Configuration

The Postgres wal_level config parameter has to be set to logical. You can check what level your pg has with this command:

Copypsql -c 'SHOW wal_level'

If it doesn’t output logical then you need to change the wal level. To do this, run:

Copypsql -c "ALTER SYSTEM SET wal_level = 'logical';"

Then restart Postgres. On most pg systems you can do this like so:

Copydata_dir=$(psql -t -A -c 'SHOW data_directory')
pg_ctl -D "$data_dir" restart

After your server restarts, show the wal_level again to ensure it has changed:

Copypsql -c 'SHOW wal_level'

SSL Mode

Some Postgres providers (notably Fly.io, so far) do not support TLS on their internal networks. You can disable attempting to use it by adding the sslmode=disable query parameter to your connection strings from zero-cache.

Supabase-Specific Notes

In order to connect to Supabase you must use the "Direct Connection" style connection string, not the pooler:

This is because Zero sets up a logical replication slot, which is only supported with a direct connection.

Additionally, you'll likely need to assign a IPv4 address to your Supabase instance. This is not supported on the free Supabase tier, and is an extra $4/mo fee.