Getting started with Zero and Neon

This guide demonstrates how to integrate Zero by Rocicorp with Neon Postgres. Zero allows you to build reactive, real-time applications by writing queries directly in your client code against your backend database schema. It synchronizes query results efficiently to a client-side cache, enabling instant UI updates and a local-first feel.

Zero achieves this using its custom streaming query engine, ZQL, and a stateful middleware service called zero-cache. zero-cache maintains a SQLite replica of your upstream Postgres database and serves ZQL queries to clients over WebSockets.

This guide provides a step-by-step walkthrough of setting up Zero with Neon Postgres. You will learn how to:

• Prepare your Neon Postgres database for Zero integration.
• Clone and run the Zero hello-zero quickstart application as a practical example.
• Test the integration to ensure data syncs correctly between the application, zero-cache, and Neon.

Prerequisites

Before you begin, ensure you have the following prerequisites installed and configured:

• Neon Account: Sign up for a free Neon account if you don't have one already. Neon provides a Postgres database for your Zero application.
• Node.js v20+: Node.js (version 20 or higher) is required to run the hello-zero example application and Zero tooling. Download and install it from nodejs.org.

Setting up Neon Database

Zero requires a Postgres database (version 15+) with logical replication enabled. You'll configure your Neon project accordingly.

1. Create a Neon Project: If you haven't already, create a new Neon project using pg.new.

2. Enable Logical Replication: Zero uses Postgres logical replication (wal_level = logical) to receive changes from your database.

   • Navigate to your Neon Project using the Neon Console.
   • Open the Settings menu.
   • Click on Logical Replication.
   • Click the Enable button to enable logical replication.

3. Retrieve Connection String:

   • Navigate to the Dashboard of your Neon project.
   • Click on the Connect button which opens a modal.
   • Select your database and branch, and copy the connection string with connection pooling disabled.

     important

     Make sure to turn off connection pooling in the connection string modal. This is essential for zero-cache to maintain a persistent connection to the Neon database.

     

Setting up the hello-zero example application

With your Neon database prepared, let's set up the hello-zero example application from Zero's Quickstart to connect to it.

1. Clone the hello-zero repository and install dependencies: In a terminal window, navigate to the directory where you want to clone the hello-zero repository. Run the following commands:

   git clone https://github.com/rocicorp/hello-zero.git
   cd hello-zero
   npm install

   This clones the hello-zero repository and installs the necessary Node.js dependencies.

   Using non-npm package managers?

   If you are using pnpm or bun instead of npm, you might need to explicitly allow the postinstall script for @rocicorp/zero-sqlite3, which installs native binaries. Follow the instructions on Zero's Docs to configure your package manager correctly.

2. Apply database schema/seed data: To run the example application, you need to set up the database schema and seed initial data by running the SQL migrations. The project includes the necessary SQL commands in the docker/seed.sql file.

   You can execute this file using psql (ensure it's installed locally) or the Neon SQL Editor.

   Using psql, run the following command. Replace YOUR_NEON_CONNECTION_STRING with your database connection string copied from the Neon Console:

   psql "YOUR_NEON_CONNECTION_STRING" -f docker/seed.sql

   Alternatively, you can run the SQL commands directly in the Neon SQL Editor. Copy the contents of docker/seed.sql and paste them into the SQL Editor in the Neon Console. Click Run to execute the commands.

3. Configure environment variables: Open the .env file and modify the ZERO_UPSTREAM_DB variable to point to your Neon database. It should look something like this:

   # other environment variables...
   ZERO_UPSTREAM_DB="YOUR_NEON_CONNECTION_STRING"

   Replace YOUR_NEON_CONNECTION_STRING with the actual connection string from your Neon project dashboard which you copied earlier.

4. Run the zero-cache service: Now, start the zero-cache service using the provided npm script. In your terminal, still within the hello-zero directory, run:

   npm run dev:zero-cache

   This command starts the zero-cache process. It connects to your Neon database, applies necessary permissions required for the hello-zero application, and starts the replication process. The terminal will display logs indicating the connection status and replication progress. Keep this terminal window open as it runs the zero-cache service.

   Topology

   To optimize performance, deploy your zero-cache service in close proximity to your Neon database to minimize latency in production. During local development, you might notice logs indicating a higher ping time if your zero-cache service and Neon database are not in the same region. This is expected and can be disregarded in a development environment. However, for production, it is crucial to deploy the zero-cache service in the same region as your Neon database to achieve minimal latency. For more information on deployment, refer to Deploying Zero.

5. Run the hello-zero UI: Open a new terminal window, navigate back to the hello-zero directory, and run the following command to start the frontend application:

   npm run dev:ui

   This command starts the Vite development server, making the application available at http://localhost:5173. Open this URL in your browser.

Using the demo application

You should now have the hello-zero application running in your browser. It connects to the zero-cache process running in your first terminal window, which synchronizes data with your Neon Postgres database.

1. Access the application: Open http://localhost:5173 in your browser.
2. Test functionality: Try the features described in the Zero Quickstart Overview:
   • Click Add Messages. New messages should appear instantly.
   • Open the app in a second browser tab or window. Changes made in one window should appear nearly instantaneously in the other.
   • Click Login. You'll be logged in as a random user.
   • Try Remove Messages. This should work now that you are logged in.
   • Try editing a message (pencil icon). You should only be able to edit messages created by the user you are logged in as.
   • Use the From or Contains filters.
3. Verify data in Neon (Optional): In the Neon Console, navigate to Tables and select the message table. You should see the messages you added in the application. This confirms that data is being synchronized correctly between the application, zero-cache, and Neon.

Congratulations! You have successfully set up Rocicorp Zero with Neon Postgres using the hello-zero example application. Check out Canvas, a collaborative drawing app built with Zero and Neon, for a more complex example of Zero in action.

Resources

• Zero Documentation
• Zero Quickstart
• Zero Deployment Guide
• hello-zero Repository
• Neon Documentation
• Canvas - A collaborative drawing app built with Zero and Neon