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 | ✅ |
| postgres:16.2-alpine docker image | ✅ |
| AWS RDS | ✅ |
| AWS Aurora | ✅ v15.6+ |
| Google Cloud SQL | ✅ See notes below |
| Fly.io Postgres | ✅ |
| Supabase, Neon, Render, Heroku | 🤷♂️ Partial support with the auto-reset flag. See Schema Changes, below. See Supabase notes below. |
Schema Changes
Zero uses Postgres “Event Triggers” to implement high-quality, efficient schema migration. Event Triggers typically requires superuser access to Postgres.
Hosted Postgres providers 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:
psql -c 'SHOW wal_level'
If it doesn’t output logical then you need to change the wal level. To do this, run:
psql -c "ALTER SYSTEM SET wal_level = 'logical';"
Then restart Postgres. On most pg systems you can do this like so:
data_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:
psql -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.
Provider-Specific Notes
Google Cloud SQL
To use Google Cloud SQL you must manually create a PUBLICATION
and specify that publication name in the Shard Publications
option when running zero-cache.
(Google Cloud SQL does not provide sufficient permissions for zero-cache to create its default publication.)
Supabase
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.
