Keep/MIGRATION_GUIDE.md

Migration Guide: Tags → Notebooks

Project: Keep - Notebooks & Labels Contextuels Date: 2026-01-11 Status: READY FOR EXECUTION Version: 1.0

---

Table of Contents

1. Overview
2. Pre-Migration Checklist
3. Migration Process
4. Post-Migration Verification
5. Rollback Procedure
6. Troubleshooting

---

Overview

What This Migration Does

This migration transforms Keep's flat tags system into a contextual notebooks system:

✅ Creates a new Notebook model for organizing notes ✅ Updates the Label model to belong to notebooks (contextual) ✅ Updates the Note model to optionally belong to a notebook ✅ Preserves all existing data (zero data loss) ✅ Maintains backward compatibility (existing features still work)

What Changes

Before	After
Labels are global (shared across all notes)	Labels are contextual to notebooks
Labels belong to users	Labels belong to notebooks
No concept of notebooks	Notes can be organized into notebooks
All labels in one flat list	Labels isolated per notebook

What Doesn't Change

• ✅ All existing notes are preserved
• ✅ All existing labels are preserved
• ✅ Notes remain accessible (in "Notes générales" / Inbox)
• ✅ No breaking changes to the UI
• ✅ Existing features continue to work

---

Pre-Migration Checklist

1. Backup Database

CRITICAL: Always backup before migration!

# Navigate to project directory
cd D:\dev_new_pc\Keep

# Backup SQLite database
cp keep-notes/prisma/dev.db keep-notes/prisma/dev.db.backup-$(date +%Y%m%d)

# Verify backup exists
ls -lh keep-notes/prisma/dev.db.backup-*

2. Stop Application

Stop the development server to prevent conflicts:

# Stop Next.js dev server if running
# Press Ctrl+C in the terminal or run:
pkill -f "next dev"

3. Review Migration Plan

Understand what will happen:

• I have a database backup
• I understand that labels will be moved to a "Labels Migrés" notebook
• I understand that notes will remain in "Notes générales" (Inbox)
• I know how to rollback if needed
• I have 5-10 minutes of downtime scheduled

4. Check Prisma Status

Ensure Prisma is properly installed:

cd keep-notes
npx prisma --version
# Should show: 5.22.0 or higher

# Generate Prisma client (if not already done)
npx prisma generate

---

Migration Process

Step 1: Apply Prisma Schema Changes

The Prisma schema has already been updated with the new models.

Generate and apply the migration:

cd keep-notes

# Create migration
npx prisma migrate dev --name add_notebooks

# This will:
# 1. Update the database schema
# 2. Create the Notebook table
# 3. Add notebookId to Label and Note tables
# 4. Create indexes for performance

Expected Output:

✔ Generated Prisma Client
✔ The following migration has been created and applied from new schema changes:

migrations/
  └─ 20260111XXXXXX_add_notebooks/
    └─ migration.sql

Applying migration `20260111XXXXXX_add_notebooks`

The following migration(s) have been created and applied from new schema changes:

migrations/
  └─ 20260111XXXXXX_add_notebooks/
    └─ migration.sql

Step 2: Verify Schema Applied

Check that the new tables exist:

# Open SQLite database
sqlite3 keep-notes/prisma/dev.db

# List tables
.tables

# You should see:
# - Notebook (NEW)
# - Label (MODIFIED)
# - Note (MODIFIED)
# - _NoteToLabel (NEW - junction table)

# Exit SQLite
.quit

Step 3: Run Data Migration Script

Migrate the existing labels to the default notebook:

# From project root
npx tsx scripts/migrate-to-notebooks.ts

Expected Output:

🚀 Starting migration to notebooks...

📊 Fetching users...
✅ Found 1 user(s)

👤 Processing user: ramez@example.com (user-123)

  📁 Creating "Labels Migrés" notebook...
  ✅ Created notebook: migrate-user-123

  🏷️  Migrating labels...
  ✅ Migrated 15 label(s)
  ℹ️  User has 47 note(s) (will remain in "Notes générales")

============================================================

✅ Migration complete!

📊 Summary:
  Users processed:   1
  Notebooks created: 1
  Labels migrated:   15
  Notes affected:    47 (all remain in Inbox)

✨ Migration successful!

📌 Next steps:
  1. Test the application to ensure everything works
  2. Users can now organize their notes into notebooks
  3. Users can move labels from "Labels Migrés" to new notebooks
  4. Consider deleting old labels field from Note model after verification

Step 4: Verify Migration Success

Run the verification queries:

sqlite3 keep-notes/prisma/dev.db

# Check notebooks exist
SELECT COUNT(*) FROM "Notebook";
# Should be: 1 (or more if multiple users)

# Check labels have notebookId
SELECT COUNT(*) FROM "Label" WHERE notebookId != '';
# Should match your label count

# Check notes are still accessible
SELECT COUNT(*) FROM "Note";
# Should match your note count

# Verify notes are in Inbox (notebookId is NULL)
SELECT COUNT(*) FROM "Note" WHERE notebookId IS NULL;
# Should be all notes

.quit

---

Post-Migration Verification

1. Start Development Server

cd keep-notes
npm run dev

2. Test Application Functionality

Open http://localhost:3000 and verify:

Core Functionality

• Homepage loads without errors
• All notes are visible (in "Notes générales")
• Can create new notes
• Can edit existing notes
• Can delete notes
• Search works

Labels

• Labels are still visible on notes
• Can add labels to notes
• Can remove labels from notes
• Labels show the correct colors

Notebooks (NEW)

• "Labels Migrés" notebook exists in sidebar
• Can create a new notebook
• Can rename notebooks
• Can delete notebooks
• Can move notes between notebooks

3. Check Console for Errors

Open browser DevTools (F12) and check:

Console: No errors
Network: All requests return 200

4. Verify Data Integrity

sqlite3 keep-notes/prisma/dev.db

# No orphaned labels (all labels have notebookId)
SELECT COUNT(*) FROM "Label" WHERE notebookId = '' OR notebookId IS NULL;
# Should be: 0

# No orphaned notebook references (all notebookIds reference existing notebooks)
SELECT COUNT(*) FROM "Note"
WHERE notebookId IS NOT NULL
  AND notebookId NOT IN (SELECT id FROM "Notebook");
# Should be: 0

.quit

---

Rollback Procedure

When to Rollback

Rollback if you encounter:

• ❌ Data corruption
• ❌ Application crashes
• ❌ Critical functionality broken
• ❌ Performance severe degradation

How to Rollback

Step 1: Stop Application

pkill -f "next dev"

Step 2: Run Rollback Script

# DRY RUN FIRST (see what will happen)
npx tsx scripts/rollback-notebooks.ts --dry-run

# ACTUAL ROLLBACK (requires --confirm)
npx tsx scripts/rollback-notebooks.ts --confirm

Step 3: Restore Database Backup

cd keep-notes/prisma

# Find your backup
ls -lh dev.db.backup-*

# Restore from backup
cp dev.db.backup-YYYYMMDD dev.db

Step 4: Restart Application

cd keep-notes
npm run dev

Verify Rollback Success

• Application starts without errors
• All notes are accessible
• Labels work as before (flat list)
• No notebooks exist in database

---

Troubleshooting

Issue: "Prisma migrate fails with foreign key error"

Cause: Old data conflicts with new schema constraints

Solution:

# 1. Check for data that violates constraints
sqlite3 keep-notes/prisma/dev.db

# Find labels without userId
SELECT * FROM "Label" WHERE userId IS NULL;

# 2. Fix data manually
UPDATE "Label" SET userId = 'YOUR_USER_ID' WHERE userId IS NULL;

# 3. Re-run migration
npx prisma migrate dev --name add_notebooks

Issue: "Migration script hangs"

Cause: Large dataset or database lock

Solution:

# 1. Check database is not locked
sqlite3 keep-notes/prisma/dev.db "PRAGMA database_list;"

# 2. Kill any hanging processes
pkill -f "node"
pkill -f "prisma"

# 3. Try again
npx tsx scripts/migrate-to-notebooks.ts

Issue: "Labels disappear after migration"

Cause: Labels migrated to "Labels Migrés" notebook but UI doesn't show them

Solution:

1. Check that "Labels Migrés" notebook exists
2. Verify labels have correct notebookId
3. Refresh the page (hard refresh: Ctrl+Shift+R)
4. Check browser console for errors

Issue: "Performance degradation after migration"

Cause: Missing indexes or inefficient queries

Solution:

# Rebuild indexes
sqlite3 keep-notes/prisma/dev.db "REINDEX;"

# Analyze database for query optimization
sqlite3 keep-notes/prisma/dev.db "ANALYZE;"

# If still slow, check slow queries
# Add more indexes if needed

Issue: "Cannot create notebook - 'notebookId' is required"

Cause: Label table has NOT NULL constraint on notebookId

Solution:

This is expected behavior. Labels must belong to a notebook.

1. Create a notebook first
2. Then create labels within that notebook

---

Post-Migration Cleanup (Optional)

After verifying everything works, you can clean up deprecated fields:

1. Remove Deprecated Label.userId Field

⚠️ ONLY DO THIS AFTER VERIFICATION (1-2 weeks later)

// prisma/schema.prisma

model Label {
  id        String   @id @default(cuid())
  name      String
  color     String   @default("gray")
  notebookId String
  notebook  Notebook @relation(fields: [notebookId], references: [id], onDelete: Cascade)
  notes     Note[]
  // REMOVE THESE TWO LINES:
  // userId    String?
  // user      User?    @relation(fields: [userId], references: [id], onDelete: Cascade)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@unique([notebookId, name])
  @@index([notebookId])
}

Then run:

npx prisma migrate dev --name remove_label_user_id

2. Remove Deprecated Note.labels Field

⚠️ ONLY DO THIS AFTER MIGRATING ALL LABEL-NOTE RELATIONS

// prisma/schema.prisma

model Note {
  // ... other fields
  // REMOVE THIS LINE:
  // labels    String?   // DEPRECATED: Array of label names stored as JSON string

  // Keep the new relation:
  labelRelations Label[]
}

---

Summary

Migration Checklist

Before Migration:

• Database backed up
• Application stopped
• Migration plan reviewed
• Prisma client generated

During Migration:

• Prisma schema applied
• Data migration script run
• No errors in console
• Statistics verified

After Migration:

• Application tested
• All notes accessible
• Labels work correctly
• Notebooks functional
• No performance issues

Success Metrics

• ✅ Zero data loss
• ✅ All existing functionality works
• ✅ New notebooks feature works
• ✅ No errors in console
• ✅ Performance acceptable (< 300ms queries)

Support

If you encounter issues not covered in this guide:

1. Check the browser console for errors
2. Check the server logs for stack traces
3. Verify database integrity with SQLite queries
4. Try rollback if critical
5. Contact the development team

---

Document Status: ✅ COMPLETE Ready for Migration: YES Estimated Downtime: 5-10 minutes Rollback Time: 2-5 minutes

---

Last Updated: 2026-01-11 Author: Winston (Architect AI Agent)