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 autoreset. See Schema Changes and provider-specific notes below. |
Schema Changes
Zero uses Postgres “Event Triggers” when possible to implement high-quality, efficient schema migration.
Some hosted Postgres providers don’t provide access to Event Triggers.
Zero still works out of the box with these providers, but for correctness, any schema change triggers a full reset 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.
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 App 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.
