<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# Neon

## Introduction

[Neon](https://neon.com) is hosted Postgres with branching, automatic scaling, and scale to zero. The sync engine uses the same `@workos/sync-postgres` destination as any other Postgres database.

The [Neon integration guide](https://github.com/workos/sync-engine/blob/main/docs/integrations/neon.md) in the sync engine repository covers database setup, connection strings, TLS, deployment, and branching.

## Run from your own host

Follow the [Postgres guide](https://workos.com/docs/events/data-syncing/database/postgres) with your Neon connection string as `DATABASE_URL`. Both direct and pooled connections work. Use `sslmode=verify-full` and preserve the other parameters in the connection string.

See [Choose a connection](https://github.com/workos/sync-engine/blob/main/docs/integrations/neon.md#choose-a-connection) and [Run the sync from your own host](https://github.com/workos/sync-engine/blob/main/docs/integrations/neon.md#run-the-sync-from-your-own-host) for the exact setup.

## Run as a Neon Function

You can also run the sync on the Neon branch itself, without operating a separate host. The Neon Functions template uses scheduled triggers for polling, backfill, and reconciliation. A verified WorkOS webhook can trigger an immediate poll, and a token-protected status endpoint reports the mirror's health.

Follow [Run the sync as a Neon Function](https://github.com/workos/sync-engine/blob/main/docs/integrations/neon.md#run-the-sync-as-a-neon-function) for the template, environment variables, trigger configuration, and deployment commands.

## Compute and branches

A continuous listener or a tick every minute keeps Neon's compute awake, so plan for continuous compute usage while syncing. A longer polling interval can let it suspend between polls, at the cost of more lag.

A Neon branch copies the mirror, cursor, checkpoints, and writer lease. A sync on the child resumes from that cursor for the same WorkOS environment rather than starting a new backfill. See [Branches](https://github.com/workos/sync-engine/blob/main/docs/integrations/neon.md#branches) for lease timing and shared API rate limits.

Keep the `workos` schema out of Neon's Data API unless you have designed the grants and row-level security for browser access. The mirror includes raw event payloads and deleted rows; see [Query it](https://github.com/workos/sync-engine/blob/main/docs/integrations/neon.md#query-it).
