Skip to main content

Overview

KAIU Natural Living uses Prisma for database migrations and schema management. This guide covers creating, applying, and managing migrations.

Migration Strategy

The project currently uses prisma db push for development, which:
  • Syncs schema changes directly to the database
  • Does not create migration files
  • Best for rapid prototyping
For production deployments, you should use Prisma Migrate for version-controlled schema changes.

Development Workflow

Making Schema Changes

1
Edit the Schema
2
Modify prisma/schema.prisma:
3
model Product {
  id          String   @id @default(uuid())
  sku         String   @unique
  name        String
  // Add new field:
  featured    Boolean  @default(false)
  // ...
}
4
Push to Database
5
npx prisma db push
6
This command:
7
  • Analyzes schema changes
  • Generates SQL statements
  • Applies changes to the database
  • Regenerates Prisma Client
  • 8
    Verify Changes
    9
    npx prisma studio
    
    10
    Inspect the updated schema visually.

    Production Workflow (Prisma Migrate)

    For production environments, use formal migrations:

    Creating Migrations

    1
    Generate Migration
    2
    npx prisma migrate dev --name add_featured_to_products
    
    3
    This:
    4
  • Creates migration files in prisma/migrations/
  • Applies the migration to your dev database
  • Updates Prisma Client
  • 5
    Review Migration Files
    6
    cat prisma/migrations/20260304_add_featured_to_products/migration.sql
    
    7
    Ensure the SQL is correct before deploying.
    8
    Commit Migration
    9
    git add prisma/migrations
    git commit -m "Add featured field to products"
    

    Applying Migrations

    Production Deployment

    npx prisma migrate deploy
    
    Use this in CI/CD pipelines and production environments. It:
    • Applies pending migrations
    • Does not prompt for confirmation
    • Safe for automation

    Development Sync

    If another developer created migrations:
    git pull
    npx prisma migrate dev
    

    Common Migration Tasks

    Add a New Model

    model Newsletter {
      id        String   @id @default(uuid())
      email     String   @unique
      createdAt DateTime @default(now())
    }
    
    npx prisma db push
    # OR for production:
    npx prisma migrate dev --name add_newsletter_model
    

    Add a Relation

    model Product {
      // ... existing fields
      reviews Review[]
    }
    
    model Review {
      id        String   @id @default(uuid())
      productId String
      product   Product  @relation(fields: [productId], references: [id])
      rating    Int
      comment   String?
      createdAt DateTime @default(now())
    }
    

    Rename a Field

    model User {
      id       String @id @default(uuid())
      fullName String // renamed from 'name'
    }
    
    npx prisma db push
    
    Prisma will detect the rename if the type matches, otherwise it will drop and recreate.

    Add an Index

    model Order {
      id         String @id @default(uuid())
      customerEmail String
      
      @@index([customerEmail])
    }
    

    Make a Field Optional/Required

    model Product {
      id          String  @id @default(uuid())
      description String? // Made optional
      name        String  // Required
    }
    

    PostgreSQL Specific Features

    Enable Extensions

    For pgvector (AI embeddings):
    CREATE EXTENSION IF NOT EXISTS vector;
    
    Run this manually before pushing schema with vector fields.

    Using Unsupported Types

    For PostgreSQL-specific types not directly supported by Prisma:
    model KnowledgeBase {
      id        String @id @default(uuid())
      embedding Unsupported("vector(1536)")
    }
    

    Seeding After Migrations

    After schema changes, reseed the database:
    npm run seed
    
    See Database Seeding for details.

    Rollback Strategies

    Development Rollback

    Reset the entire database:
    npx prisma migrate reset
    
    Warning: This deletes all data!

    Production Rollback

    Create a new migration that reverses changes:
    npx prisma migrate dev --name revert_featured_field
    
    Manually write SQL to undo the previous migration.

    Migration Best Practices

    1. Test Locally First - Always test migrations on development database
    2. Backup Production - Create database backup before applying migrations
    3. Small Changes - Keep migrations focused and atomic
    4. Descriptive Names - Use clear migration names: add_user_roles, create_reviews_table
    5. Review Generated SQL - Check migration files for correctness
    6. Version Control - Commit migration files with related code changes

    Troubleshooting

    Migration Out of Sync

    If migrations are out of sync:
    npx prisma migrate resolve --applied <migration_name>
    # OR
    npx prisma migrate resolve --rolled-back <migration_name>
    

    Schema Drift

    If database schema differs from Prisma schema:
    npx prisma db pull
    
    This introspects the database and updates your schema file.

    Failed Migration

    npx prisma migrate resolve --rolled-back <failed_migration>
    npx prisma migrate deploy
    

    Environment-Specific Migrations

    Development

    npx prisma db push
    
    Fast iteration without migration history.

    Staging/Production

    npx prisma migrate deploy
    
    Controlled migration application from version control.

    Next Steps

    Build docs developers (and LLMs) love