Skip to main content
Reactive Resume v4 used a different database schema, so you can’t upgrade a v4 installation in place. Instead, you set up a new installation next to it and copy your users and resumes across. This page covers that move. To upgrade an existing v5 installation, see Migrating from v5 instead.
Keep your v4 instance running until every user and resume is in the new installation and you’ve checked the result. It’s your fallback if something goes wrong. Work only on infrastructure and backups you’re authorized to operate.

​
Before you start

You need:
  • Your running v4 instance, and a recent backup of its PostgreSQL database.
  • Access to the v4 database (the source) and to a new, empty PostgreSQL database for the new installation (the target).
  • A plan for the new installation. Self-hosting with Docker is the usual choice.

​
Choose a method

​
Import resumes one by one

The current version reads v4 JSON exports directly and converts them.
1

Export from v4

In your v4 instance, open each resume and export it as JSON.
2

Import into the new installation

Sign in to the new installation (create an account first if needed), select New, then Import a resume, and choose the JSON file. Reactive Resume recognizes the v4 format on its own. See Importing resumes for details.
3

Check and repeat

Look through the imported resume, especially dates and layout, then repeat for the next one.

​
Run the migration scripts

The scripts live in the repository at tag v5.0.20, the last release that includes them. They were written against the database schema of that release, so you create the target database with that release first, run the scripts, and only then start the current version, which brings the data forward with its own migrations.
Don’t run the scripts against a database that a newer release has already set up. They don’t fill in columns added later (such as the sign-in issuer added in v5.2.8), so migrated users could fail to sign in. Starting the current version after the scripts fills those columns in.

​
Prepare the scripts

Install tsx and a .env loader such as dotenvx on the machine that runs the scripts, then check out the tag:
Use this checkout only to run the migration. Your actual installation runs the current release. Create a .env file at the root of the checkout:
.env
Double-check both connection strings. DATABASE_URL is the new target and PRODUCTION_DATABASE_URL is the old v4 source. Swapping them can destroy data. PRODUCTION_DATABASE_URL is used only by these scripts, never by the app.

​
Create the target schema

Apply the v5.0.20 migrations to the empty target database:

​
Migrate users

The script:
  • Reads v4 users in batches and creates matching users in the target.
  • Copies sign-in methods (email and password, Google, GitHub, custom OAuth). Two-factor authentication isn’t copied: every migrated user starts with it turned off.
  • Writes scripts/migration/user-id-map.json, which links each v4 user ID to its new ID. The resume script needs it.
  • Saves progress to scripts/migration/user-progress.json after each batch. If the run stops, run it again to continue from the last saved batch.
It ends with a summary of users created, accounts created, and users skipped.
Migrated two-factor authentication is disabled. Before switching traffic, tell affected users to enable it again on the new installation. Treat the transition as a change to account security.

​
Migrate resumes

The script:
  • Reads v4 resumes in batches, converts each to the new format, and assigns it to the right user through the ID map.
  • Copies view and download statistics, public or private visibility, and the locked state.
  • Saves progress to scripts/migration/resume-progress.json after each batch, and continues from there if you run it again.
It ends with a summary of resumes created, resumes skipped, and errors.
Each script deletes its progress file when it finishes. Keep user-id-map.json as the record of which v4 user became which new user. Don’t re-run the scripts against a populated target to “fix” a problem; review the source backup, the map, and the target first.
These historical scripts register cleanup on normal exit, not on SIGINT. Prefer letting a batch finish before stopping it. After an interruption, retain the progress and ID-map files and verify the last batch before resuming.

​
Start the current version

Point a current Reactive Resume installation at the target database and start it. On startup it applies every migration since v5.0.20, which also fills in the new columns for the migrated users. Watch the logs for Database migrations completed.

​
After the migration

1

Check the data

Sign in as a few users and spot-check their resumes.
2

Test the essentials

Download a resume as PDF, and sign in with email and password and with each social provider you use.
3

Switch traffic

Point your DNS or reverse proxy at the new installation.
4

Retire v4

After a grace period with no problems, shut down the v4 instance.

​
What carries over

People who signed up with email and password keep their password. No reset is needed.
The database stores references to pictures, not the files. Give the new installation access to the same storage (for example the same S3 bucket), or people re-upload their pictures.
Configure the same providers with the same client IDs in the new installation. Custom OAuth now uses a different callback URL, so update your provider as described in Single sign-on (SSO). On the first sign-in, the provider account is linked to the migrated user by email. For custom OAuth, that works only if the user’s email was verified in v4; otherwise the sign-in stops with an “account not linked” error.
Not carried over. Users who had two-factor authentication in v4 sign in with their password alone, and can set it up again in Settings → Account.
v4’s visibility became a public/private flag, a resume’s title became its name, and resume data was reorganized. The scripts and the importer handle these conversions.

​
Recover one person’s resumes later

Sometimes a person changes a resume in v4 after the main migration, or a resume didn’t come across. Handle this as a recovery case rather than re-running the scripts, and never overwrite the resume in the new installation. Keep a private record for each case, outside Git, because it links account and resume identifiers:
  • Case ID and the capture time of the source snapshot.
  • How you verified the person owns the account.
  • Source resume ID and mapped target resume ID, if there is one.
  • Source and target content hashes, and the outcome: no-op, export-copy, or blocked.
1

Confirm a source exists

Check that a source snapshot exists and note when it was taken. Records missing from every available source can’t be reconstructed.
2

Verify ownership and mapping

Verify the requester through your approved account-ownership process, and confirm the old-to-new user mapping. A matching email, resume title, or username alone isn’t proof. Stop if either check is incomplete.
3

Compare without writing

Identical content is a no-op. Content that exists only in the source, or differs, is an export-copy. Missing evidence, mapping, valid data, or source is blocked. Content hashes prove equality only, never ownership or authenticity.
4

Deliver a separate private export

Send the recovered JSON privately through an approved channel, so the person imports it as a new resume. Confirm the delivered hash matches the source.
Contributors can rehearse the comparison with tooling/recovery/compare-resume.ts. It takes one serialized JSON request whose source and target already match the current resume schema, produces a dry-run manifest, and never touches a database or the network. It doesn’t convert raw v4 data; review the converter at tag v5.0.20 for that. Use synthetic data only.

​
Troubleshooting

Put both DATABASE_URL and PRODUCTION_DATABASE_URL in .env and run the scripts through dotenvx run -- (or export the variables yourself).
A user is skipped when their email or username already exists in the target, or when an earlier run already migrated them. The console output gives the reason.
A resume is skipped when its owner isn’t in the user ID map, when the owner already has a resume with the same slug, or when an earlier run already migrated it.
When a v4 resume can’t be parsed, the scripts can create empty default data. Treat that as a failed conversion, not a recovered resume. Keep the source export and import it by hand once you’ve confirmed it’s valid.
Check that you started the current version against the target database after the scripts, so its migrations ran. The startup log shows Database migrations completed.
The scripts work in batches to spare the databases. Run them off-peak, give both databases enough resources, or adjust the batch size in the script files.