Skip to main content

​
Overview

This guide walks you through migrating your Reactive Resume installation from v4 to v5. The migration process involves setting up a new v5 instance alongside your existing v4 instance, then transferring your users and resumes to the new system.
Keep your v4 instance running until you have successfully migrated all data to v5 and verified everything works correctly. This ensures you have a fallback in case anything goes wrong during the migration.

​
Prerequisites

Before starting the migration, ensure you have:

Running v4 Instance

Your existing Reactive Resume v4 instance should be running and accessible.

New v5 Instance

A fresh Reactive Resume v5 instance set up and running. Follow the Self-Hosting with Docker guide if you haven’t done this yet.

Database Access

Access to both your v4 PostgreSQL database (source) and v5 PostgreSQL database (target).

Backup

A recent backup of your v4 database. Always backup before any migration.

​
Choosing a Migration Method

The best migration approach depends on the size of your instance:

Manual Migration

Best for: Small instances with a handful of resumes.Uses the built-in Import Dialog to manually convert resumes one at a time.

Automated Migration

Best for: Large instances with many users and resumes.Uses migration scripts to batch-process all users and resumes automatically.

​
Manual Migration (Small Instances)

If you have only a few resumes to migrate, the simplest approach is to use the Import Dialog feature in v5.
1

Export from v4

In your v4 instance, go to each resume and export it as JSON. This creates a portable file containing all your resume data.
2

Import into v5

In your new v5 instance:
  1. Log in or create a new account
  2. Click Create Resume or use the Import option
  3. Select the Reactive Resume v4 format
  4. Upload your exported JSON file
The import process automatically converts the v4 format to v5.
3

Verify and repeat

Review the imported resume to ensure all data transferred correctly. Repeat for each resume you need to migrate.
The Import Dialog handles the schema conversion automatically, so you don’t need to worry about format differences between v4 and v5.

​
Automated Migration (Large Instances)

For instances with many users and resumes, use the migration scripts to automate the process. The migration happens in two phases: first users, then resumes.

​
Requirements

To run the migration scripts, you need the following installed on your host machine:

Node.js Runtime

tsx - TypeScript execution environment. Install globally with:
npm install -g tsx

Environment Loader

dotenvx (or any tool to load .env files). Install globally with:
npm install -g @dotenvx/dotenvx
Alternatively, you can use dotenv, direnv, or export the variables manually.

Reactive Resume Source Code

Clone the Reactive Resume repository to access the migration scripts:
git clone https://github.com/amruthpillai/reactive-resume.git
cd reactive-resume
pnpm install

​
Environment Setup

Create a .env file in the root of the repository with the following variables:
.env
# Connection string to your NEW v5 PostgreSQL database (target)
DATABASE_URL="postgresql://user:password@localhost:5432/reactive_resume_v5"

# Connection string to your OLD v4 PostgreSQL database (source)
PRODUCTION_DATABASE_URL="postgresql://user:password@localhost:5432/reactive_resume_v4"
Double-check your connection strings! DATABASE_URL should point to your new v5 database and PRODUCTION_DATABASE_URL should point to your old v4 database. Mixing these up could cause data loss.

​
Step 1: Migrate Users

The user migration script transfers all user accounts, authentication data, and two-factor settings from v4 to v5. 
dotenvx run -- tsx scripts/migration/user.ts
What this script does:
  • Fetches users in batches from the v4 database
  • Creates corresponding user accounts in the v5 database
  • Migrates authentication providers (email, Google, GitHub, custom OAuth)
  • Preserves two-factor authentication settings and backup codes
  • Creates a mapping file (scripts/migration/user-id-map.json) that links old user IDs to new ones
The script saves progress automatically. If interrupted (Ctrl+C), you can run it again and it will resume from where it left off.
Expected output: 
⌛ Starting user migration...
📥 Fetching users batch from production database (OFFSET 0)...
📋 Found 1000 users in this batch.
📝 Preparing to bulk insert 1000 users...
✅ Bulk inserted 1000 users in 245.3 ms (avg 0.2 ms/user)
💾 Progress saved at offset 1000
📦 Processed 1000 users so far...

📊 Migration Summary:
   Users created: 1000
   Accounts created: 1000
   Two-factor entries created: 50
   Skipped (already exist): 0
⏱️  Total migration time: 1234.5 ms (1.23 seconds)
✅ User migration complete!

​
Step 2: Migrate Resumes

After users are migrated, run the resume migration script. This script depends on the user ID mapping created in the previous step. 
dotenvx run -- tsx scripts/migration/resume.ts
What this script does:
  • Fetches resumes in batches from the v4 database
  • Converts each resume from v4 format to v5 format automatically
  • Links resumes to the correct users using the ID mapping
  • Migrates resume statistics (views, downloads)
  • Preserves visibility settings (public/private) and lock status
Like the user script, the resume migration also saves progress and can be resumed if interrupted.
Expected output: 
⌛ Starting resume migration...
📥 Fetching resumes batch from production database (OFFSET 0)...
📋 Found 2500 resumes in this batch.
📝 Preparing to bulk insert 2500 resumes...
✅ Bulk inserted 2500 resumes in 892.1 ms (avg 0.4 ms/resume)
💾 Progress saved at offset 2500
📦 Processed 2500 resumes so far...

📊 Migration Summary:
   Resumes created: 2500
   Statistics created: 2500
   Skipped (userId not found or already exist): 0
   Errors: 0
⏱️  Total migration time: 5678.9 ms (5.68 seconds)
✅ Resume migration complete!

​
Progress and Recovery

Both migration scripts support graceful shutdown and resume:
  • Progress files: scripts/migration/user-progress.json and scripts/migration/resume-progress.json track the current migration state
  • User ID mapping: scripts/migration/user-id-map.json maps v4 user IDs to v5 user IDs
  • Graceful shutdown: Press Ctrl+C to stop the migration safely. Progress is saved before exit.
  • Resume migration: Run the script again to continue from where you left off
If you need to restart the migration from scratch, delete the progress files and the user ID mapping file before running the scripts again.

​
Post-Migration Steps

After completing the migration:
1

Verify data integrity

Log into your v5 instance and spot-check several user accounts and resumes to ensure data transferred correctly.
2

Test functionality

  • Create a test resume and export it as PDF
  • Verify social logins work (if configured)
  • Check that two-factor authentication works for migrated users
3

Update DNS/Proxy

Once verified, update your DNS records or reverse proxy to point to the new v5 instance.
4

Decommission v4

After confirming everything works and allowing a grace period, you can safely shut down your v4 instance.

​
Important Notes

Users who signed up with email/password can continue using their existing passwords. No password reset is required after migration.
User profile pictures (avatars) are stored as references in the database. If you were using S3 storage, ensure your v5 instance has access to the same bucket, or users may need to re-upload their avatars.
Similar to profile pictures, any images embedded in resumes need to be accessible from your v5 instance. Consider migrating your storage bucket or updating references as needed.
If you’re using custom OAuth providers, ensure the same providers are configured in v5 with matching client IDs. Users authenticate with the same provider ID, so mismatched configurations will cause login failures.
The v5 schema has some changes from v4:
  • visibility (public/private) is now isPublic (boolean)
  • Resume title is now name
  • Some resume data fields have been reorganized
The migration scripts handle these conversions automatically.

​
Troubleshooting

Ensure your .env file contains both DATABASE_URL and PRODUCTION_DATABASE_URL, and that you’re using a tool like dotenvx to load them before running the script.
Users are skipped if:
  • Their email already exists in the v5 database
  • Their username already exists in the v5 database
  • They were already migrated in a previous run
Check the console output for skip reasons.
Resumes are skipped if:
  • The associated user wasn’t migrated (user ID not in mapping file)
  • A resume with the same slug already exists for that user
  • They were already migrated in a previous run
If a resume can’t be parsed from v4 format, it will be created with default empty data. Check the console output for warnings about specific resumes, and consider manually importing those using the Import Dialog.
The scripts process data in batches to avoid overwhelming the database. For very large instances:
  • Consider running the migration during off-peak hours
  • Ensure both databases have adequate resources
  • The batch size can be adjusted in the script files if needed