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
Neon	✅  See notes below
Postgres.app	✅
postgres:16.2-alpine docker image	✅
Supabase	✅  See notes below
PlanetScale for Postgres	🤷‍♂️  No event triggers, see notes below
Render	🤷‍♂️  No event triggers
Heroku	🤷‍♂️  No event triggers

Event Triggers

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:

Use the "Direct Connection" option to connect zero-cache to your Supabase database.

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

Additionally, you may need to assign an IPv4 address to your Supabase instance:

Assign an IPv4 address if you have trouble connecting from residential internet.

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.

PlanetScale for Postgres

PlanetScale doesn't support event triggers yet, but they say this is something they are working on.

PlanetScale also doesn't support creating publications with the FOR ALL TABLES clause. Zero typically uses this to create an initial default publication during setup. You can workaround this by creating a publication explicitly listing the tables you want to replicate.

Neon

Neon fully supports Zero, but you should be aware of how Neon's pricing model and Zero interact.

Because Zero keeps an open connection to Postgres to replicate changes, as long as zero-cache is running, Postgres will be running and you will be charged by Neon.

For production databases that have enough usage to always be running anyway, this is fine. But for smaller applications that would otherwise not always be running, this can create a surprisingly high bill. You may want to choose a provider that charge a flat monthly rate instead.

Also some users choose Neon because they hope to use branching for previews. Note that Zero doesn't support this usage model well yet, and if not done with care, Zero can end up keeping each Neon preview branch running too 😳.

We are actively working on better preview support.