> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubby.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Building with Neon Postgres

> Deploy a Next.js app with Neon Postgres database on Cubby

# Building with Neon Postgres

<Info>
  Neon Postgres support is in beta. Some features may have known issues.
</Info>

This tutorial walks you through creating and deploying a Next.js app with a Neon Postgres database on Cubby.

**Time:** \~15 minutes

## Prerequisites

* Cubby CLI installed and logged in (`cubby login`)
* Node.js 18 or later
* A **Builder** ($9.99/mo) or **Pro** ($19.99/mo) plan -- Neon Postgres requires Builder or higher

```bash theme={null}
npm install -g cubbypro
cubby login
```

## Create Your App

Run `cubby init` and select the **Next.js + Neon Postgres** template:

```bash theme={null}
cubby init my-neon-app
```

When prompted, select:

```
? Select a template
  Next.js + SQLite
> Next.js + Neon Postgres
  Next.js
  Bring Your Own Dockerfile
```

This selects the `nextjs-neon` template and creates a project with:

```
my-neon-app/
├── app/
│   ├── layout.tsx         # Root layout with manifest link
│   └── page.tsx           # Home page
├── prisma/
│   └── schema.prisma      # Postgres Prisma schema
├── lib/
│   └── db.ts              # Prisma client singleton
├── cubby.yaml             # App config with database: { provider: neon }
├── CUBBY.md               # Platform instructions for AI tools
├── CLAUDE.md              # Claude Code project instructions
└── package.json           # Dependencies including Prisma
```

The key difference from the SQLite template is `cubby.yaml`:

```yaml theme={null}
name: my-neon-app
database:
  provider: neon
```

This tells Cubby to provision a Neon Postgres database instead of SQLite.

## Understanding the Database

When you deploy with `database: { provider: neon }`, Cubby provisions a Neon Postgres database automatically:

* **One Neon project per user**, with individual databases per app
* **`DATABASE_URL`** and **`DIRECT_URL`** are injected into your app's environment
* **Prisma** uses the Neon serverless driver (`@prisma/adapter-neon`) for WebSocket connections

You don't need a Neon account or API key -- Cubby manages the infrastructure.

## Install and Develop

```bash theme={null}
cd my-neon-app
npm install
```

Start local development:

```bash theme={null}
cubby dev
```

This starts a local development environment for the Neon template. Your app is available at `http://localhost:3000`, with database settings shaped like the Cubby runtime.

## Define Your Data Model

Edit `prisma/schema.prisma` to add your models:

```prisma theme={null}
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Note {
  id        String   @id @default(cuid())
  title     String
  content   String?
  userId    String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([userId])
}
```

Then sync your local database:

```bash theme={null}
npx prisma db push
```

## Deploy

When you're ready, deploy to Cubby:

```bash theme={null}
cubby deploy
```

Here's what happens during deploy:

1. **Verification**: Pre-build checks, AI review, and PWA auto-fix
2. **Cloud Build**: Your Docker image is built in Google Cloud Build
3. **Database provisioning**: Neon Postgres database is created (or reused on redeploy)
4. **Schema sync**: `prisma db push` runs automatically to apply your schema
5. **Container start**: Your app goes live with `DATABASE_URL` injected

When complete:

```
Your app is live at:
https://my-neon-app--yourname.cubby.pro
```

## Working with Your Database

Cubby provides database management commands via `cubby db`:

### Export Your Data

```bash theme={null}
cubby db export --app my-neon-app
```

Downloads a SQL dump of your database for backup or migration.

### Create a Branch

```bash theme={null}
cubby db branch --app my-neon-app --name staging
```

Creates a Neon branch -- a copy-on-write clone of your database. Useful for testing schema changes without affecting production data.

### List Branches

```bash theme={null}
cubby db branches --app my-neon-app
```

### Take a Snapshot

```bash theme={null}
cubby db snapshot --app my-neon-app
```

Creates a point-in-time snapshot of your database.

### List Snapshots

```bash theme={null}
cubby db snapshots --app my-neon-app
```

See the [db CLI reference](/cli-reference/db) for full documentation of all database commands.

## Prisma Schema Changes

When you change your Prisma schema and redeploy:

1. Update `prisma/schema.prisma` with your changes
2. Run `cubby deploy`
3. Cubby runs `prisma db push` automatically during deploy

`prisma db push` applies schema changes non-destructively. It creates new tables and columns but does not drop existing data. For destructive changes (removing columns, renaming tables), you'll need to handle the migration manually.

<Warning>
  `prisma db push` can cause data loss if you remove or rename fields. Test schema changes on a branch first using `cubby db branch`.
</Warning>

## Differences from SQLite

|                       | SQLite                     | Neon Postgres                                 |
| --------------------- | -------------------------- | --------------------------------------------- |
| **Tier**              | All tiers (including free) | Builder ($9.99/mo) or Pro ($19.99/mo)         |
| **Concurrent writes** | Single writer              | Multiple connections                          |
| **Data location**     | Inside container (PVC)     | External (Neon cloud)                         |
| **Branching**         | Not available              | `cubby db branch`                             |
| **Snapshots**         | Not available              | `cubby db snapshot`                           |
| **Best for**          | Simple apps, prototypes    | Complex queries, shared data, production apps |

**Choose SQLite** when your app is simple, single-user, or you want to stay on the free tier. SQLite is fast, requires no external services, and works on all plans.

**Choose Neon Postgres** when you need concurrent writes from multiple users, complex queries with joins, or database features like branching and snapshots. Neon databases persist independently of your container, so data survives even if the container is replaced.

## Related

* [Building Database Apps](/tutorials/database-apps) - SQLite and Prisma basics
* [`cubby db`](/cli-reference/db) - Database CLI reference
* [Pricing and Billing](/platform/billing) - Plan requirements for Neon
* [`cubby init`](/cli-reference/init) - Create a new app