Database

On This Page

Pick a databasePoint DATABASE_URL at a hosted provider or a local Docker container.Schema LayoutHow the Prisma schema is split across domain files.What's ModeledIdentity, billing, AI, and side-effect domains and where they live.How The Models ConnectForeign-key relationships across the four domains.Common WorkflowsMigrate, reset, seed, inspect, and regenerate the client.Migrations In ProductionThe non-interactive migrator and how to run it safely.Seedingbootstrap, demo, and test seed modes.Using The Client In Your CodeImport the singleton prisma client and query as usual.

Pick a database

For the first-run path (URL → env → migrate), use Quickstart. This page covers adapters, schema layout, and day-to-day workflows.

DATABASE_URL="postgresql://<user>:<password>@<host>/<database>"

docker run --name syntaxkit-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=syntaxkit \
  -p 5432:5432 \
  -d postgres:16

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/syntaxkit"

Schema Layout

The Prisma schema is split across several files in packages/database/prisma/ so each domain has a clear home:

What's Modeled

How The Models Connect

The diagram below shows the foreign-key relationships across the four domains.

Product data (Subscription, Chat, AiUsageEvent, and messages via their chat) is org-scoped. Membership (Member) is the access path into an organization. Creator and active-org foreign keys on users and sessions exist for attribution and session context; they are not a second tenancy model.

Common Workflows

Expand the task you're doing.

pnpm db:migrate:dev

pnpm db:migrate:dev

pnpm db:reset

pnpm db:reset:demo

pnpm db:studio

pnpm db:generate

pnpm auth:generate

Migrations In Production

Production deploys use the non-interactive migrator:

pnpm db:migrate:deploy

Two important details:

• The migrator service in docker-compose.yml runs this command for self-hosted Docker deploys. Run it before bringing up web after every schema change.
• pnpm db:migrate:status reports whether the database is in sync with the migrations directory; useful in CI and on deploy targets that do not auto-migrate.

For platform-specific runbooks (Vercel, Fly.io, Render, Docker), see Deployment and Going To Production.

Seeding

prisma db seed runs through packages/database/prisma/seed.ts, which dispatches to one of three modes:

Using The Client In Your Code

Import the singleton client from @syntaxkit/database and write Prisma queries the usual way:

import { prisma } from "@syntaxkit/database";

const orgs = await prisma.organization.findMany({
  where: { members: { some: { userId } } },
});

prisma is a process-wide singleton. The driver adapter is chosen from DATABASE_URL (see Pick a database), so application code never has to know which Postgres it is talking to.

Where To Go Next

Also useful: AI, Deployment, Going To Production, and Conventions.