---
title: "Neon"
description: "Use Neon for MainSDK data and backups - serverless Postgres per region, main.yaml, point-in-time restore, restore drills on branches and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/neon"
updated: "2026-10-28"
---

# Neon

> Use Neon for MainSDK data and backups - serverless Postgres per region, main.yaml, point-in-time restore, restore drills on branches and swapping.

Canonical: https://mainsdk.dev/docs/integrations/neon · Updated: 2026-10-28

Neon is serverless Postgres, and a driver behind [`db`](https://mainsdk.dev/docs/interfaces/db) and [`backup`](https://mainsdk.dev/docs/interfaces/backup). Your records live in a Neon project per region, and Neon's point-in-time restore and branches give `backup` a fast way to run restore drills. Pick Neon for a Next.js app on Vercel, or whenever you want managed Postgres without running servers.

## Interfaces it serves

### Data and records (`db`)

- Status: Building for 0.3 · ships as a stable API
- Driver: `neon` (Neon)
- Docs: https://mainsdk.dev/docs/interfaces/db.md

```yaml
db:
  driver: neon
```

Swap to another provider: `postgres`, `supabase`, `sqlite`.

### Backups and restore drills (`backup`)

- Status: Building for 1.2 · ships as a beta API
- Driver: `neon-pitr` (Neon point-in-time recovery)
- Docs: https://mainsdk.dev/docs/interfaces/backup.md

```yaml
backup:
  driver: neon-pitr
```

Swap to another provider: `local`, `supabase-pitr`, `pgbackrest`, `aws-backup`, `object-lock`.

## Before you start

1. Create a Neon project for each region your users are in, and check that Neon offers a region for each store you need.
2. Copy each project's connection string and store it in your secrets manager.
3. Review the project's history retention: it sets how far back point-in-time restore can go.

## Configure

```yaml title="main.yaml"
db:
  driver: neon
  regions:
    us: secret:DB_US        # suggested name; Neon connection string, US
    eu: secret:DB_EU        # suggested name; Neon connection string, EU
    in: secret:DB_IN        # suggested name; Neon connection string, India
backup:
  rpo: 15m
  rto: 1h
  keep: 35d
  drill: { every: 30d, to: scratch }
```

Point-in-time recovery comes from the Neon `db` driver's capability profile; there is no separate backup driver to set.

## Use it

```ts title="app/api/orders/route.ts"
import { auth, db } from "mainsdk";

export async function GET(req: Request) {
  const session = await auth.require(req);
  return Response.json(await db.orders.for(session.user).list({ limit: 20 }));
}
```

```ts title="scripts/drill.ts"
import { runDrill } from "mainsdk/backup";

const result = await runDrill({ driver, declared, app: "my-app", at: new Date(), to: "scratch" });   // restores into scratch, never production
```

`mainsdk drill restore --to scratch` runs the same drill from the command line and signs the evidence.

## Local development and testing

Use [SQLite](https://mainsdk.dev/docs/integrations/sqlite) or a Neon development branch locally. `createTestApp()` from `@mainsdk/testing` runs `db` on its in-memory fake, and `chaos.on("db", { outage: true })` simulates an outage. Run `mainsdk drill restore` in CI to test restores against Neon itself.

## What MainSDK adds on top

- Owner scope, region routing, field labels and idempotent writes, as on every `db` driver.
- `mainsdk check` reads Neon's restore window and fails with the gap when it cannot meet your RPO.
- Restore drills into a Neon branch, timed against your RTO and signed as evidence.

See [Data and records](https://mainsdk.dev/docs/interfaces/db) and [Backups and restore drills](https://mainsdk.dev/docs/interfaces/backup).

## Limits and notes

- The `neon` driver comes with the db spec (phase 1); `neon-pitr` comes with the backup-restore-evidence spec (phase 3, milestone 1.2).
- MainSDK never runs or stores backups; Neon does.

## Swap to or from it

```yaml title="main.yaml"
db:
  driver: neon   # was postgres
```

> **Warning:** Rows don't move by themselves; MainSDK runs the move as a guided migration job with a rollback. Your old provider's backups don't move either, so run a drill on Neon before you rely on it.

## FAQ

**Is Neon just Postgres?** Yes. Your Postgres schema and Prisma or Drizzle migrations work unchanged.

**Can a drill touch my production branch?** No. Drills restore only into a new branch or scratch database.

## Next

- [Data and records](https://mainsdk.dev/docs/interfaces/db) and [Backups and restore drills](https://mainsdk.dev/docs/interfaces/backup)
- [Postgres](https://mainsdk.dev/docs/integrations/postgres), [Supabase](https://mainsdk.dev/docs/integrations/supabase) and [Vercel](https://mainsdk.dev/docs/integrations/vercel)