# 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.

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.

## Facts

- 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.

## Deploy it

Bring this folder to Tokay any way you like. Paste or upload it in the dashboard, push it with git, or hand it to your AI agent along with [our agent instructions](https://app.tokay.io/llms.txt). Tokay figures out the rest.

Working in Claude, ChatGPT, VS Code, or another MCP client? Connect the [Tokay MCP server](https://tokay.io/docs/platform-mcp) and ask your agent to deploy this example. It signs in through your browser, so there is no token to paste.

New to Tokay? The [getting started guide](https://tokay.io/getting-started) walks you through your first deploy.

## 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.

```sh
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.

```sh
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.

```sh
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.

```sh
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](/examples/python-streamlit-support-dashboard) when you want a private team app in front of managed data.

## Source files

- [package.json](https://tokay.io/examples/src/node-prisma-migrations-walkthrough/package.json)
- [prisma.config.ts](https://tokay.io/examples/src/node-prisma-migrations-walkthrough/prisma.config.ts)
- [prisma/migrations/20260719090000\_init/migration.sql](https://tokay.io/examples/src/node-prisma-migrations-walkthrough/prisma/migrations/20260719090000_init/migration.sql)
- [prisma/migrations/20260719100000\_add\_confirmation/migration.sql](https://tokay.io/examples/src/node-prisma-migrations-walkthrough/prisma/migrations/20260719100000_add_confirmation/migration.sql)
- [prisma/migrations/20260719110000\_remove\_page\_visits/migration.sql](https://tokay.io/examples/src/node-prisma-migrations-walkthrough/prisma/migrations/20260719110000_remove_page_visits/migration.sql)
- [prisma/migrations/migration\_lock.toml](https://tokay.io/examples/src/node-prisma-migrations-walkthrough/prisma/migrations/migration_lock.toml)
- [prisma/schema.prisma](https://tokay.io/examples/src/node-prisma-migrations-walkthrough/prisma/schema.prisma)
- [src/server.ts](https://tokay.io/examples/src/node-prisma-migrations-walkthrough/src/server.ts)
- [tsconfig.json](https://tokay.io/examples/src/node-prisma-migrations-walkthrough/tsconfig.json)

## Download and source

- [Download the complete project](https://tokay.io/examples/downloads/node-prisma-migrations-walkthrough.zip)
- Last updated: 2026-07-31
- Example revision: `52c7b7f`
- [View this revision on GitHub](https://github.com/tokayio/tokay-examples/tree/52c7b7ffd52e157375b08f1f11ff4fbe6c498642/node-prisma-migrations-walkthrough)
- [Deploy database migrations safely](https://tokay.io/use-cases/deploy-database-migrations-safely)