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
AWS RDS	✅
AWS Aurora	✅ v15.6+
Google Cloud SQL	✅ See notes below
Fly.io Postgres	✅ See notes below
Postgres.app	✅
postgres:16.2-alpine docker image	✅
Supabase	✅ See notes below
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 (< 10GB) 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:

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'

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

Fly.io

Fly does not support TLS on their internal networks. If you run both zero-cache and Postgres on Fly, you need to stop zero-cache from trying to use TLS to talk to Postgres. You can do this by adding the sslmode=disable query parameter to your connection strings from zero-cache.

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 may need to assign a IPv4 address to your Supabase instance:

This will be required if you cannot use IPv6 from wherever zero-cache is running. Most cloud providers support IPv6, but some do not. For example, if you are running zero-cache in AWS, it is possible to use IPv6 but difficult.

IPv4 addresses are only supported on the Pro plan and are an extra $4/month.