> Full Neon documentation index: https://neon.com/docs/llms.txt

# Getting started with Zero and Neon

A step-by-step guide to integrating Zero with Lakebase Postgres

This guide shows how to integrate [Zero](https://zero.rocicorp.dev/) by [Rocicorp](https://rocicorp.dev/) with Lakebase Postgres. With Zero, you build reactive, real-time applications by writing queries in your client code against your backend database schema. Zero syncs query results to a client-side cache, so the UI updates instantly and feels local-first.

Zero achieves this using its custom streaming query engine, [ZQL](https://zero.rocicorp.dev/docs/reading-data), 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.

In this guide, you'll learn how to:

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

## Prerequisites

Before you begin, make sure you have the following:

- **Neon account:** Sign up for a [Neon account](https://console.neon.tech/signup) (the Free plan works) if you don't have one already. Neon provides the 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](https://nodejs.org).

## Setting up the 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 in the [Neon Console](https://console.neon.tech).

2. **Enable logical replication:** Zero uses Postgres logical replication (`wal_level = logical`) to receive changes from your database.
   - Select your project in the [Neon Console](https://console.neon.tech/).
   - On the **Project Dashboard**, select **Settings**.
   - Select **Postgres**, then **Logical replication**.
   - Click **Enable** to enable logical replication.
     ![Neon dashboard settings with option to enable logical replication](https://neon.com/docs/guides/neon-console-settings-logical-replication.png)

3. **Retrieve the connection string:**
   - Navigate to the **Dashboard** of your Neon project.
   - Click **Connect** to open the **Connect to your branch** modal.
   - Select your database and branch, and copy the connection string with connection pooling disabled.

     **Important:** Turn off connection pooling in the **Connect to your branch** modal. `zero-cache` needs a direct connection because logical replication isn't supported through the PgBouncer pooler.

     ![Neon direct connection string modal](https://neon.com/docs/guides/neon-console-direct-connection-string.png)

## Setting up the `hello-zero` example application

With your Neon database ready, set up the `hello-zero` example application from [Zero's Quickstart](https://zero.rocicorp.dev/docs/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:

   ```bash
   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.

   **Note: 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 in [Zero's docs](https://zero.rocicorp.dev/docs/quickstart#not-npm) 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](https://neon.com/docs/get-started/query-with-neon-sql-editor).

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

   ```bash
   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:

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

   > Replace `YOUR_NEON_CONNECTION_STRING` with the direct connection string 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:

   ```bash
   npm run dev:zero-cache
   ```

   This command starts the `zero-cache` process. It connects to your Neon database, applies the [permissions](https://zero.rocicorp.dev/docs/permissions) the `hello-zero` application needs, 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.

   **Tip: Topology**

   During local development, you might see logs reporting a higher ping time if your `zero-cache` service and Neon database are in different regions. You can ignore this in development. For production, deploy the `zero-cache` service in the same region as your Neon database to minimize latency. For more information on deployment, refer to [Deploying Zero](https://zero.rocicorp.dev/docs/deployment#topology).

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:
   ```bash
   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 Lakebase 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](https://zero.rocicorp.dev/docs/quickstart#quick-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.
     ![Demo of the hello-zero app](https://neon.com/docs/guides/hello-zero-demo.gif)
   - 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 syncing between the application, `zero-cache`, and Neon.
   ![Neon messages table](https://neon.com/docs/guides/zero-message-table.png)

You have set up Rocicorp Zero with Lakebase Postgres using the `hello-zero` example application. Check out [Canvas](https://github.com/neondatabase-labs/canvas), a collaborative drawing app built with Zero and Neon, for a more complex example of Zero in action.

**Note: Schema changes**

Zero uses Postgres event triggers to handle schema migrations. Neon supports event triggers, but Zero may still perform a **full reset of the `zero-cache` and all connected client states** whenever schema changes are detected to ensure correctness.

This reset mechanism can be inefficient for larger databases (e.g., > 1GB) or applications undergoing frequent schema evolution. For smaller databases or projects with stable schemas, the impact is typically acceptable. Consider this behavior when managing schema changes for your Zero application, especially for larger projects.

## Resources

- [Zero documentation](https://zero.rocicorp.dev/docs)
- [Zero Quickstart](https://zero.rocicorp.dev/docs/quickstart)
- [Zero deployment guide](https://zero.rocicorp.dev/docs/deployment)
- [`hello-zero` repository](https://github.com/rocicorp/hello-zero)
- [Neon documentation](https://neon.com/docs)
- [Canvas - A collaborative drawing app built with Zero and Neon](https://github.com/neondatabase-labs/canvas)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/guides/zero"}` to https://feedback.neon.tech/ (no auth required).