Database Overview
Prisma v7 + PostgreSQL β the data layer powering every Nebutra application.
Nebutra uses Prisma v7 as the ORM and PostgreSQL as the database engine. The stack is designed for multi-tenant SaaS: shared schemas, row-level security, pgvector for AI embeddings, and provider flexibility (Neon or Supabase).
Architecture
βββββββββββββββββββββββββββββββββββββββ
β Application Code β
β (Next.js Server Components, API) β
ββββββββββββββββββ¬βββββββββββββββββββββ
β import { db } from "@nebutra/db"
ββββββββββββββββββΌβββββββββββββββββββββ
β Prisma v7 Client β
β (type-safe query builder) β
ββββββββββββββββββ¬βββββββββββββββββββββ
β PostgreSQL wire protocol
ββββββββββββββββββΌβββββββββββββββββββββ
β Connection Pooler β
β PgBouncer (Neon) / Supavisor β
β (Supabase) β prevents conn. exhaustβ
ββββββββββββββββββ¬βββββββββββββββββββββ
β
ββββββββββββββββββΌβββββββββββββββββββββ
β PostgreSQL Database β
β pgvector Β· RLS Β· multi-schema β
βββββββββββββββββββββββββββββββββββββββAll application code imports the pre-configured db singleton from @nebutra/db. Direct Prisma imports are not used in application code.
Schema layout
The Prisma schema is split across four PostgreSQL schemas, each representing a product domain:
| PostgreSQL schema | Purpose | Key models |
|---|---|---|
public | Core SaaS platform | Organization, User, Subscription, AuditLog, ApiKey |
ecommerce | E-commerce features | Product, Order, Cart, Payment, Fulfillment |
recsys | Recommendation system | Embedding, Interaction, Recommendation, FeatureVector |
web3 | Blockchain / wallet features | Wallet, Token, Transaction, SmartContract |
The full schema lives at packages/platform/db/prisma/schema.prisma (~1,400 lines).
Key models
| Model | Schema | Description |
|---|---|---|
Organization | public | A tenant β the top-level billing and access boundary |
User | public | An authenticated identity; belongs to one or more organizations |
Subscription | public | Stripe subscription attached to an organization |
AuditLog | public | Immutable event log for compliance and debugging |
ApiKey | public | Scoped API credentials issued per organization |
Content | public | CMS content items (pages, posts, blocks) |
Integration | public | Third-party integration configs per organization |
Project | public | A workspace inside an organization |
pgvector
PostgreSQL's pgvector extension is enabled on every Nebutra database. It powers:
- Semantic search β cosine similarity over
Embeddingvectors in therecsysschema - RAG pipelines β chunked document embeddings stored alongside content
- Recommendation engine β collaborative filtering via ANN (approximate nearest-neighbour) queries
pgvector must be enabled on your PostgreSQL instance before running migrations. Both Neon and Supabase enable it by default. Self-hosted PostgreSQL requires CREATE EXTENSION vector;.
Command reference
| Command | When to use |
|---|---|
pnpm db:generate | After editing schema.prisma β regenerates the Prisma client |
pnpm db:migrate | Create and apply a new migration (development and CI/CD) |
pnpm db:push | Push schema changes without a migration file (local prototyping only) |
pnpm db:studio | Open Prisma Studio at http://localhost:5555 |
pnpm db:seed | Populate the database with development seed data |
Never run pnpm db:push against a production or staging database. It applies schema changes without a migration history, which can cause irreversible data loss.
Multi-tenancy
Every table in the public schema that stores tenant-specific data has a tenantId column. Queries are automatically scoped using PostgreSQL Row-Level Security (RLS) via the withRls helper from @nebutra/tenant. See the RLS guide for details.
How is this guide?
Last updated on