elearning/Backend/.agent/workflows/database-migration.md

description
How to create and run database migrations

Database Migration Workflow

Follow these steps to create and apply database migrations using Prisma.

---

Step 1: Update Prisma Schema

Edit prisma/schema.prisma:

model Course {
  id              Int      @id @default(autoincrement())
  title           Json     // { th: "", en: "" }
  description     Json
  price           Decimal  @db.Decimal(10, 2)
  is_free         Boolean  @default(false)
  have_certificate Boolean @default(false)
  status          CourseStatus @default(DRAFT)
  thumbnail       String?
  
  category_id     Int
  category        Category @relation(fields: [category_id], references: [id])
  
  created_by      Int
  creator         User     @relation(fields: [created_by], references: [id])
  
  chapters        Chapter[]
  instructors     CourseInstructor[]
  enrollments     Enrollment[]
  
  created_at      DateTime @default(now())
  updated_at      DateTime @updatedAt
  deleted_at      DateTime?
  is_deleted      Boolean  @default(false)
  
  @@index([category_id])
  @@index([status])
  @@index([is_deleted])
}

---

Step 2: Create Migration

// turbo Run migration command:

npx prisma migrate dev --name add_course_model

This will:

1. Generate SQL migration file
2. Apply migration to database
3. Regenerate Prisma Client

---

Step 3: Review Migration File

Check generated SQL in prisma/migrations/:

-- CreateTable
CREATE TABLE "Course" (
    "id" SERIAL NOT NULL,
    "title" JSONB NOT NULL,
    "description" JSONB NOT NULL,
    "price" DECIMAL(10,2) NOT NULL,
    "is_free" BOOLEAN NOT NULL DEFAULT false,
    ...
    CONSTRAINT "Course_pkey" PRIMARY KEY ("id")
);

-- CreateIndex
CREATE INDEX "Course_category_id_idx" ON "Course"("category_id");

---

Step 4: Update Prisma Client

// turbo Regenerate client if needed:

npx prisma generate

---

Step 5: Create Seed Data (Optional)

Update prisma/seed.js:

const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

async function main() {
  // Create categories
  const category = await prisma.category.create({
    data: {
      name: { th: 'การเขียนโปรแกรม', en: 'Programming' },
      description: { th: 'หลักสูตรด้านการเขียนโปรแกรม', en: 'Programming courses' }
    }
  });

  // Create test user
  const user = await prisma.user.create({
    data: {
      username: 'instructor1',
      email: 'instructor@example.com',
      password: '$2b$10$...', // hashed password
      role_id: 2 // INSTRUCTOR
    }
  });

  // Create test course
  const course = await prisma.course.create({
    data: {
      title: { th: 'Python สำหรับผู้เริ่มต้น', en: 'Python for Beginners' },
      description: { th: 'เรียนรู้ Python', en: 'Learn Python' },
      price: 990,
      is_free: false,
      category_id: category.id,
      created_by: user.id
    }
  });

  console.log('Seed data created:', { category, user, course });
}

main()
  .catch((e) => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    await prisma.$disconnect();
  });

---

Step 6: Run Seed

// turbo Seed the database:

npx prisma db seed

---

Common Migration Tasks

Add New Field

model Course {
  // ... existing fields
  slug String @unique  // New field
}

// turbo

npx prisma migrate dev --name add_course_slug

Add Index

model Course {
  // ... existing fields
  
  @@index([created_at])  // New index
}

Add Relation

model Lesson {
  // ... existing fields
  
  quiz_id Int?
  quiz    Quiz? @relation(fields: [quiz_id], references: [id])
}

Rename Field

model Course {
  // Old: instructor_id
  created_by Int  // New name
}

Note: Prisma will detect rename and ask for confirmation

---

Production Migration

Step 1: Generate Migration (Dev)

npx prisma migrate dev --name migration_name

Step 2: Commit Migration Files

git add prisma/migrations/
git commit -m "Add migration: migration_name"

Step 3: Deploy to Production

npx prisma migrate deploy

Important: Never use migrate dev in production!

---

Rollback Migration

Option 1: Manual Rollback

# Find migration to rollback
ls prisma/migrations/

# Manually run the down migration (if exists)
psql $DATABASE_URL < prisma/migrations/XXXXXX_migration_name/down.sql

Option 2: Reset Database (Dev Only)

npx prisma migrate reset

Warning: This will delete all data!

---

Troubleshooting

Migration Failed

# Check database status
npx prisma migrate status

# Resolve migration
npx prisma migrate resolve --applied MIGRATION_NAME
# or
npx prisma migrate resolve --rolled-back MIGRATION_NAME

Schema Drift

# Check for drift
npx prisma migrate diff

# Reset and reapply
npx prisma migrate reset

Generate Client Error

# Clear node_modules and reinstall
rm -rf node_modules
npm install

# Regenerate client
npx prisma generate

---

Checklist

• Schema updated in prisma/schema.prisma
• Migration created with descriptive name
• Migration SQL reviewed
• Migration applied successfully
• Prisma Client regenerated
• Seed data updated (if needed)
• Tests updated for new schema
• Migration files committed to git

---

Best Practices

1. Descriptive Names: Use clear migration names

   • ✅ add_course_certificate_field
   • ❌ update_schema

2. Small Migrations: One logical change per migration

3. Review SQL: Always check generated SQL before applying

4. Test First: Test migrations on dev database first

5. Backup: Backup production database before migrating

6. Indexes: Add indexes for frequently queried fields

7. Constraints: Use database constraints for data integrity