Building with Neon Postgres

Neon Postgres support is in beta. Some features may have known issues.

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

npm install -g cubbypro
cubby login

Create Your App

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

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:

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

cd my-neon-app
npm install

Start local development:

cubby dev

This starts a local Postgres container for development. Your app is available at http://localhost:3000.

Define Your Data Model

Edit prisma/schema.prisma to add your models:

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:

npx prisma db push

Deploy

When you’re ready, deploy to Cubby:

cubby deploy

Here’s what happens during deploy:

Verification: Pre-build checks, AI review, and PWA auto-fix
Cloud Build: Your Docker image is built in Google Cloud Build
Database provisioning: Neon Postgres database is created (or reused on redeploy)
Schema sync: prisma db push runs automatically to apply your schema
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

cubby db export --app my-neon-app

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

Create a Branch

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

cubby db branches --app my-neon-app

Take a Snapshot

cubby db snapshot --app my-neon-app

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

List Snapshots

cubby db snapshots --app my-neon-app

See the db CLI reference for full documentation of all database commands.

Prisma Schema Changes

When you change your Prisma schema and redeploy:

Update prisma/schema.prisma with your changes
Run cubby deploy
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.

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

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.

Building Database Apps - SQLite and Prisma basics
cubby db - Database CLI reference
Pricing and Billing - Plan requirements for Neon
cubby init - Create a new app

Guides

Documentation Index

​Building with Neon Postgres

​Prerequisites

​Create Your App

​Understanding the Database

​Install and Develop

​Define Your Data Model

​Deploy

​Working with Your Database

​Export Your Data

​Create a Branch

​List Branches

​Take a Snapshot

​List Snapshots

​Prisma Schema Changes

​Differences from SQLite

​Related

Building with Neon Postgres

Prerequisites

Create Your App

Understanding the Database

Install and Develop

Define Your Data Model

Deploy

Working with Your Database

Export Your Data

Create a Branch

List Branches

Take a Snapshot

List Snapshots

Prisma Schema Changes

Differences from SQLite

Related