Neon + PowerSync

This guide shows you how to set up PowerSync with Neon and run a React notes demo app. The app reads and writes a local SQLite database, so it responds instantly and keeps working without a network connection. The demo app is a fork of Neon’s Data API and Neon Auth demo with PowerSync added.

Comparing PowerSync with Neon Realtime? See PowerSync vs Neon Realtime.

Before you start, make sure you have:

A Neon account
A PowerSync Cloud account
pnpm installed

Architecture

Diagram of the PowerSync Service syncing data from Neon Postgres to SQLite in the app, and the app uploading writes to Neon through the Neon TypeScript SDK — Neon + PowerSync architecture

The PowerSync Service replicates data from Neon Postgres and syncs it to each client’s SQLite database, based on your Sync Streams. When the app writes to SQLite, the PowerSync SDK also adds the change to an upload queue. While the device is online, the SDK calls the app’s uploadData() function, which sends queued changes to Neon through the Neon Data API. Neon Auth handles sign-in. The Data API and PowerSync both accept the JWTs that Neon Auth issues. For more on how PowerSync works, see the Architecture Overview.

Overview

Configure Neon

Create a Neon project with Neon Auth and the Data API
Enable logical replication
Create the demo database schema
Create the PowerSync database user and publication

Configure PowerSync

Connect PowerSync to Neon
Configure Neon Auth
Configure Sync Streams

Run the Demo App

Configure and run the notes demo app, then test sync.

Configure Neon

Create a Neon Project

Create a project with Neon Auth, Neon’s managed Better Auth service, and the Data API.

Web UI
CLI

In the Neon Console, create a project.
Enable Better Auth.
Enable the Data API under Postgres database > Data API. Keep Use Neon Auth selected and select Grant public schema access, which is off by default.

Install the Neon CLI and log in:
npm i -g neon@latest neon login
Create a project. The output includes the project ID, which the following commands use as <project-id>:
neon projects create --name powersync-neon-notes --region-id aws-us-east-2

Enable Neon Auth and the Data API:

neon neon-auth enable --project-id <project-id>
neon data-api create --project-id <project-id> --database neondb --auth-provider neon_auth --add-default-grants

The demo app uploads writes through the Data API as the authenticated role. Grant public schema access (--add-default-grants in the CLI) gives this role read and write access to tables in the public schema, including tables you create later. Without these grants, the demo app’s uploads fail.

Enable Logical Replication

PowerSync uses Postgres logical replication to read changes from your database. Enabling logical replication can’t be undone. It also restarts your project’s computes, which drops active connections.

Web UI
CLI

In the Neon Console, go to Settings > Postgres and enable Logical Replication.

Run the following Neon CLI command, replacing <project-id> with your Neon project ID:

neon projects update <project-id> --enable-logical-replication --yes

While PowerSync is connected, its replication connection keeps your Neon compute active, so the compute doesn’t scale to zero. This uses compute hours continuously, which counts toward your Neon plan’s limits.

Create the Demo Database Schema

The demo app uses Drizzle migrations to create its tables and Row Level Security (RLS) policies.

Clone the demo app and install its dependencies:

git clone https://github.com/powersync-ja/powersync-js.git
cd powersync-js/demos/react-neon-tanstack-query-notes
pnpm install

Get a direct connection string:
- Web UI: In the Neon Console, click Connect, turn off Connection pooling, and copy the connection string.
- CLI: Run neon connection-string --project-id <project-id>. It returns a direct connection string by default.

Create a .env file in the demo directory and add the connection string:

DATABASE_URL=postgresql://neondb_owner:<password>@ep-cool-darkness-123456.c-2.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require

Run the migration:
pnpm db:migrate

The migration creates these tables:

CREATE TABLE "notes" (
  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
  "owner_id" text DEFAULT auth.user_id() NOT NULL,
  "title" text DEFAULT 'untitled note' NOT NULL,
  "created_at" timestamp with time zone DEFAULT now(),
  "updated_at" timestamp with time zone DEFAULT now(),
  "shared" boolean DEFAULT false
);

CREATE TABLE "paragraphs" (
  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
  "note_id" uuid REFERENCES notes(id),
  "content" text NOT NULL,
  "created_at" timestamp with time zone DEFAULT now()
);

The RLS policies let each signed-in user read and write their own notes and paragraphs, and read shared notes and their paragraphs.

Create a PowerSync Database User

Run the following SQL in the Neon Console under Postgres database > SQL Editor, or with psql "$(neon connection-string --project-id <project-id>)". The role needs BYPASSRLS so that PowerSync can replicate every row of the RLS-protected demo tables. Your Sync Streams then decide which rows each user receives.

-- Create a role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

To restrict read access to specific tables, explicitly list allowed tables for both the SELECT privilege, and for the publication mentioned in the next step (as well as for any other publications that may exist).

Create the Postgres Publication

Run the following SQL in the SQL Editor or with psql:

-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

Configure PowerSync

Create a PowerSync Cloud Instance

Web UI
CLI

When creating a project in the PowerSync Dashboard, Development and Production instances of the PowerSync Service will be created by default. Select the instance you want to configure.If you need to create a new instance, follow the steps below.

In the dashboard, select your project and open the instance selection dropdown. Click Add Instance.

Give your instance a name, such as “Production”.
[Optional] You can change the default cloud region. You can’t change the region after you create the instance. See Regions for details.
Click Create Instance.

Run these commands in the demo directory.Install the PowerSync CLI (requires Node.js/npm), then log in and scaffold the config directory:

npm install -g powersync
powersync login
powersync init cloud

This creates a powersync/ directory with service.yaml (instance name, region, connection, auth) and sync-config.yaml (Sync Config). Edit powersync/service.yaml to set your instance name and region.Then create the instance and link the directory to it:

powersync link cloud --create --project-id=<project-id>

Find your project ID in the PowerSync Dashboard URL, or run powersync fetch instances after logging in.

Connect PowerSync to Neon

Web UI
CLI

In the Neon Console, click Connect, turn off Connection pooling, and copy the connection string.
In the PowerSync Dashboard, select your project and instance and go to the Database Connection view.
Select the Postgres tab.
Paste the connection string into the URI field. PowerSync fills in the other connection fields from the URI.
Change Username and Password to the powersync_role and password you created in Create a PowerSync Database User.
Keep SSL Mode set to verify-full. PowerSync trusts Neon’s certificate by default, so you don’t need to add a server certificate.
Click Test Connection and fix any errors.
Click Save Connection.

PowerSync now creates an isolated cloud environment for your instance. This typically takes a minute or two.

Add the connection to powersync/service.yaml. Use the host from neon connection-string --project-id <project-id>, with powersync_role as the user:

replication:
  connections:
    - type: postgresql
      uri: postgresql://powersync_role@ep-cool-darkness-123456.c-2.us-east-2.aws.neon.tech/neondb
      password:
        secret: !env POWERSYNC_DATABASE_PASSWORD

Configure Neon Auth

The demo app sends PowerSync the JWT that Neon Auth issues for the signed-in user. To verify these JWTs, PowerSync needs two values from Neon:

JWKS URL: The public keys that Neon Auth publishes as a JSON Web Key Set (JWKS), for example https://ep-cool-darkness-123456.neonauth.c-2.us-east-2.aws.neon.tech/neondb/auth/.well-known/jwks.json.
JWT audience: The origin of your Neon Auth URL, which is the URL without the path and without a trailing /, for example https://ep-cool-darkness-123456.neonauth.c-2.us-east-2.aws.neon.tech. PowerSync rejects a token if its aud value doesn’t match exactly.

You also enable development tokens, which you use to test your Sync Streams at the end of this guide.

Web UI
CLI

Find the Auth URL and JWKS URL in the Neon Console under Settings > Better Auth. Then, in the PowerSync Dashboard, go to the Client Auth view and set the following fields:

Development tokens: Enable this setting.
JWKS URI: Enter the JWKS URL from Neon.
JWT Audience: Enter the origin of the Auth URL from Neon.

Then click Save and Deploy.

neon neon-auth status --project-id <project-id> prints the Auth URL as base_url and the JWKS URL as jwks_url. Add a client_auth section to powersync/service.yaml:

client_auth:
  jwks_uri: https://ep-cool-darkness-123456.neonauth.c-2.us-east-2.aws.neon.tech/neondb/auth/.well-known/jwks.json
  additional_audiences:
    - https://ep-cool-darkness-123456.neonauth.c-2.us-east-2.aws.neon.tech
  allow_temporary_tokens: true

You deploy this configuration together with your Sync Config in the next step.

Configure Sync Streams

Sync Streams define which data syncs to which users’ devices. In the demo app, each user syncs their own notes and paragraphs, plus all shared notes and their paragraphs. Use the following Sync Config:

config:
  edition: 3
streams:
  user_notes:
    auto_subscribe: true
    # Sync notes and paragraphs belonging to the authenticated user
    queries:
      - SELECT * FROM notes WHERE owner_id = auth.user_id()
      - SELECT paragraphs.* FROM paragraphs
          INNER JOIN notes ON notes.id = paragraphs.note_id
          WHERE notes.owner_id = auth.user_id()
  shared_notes:
    auto_subscribe: true
    # Sync all shared notes to all users (not recommended for production)
    queries:
      - SELECT * FROM notes WHERE shared = TRUE
      - SELECT paragraphs.* FROM paragraphs
          INNER JOIN notes ON notes.id = paragraphs.note_id
          WHERE notes.shared = TRUE

Web UI
CLI

In the PowerSync Dashboard, go to the Sync Streams view.
Replace the contents of the editor with the Sync Config above.
Click Validate and fix any errors.
Click Deploy.

Replace the contents of powersync/sync-config.yaml with the Sync Config above. Then deploy the full configuration, which includes the database connection, client auth, and Sync Config:

export POWERSYNC_DATABASE_PASSWORD=<powersync_role password>
powersync deploy

Run the Demo App

Configure Environment Variables

Add the following variables to the .env file in the demo directory:

# Neon Console > Postgres database > Data API > API URL
VITE_NEON_DATA_API_URL=https://ep-cool-darkness-123456.apirest.c-2.us-east-2.aws.neon.tech/neondb/rest/v1

# Neon Console > Settings > Better Auth > Auth URL
VITE_NEON_AUTH_URL=https://ep-cool-darkness-123456.neonauth.c-2.us-east-2.aws.neon.tech/neondb/auth

# PowerSync Dashboard > Connect > instance URL
VITE_POWERSYNC_URL=https://your-instance-id.powersync.journeyapps.com

If you use the CLI, neon data-api get --project-id <project-id> --database neondb prints the Data API URL, and neon neon-auth status --project-id <project-id> prints the Auth URL as base_url. Your PowerSync instance URL is https://<instance-id>.powersync.journeyapps.com, where <instance-id> is the instance_id value in powersync/cli.yaml.

Start the App

Start the development server:

pnpm dev

Open http://localhost:5173 and sign up. Neon Auth accepts requests from localhost while Allow Localhost is on, which is the default. If you deploy the app, add its domain in the Neon Console under Settings > Better Auth > Domains. The notes list is empty at first. Create a note, then disconnect your device from the network (for example, turn off Wi-Fi) and edit the note. When you reconnect, the SDK uploads the queued changes, and they appear in the notes and paragraphs tables in Neon.

Demo app showing a list of two notes for the signed-in user — The demo app after creating two notes

If a note disappears shortly after you create it, the Data API rejected the upload with a permission error (42501), and the demo app discarded the change. To grant access to the demo tables, run GRANT SELECT, INSERT, UPDATE, DELETE ON notes, paragraphs TO authenticated; in the SQL Editor.

Test Your Sync Streams (Optional)

To see which data syncs to a specific user, generate a development token for a user who signed up in the demo app, and open it in the Sync Diagnostics Client. Use the user’s ID as the token subject. This ID is the owner_id value of the user’s notes.

Web UI
CLI

In the PowerSync Dashboard, go to the Sync Test view. Enter the user ID as the token subject, then click Generate token and Launch Sync Diagnostics Client.

In the demo directory, run the following command and paste the token into the Sync Diagnostics Client:

powersync generate token --subject=<user-id>

If you run into problems, ask us on Discord.

Get Started

Configuration Details

Sync Streams

Client SDKs

Handling Writes

Maintenance & Ops

Integrations

Tools

Resources

Architecture

Overview

Configure Neon

Create a Neon Project

Enable Logical Replication

Create the Demo Database Schema

Create a PowerSync Database User

Create the Postgres Publication

Configure PowerSync

Create a PowerSync Cloud Instance

Connect PowerSync to Neon

Configure Neon Auth

Configure Sync Streams

Run the Demo App

Configure Environment Variables

Start the App

Test Your Sync Streams (Optional)

​Architecture

​Overview

​Configure Neon

​Create a Neon Project

​Enable Logical Replication

​Create the Demo Database Schema

​Create a PowerSync Database User

​Create the Postgres Publication

​Configure PowerSync

​Create a PowerSync Cloud Instance

​Connect PowerSync to Neon

​Configure Neon Auth

​Configure Sync Streams

​Run the Demo App

​Configure Environment Variables

​Start the App

​Test Your Sync Streams (Optional)

Architecture

Overview

Configure Neon

Create a Neon Project

Enable Logical Replication

Create the Demo Database Schema

Create a PowerSync Database User

Create the Postgres Publication

Configure PowerSync

Create a PowerSync Cloud Instance

Connect PowerSync to Neon

Configure Neon Auth

Configure Sync Streams

Run the Demo App

Configure Environment Variables

Start the App

Test Your Sync Streams (Optional)