Node Prisma migrations walkthrough

A newsletter signup app walks one PostgreSQL database through an additive Prisma change and a populated table drop without losing the subscriber list. Tokay runs it as one Web Service and rehearses each migration against a copy of your data first.

Last updated July 31, 2026

Use this walkthrough when you want to see the difference between a routine schema update and a release that deserves a human decision. Three Git tags hold the versions, and the setup below turns them into three commits in one standalone repository.

The download contains the final version for inspection. Start the full walkthrough with the Git setup below so you can deploy all three versions in order.

Runtime

Node.js

Framework

Express and Prisma

Service types

Web Service

Resources

PostgreSQL

Required secrets

None

What it does

The Field Notes page collects a name and email, rejects duplicate addresses, and lists the people already reading.

The second version adds Confirm signup beside each unconfirmed reader. Your existing names remain while the new field begins empty.

The final version removes page visit tracking as a privacy cleanup. The page keeps subscriber and confirmation data because those records live in a different table.

Prepare the walkthrough repository

The Tokay examples repository contains many apps. Extract this example at v1 into its own repository before you push it, so Tokay sees only the newsletter app.

git clone https://github.com/tokayio/tokay-examples.git tokay-examples-source
mkdir prisma-walkthrough
git -C tokay-examples-source archive v1 node-prisma-migrations-walkthrough \
  | tar -x -C prisma-walkthrough --strip-components=1
git -C prisma-walkthrough init -b main
git -C prisma-walkthrough add README.md package.json prisma.config.ts prisma src tsconfig.json
git -C prisma-walkthrough commit -m "Start newsletter signups"

Keep tokay-examples-source beside prisma-walkthrough. The later steps copy v2-additive and v3-destructive from that clone.

Start the walkthrough with v1

1. From the prepared prisma-walkthrough repository, choose Add code, then Push with Git in Tokay.
2. Create a repository and follow the Git setup commands shown by Tokay.
3. Push the v1 commit to the remote shown in those instructions.

git push tokay main

4. Choose the detected Web Service and a Project, then choose Deploy.
5. Open the walkthrough Service's Environment page. Confirm the app database for DATABASE_URL.
6. When DATABASE_URL says Good to go, follow the deployment tracker and choose Go Live if that action appears.

Try it

1. Open Field Notes and add yourself. From prisma-walkthrough, replace its files with the additive version, commit them, and push.

git -C ../tokay-examples-source archive v2-additive node-prisma-migrations-walkthrough \
  | tar -x --strip-components=1
git add README.md package.json prisma.config.ts prisma src tsconfig.json
git commit -m "Add signup confirmation"
git push tokay main

Confirm your existing signup after the safe migration goes live.

2. Open Project Settings and change Migration Safety to Strict. Replace the files with the destructive version, commit them, and push.

git -C ../tokay-examples-source archive v3-destructive node-prisma-migrations-walkthrough \
  | tar -x --strip-components=1
git add README.md package.json prisma.config.ts prisma src tsconfig.json
git commit -m "Remove page visit tracking"
git push tokay main

3. Choose Review release and inspect the populated public.PageVisit drop. Apply it with downtime, then reopen Field Notes and confirm your signup remains. In a production Project, the release also shows its restore point under Database snapshots.

An agent sees the same stop as ACTION_REQUIRED with action CONFIRM_RELEASE. The agent must show you the rehearsal evidence and wait for your decision.

What protects your data

The Prisma migration files stay with the code, but each change is tested against a copy of your data before production. This lets you see what the migration will do with the data shape you actually have.

The v2-additive migration only adds a nullable field. Under Normal mode, the successful rehearsal lets this release continue automatically.

Before v3-destructive, you change Migration Safety to Strict. The rehearsal finds a populated table drop and pauses the release. Your production database has not changed at this point.

If you confirm, Tokay takes a restorable production snapshot, applies the migration during the stated downtime window, and starts the new version. The snapshot gives you an explicit recovery option if the result is not what you expected.

How it works

The newsletter page lets you create and confirm signups while Prisma stores them in PostgreSQL. One fictional signup appears only when the list is empty, so it does not return after you add real data.

Every database shape is committed under prisma/migrations. The three Git tags let the same app and database move through a safe additive change and a deliberate destructive change.

You may notice a placeholder URL in prisma.config.ts. Prisma 7 requires a URL while generating the client, even though that step never connects to a database. Migrations and the running app always receive the real DATABASE_URL from Tokay.

Secrets

You do not need to create a secret. Tokay supplies DATABASE_URL from the managed PostgreSQL database you confirm.

Grow from here

Try the Streamlit support dashboard when you want a private team app in front of managed data.

Guide: Deploy database migrations safely