Skip to Content
DocumentationGuidesDatabase

Database

I’ll first inspect the @database package files (config, CLI, schema, env) to understand how it’s meant to be used, then I’ll write a concise markdown doc you can drop into your repo.

[5 tools called]

@database/prisma – Usage Guide

This document explains how to use the @database/prisma package for database management and app configuration in this boilerplate.

Installation & Setup

Go to the packages/database directory:

  • Install dependencies (root of repo):
npm install
  • Environment variables:

Copy the example env file and set your database URL:

cd packages/database
cp .env.example .env

Then edit .env:

DIRECT_URL="postgresql://USER:PASSWORD@HOST:5432/postgres"

DIRECT_URL must point to your Postgres (Supabase) instance.

Prisma Configuration

  • Config file: prisma.config.ts

Key parts:

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: {
    url: env("DIRECT_URL"),
  },
  migrations: {
    path: "prisma/migrations",
    seed: "tsx src/seed.ts",
  },
});
  • Prisma uses DIRECT_URL for all DB operations.
  • Migrations live under prisma/migrations.
  • src/seed.ts is the default seeding script.
  • src/cli.ts is the interactive config CLI.

NPM Scripts (from package.json)

Run these from packages/database:

  • Apply production migrations:
npm run db:migrate:deploy
  • Development migrations (interactive):
npm run db:migrate:dev
  • Push schema without migrations (dev only):
npm run db:push
  • Seed database:
npm run db:seed
  • Open Prisma Studio:
npm run studio
  • Generate Prisma client:
npm run generate
  • Run interactive config CLI:
npm run cli

Seeding App Configs (src/seed.ts)

src/seed.ts:

  • Connects to Postgres via @prisma/adapter-pg using DIRECT_URL.
  • Clears existing appConfig entries with:
await prisma.appConfig.deleteMany({});
  • Inserts a predefined set of configs (Apple, Google, Twitter, RevenueCat, OneSignal, PostHog, Sentry, API base URL, app.version, app.campaign) using ConfigType enums.

Usage:

cd packages/database
npm run db:seed

This will wipe and recreate all appConfig rows. Comment out deleteMany if you need to preserve existing data.

Interactive App Config CLI (src/cli.ts)

The CLI provides a TUI to manage appConfig records.

Prerequisites

  • .env with a valid DIRECT_URL
  • Generated Prisma client at prisma/generated/client (run npm run generate if missing)

Start the CLI

cd packages/database
npm run cli

Features

  • Insert new config

    • Prompts:
      • key (string, required)
      • value (string, required)
      • type (one of: STRING, NUMBER, BOOLEAN, JSON, URL, EMAIL, DATE)
      • description (optional)
    • Validates:
      • NUMBER → numeric
      • BOOLEAN → true/false/1/0/yes/no
      • JSON → valid JSON
      • URL → valid URL
      • EMAIL → valid email format
      • DATE → parsable date string
    • Confirms before insert and writes to appConfig.

  • View all configs

    • Lists all configs in a table:
      • KEY, TYPE, truncated VALUE, truncated DESCRIPTION
    • Optionally allows selecting a key to view full details (including formatted JSON values and timestamps).

  • Exit

    • Cleanly terminates the process.

Typical Workflow

  • Initial setup for a new environment:

    1. Configure .env with DIRECT_URL.
    2. Run npm run db:migrate:deploy (or db:migrate:dev in development).
    3. Run npm run db:seed to populate base appConfig entries.

  • Managing runtime configs later:

    1. Run npm run cli.
    2. Use “Insert new config” to add new keys.
    3. Use “View all configs” to inspect existing values.

When to Touch @database/prisma

  • Modify prisma/schema.prisma when:

    • Adding/removing tables or fields.
    • Changing the shape of appConfig or other models.

  • Run migrations / generate client after schema changes:

    • npm run db:migrate:dev (dev) or db:migrate:deploy (prod).
    • npm run generate to update the typed client.

  • Use seed.ts and cli.ts to keep application configuration centralized and consistent across environments.

UI ComponentsConfig Environment