Building with Neon Postgres
Neon Postgres support is in beta. Some features may have known issues.
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:
When prompted, select:
? Select a template
Next.js + SQLite
> Next.js + Neon Postgres
Next.js
Bring Your Own Dockerfile
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
cubby.yaml:
name: my-neon-app
database:
provider: neon
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
http://localhost:3000, with database settings shaped like the Cubby runtime.
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])
}
Deploy
When you’re ready, deploy to Cubby:
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
Create a Branch
cubby db branch --app my-neon-app --name staging
List Branches
cubby db branches --app my-neon-app
Take a Snapshot
cubby db snapshot --app my-neon-app
List Snapshots
cubby db snapshots --app my-neon-app
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)orPro(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 |
